analyzing-influxdb

name	analyzing-influxdb
description	Use when working with Influxdb — influxDB bucket management, Flux query analysis, task management, retention policies, and performance monitoring.
connection_type	influxdb
preload	false

InfluxDB Analysis Skill

Analyze and optimize InfluxDB instances with safe, read-only operations.

MANDATORY: Two-Phase Execution

You MUST follow this two-phase pattern. Skipping Phase 1 causes hallucinated bucket/measurement names.

Phase 1: Discovery (ALWAYS run first)

#!/bin/bash

# 1. List organizations (InfluxDB 2.x)
influx org list

# 2. List buckets
influx bucket list

# 3. List measurements in a bucket
influx query 'import "influxdata/influxdb/schema"
schema.measurements(bucket: "my_bucket")'

# 4. List field keys for a measurement
influx query 'import "influxdata/influxdb/schema"
schema.measurementFieldKeys(bucket: "my_bucket", measurement: "my_measurement")'

# 5. List tag keys
influx query 'import "influxdata/influxdb/schema"
schema.measurementTagKeys(bucket: "my_bucket", measurement: "my_measurement")'

# 6. Sample data
influx query 'from(bucket: "my_bucket")
  |> range(start: -1h)
  |> filter(fn: (r) => r._measurement == "my_measurement")
  |> limit(n: 5)'

Phase 1 outputs:

• Organizations and buckets
• Measurements with field and tag keys
• Sample data to confirm schema

Phase 2: Analysis (only after Phase 1)

Only reference buckets, measurements, fields, and tags confirmed in Phase 1.

Shell Script Patterns

Helper Function

#!/bin/bash

# Core Flux query runner — always use this
influx_query() {
    local query="$1"
    influx query --org "${INFLUX_ORG}" "$query"
}

# InfluxDB API helper
influx_api() {
    local endpoint="$1"
    curl -s -H "Authorization: Token ${INFLUX_TOKEN}" \
        "http://${INFLUX_HOST:-localhost}:8086$endpoint"
}

# InfluxQL (1.x compat)
influx_v1() {
    local query="$1"
    curl -s -G "http://${INFLUX_HOST:-localhost}:8086/query" \
        --data-urlencode "q=$query" \
        -H "Authorization: Token ${INFLUX_TOKEN}"
}

Anti-Hallucination Rules

• NEVER reference a bucket without confirming via influx bucket list
• NEVER reference measurement names without discovering via schema.measurements()
• NEVER assume field or tag keys — always check via schema functions
• NEVER guess retention periods — check bucket configuration
• NEVER assume task names — list tasks first

Safety Rules

• READ-ONLY ONLY: Use only from(), schema.*, influx query, API GET endpoints
• FORBIDDEN: to(), influx delete, influx bucket delete, influx write without explicit user request
• ALWAYS bound queries with range() — unbounded queries scan all data
• Use short time ranges for initial exploration, then expand
• Limit output with |> limit(n: 100) on exploration queries

Common Operations

Bucket Overview

#!/bin/bash
echo "=== Buckets ==="
influx bucket list --json | jq '.[] | {name, id, retentionPeriod: (.retentionRules[0].everySeconds // 0 | . / 86400 | tostring + " days"), orgID}'

echo ""
echo "=== Measurements per Bucket ==="
for BUCKET in $(influx bucket list --json | jq -r '.[].name' | grep -v _); do
    echo "--- $BUCKET ---"
    influx_query "import \"influxdata/influxdb/schema\"
    schema.measurements(bucket: \"$BUCKET\")" 2>/dev/null
done

Task Management

#!/bin/bash
echo "=== Tasks ==="
influx task list --json | jq '.[] | {name, id, status, every, lastRunStatus: .latestCompleted}'

echo ""
echo "=== Task Run History ==="
TASK_ID="${1:-}"
if [ -n "$TASK_ID" ]; then
    influx task run list --task-id "$TASK_ID" --json | jq '.[] | {runID: .id, status, scheduledFor, startedAt, finishedAt}'
fi

echo ""
echo "=== Failed Tasks ==="
influx task list --json | jq '[.[] | select(.latestCompleted != null)] | .[] | {name, status}'

Query Performance Analysis

#!/bin/bash
BUCKET="${1:-my_bucket}"

echo "=== Cardinality Check ==="
influx_query "import \"influxdata/influxdb\"
influxdb.cardinality(bucket: \"$BUCKET\", start: -24h)"

echo ""
echo "=== Series Count by Measurement ==="
influx_query "import \"influxdata/influxdb/schema\"
schema.measurements(bucket: \"$BUCKET\")
  |> limit(n: 20)"

echo ""
echo "=== Tag Value Cardinality ==="
influx_query "import \"influxdata/influxdb/schema\"
schema.measurementTagValues(bucket: \"$BUCKET\", measurement: \"my_measurement\", tag: \"host\")
  |> count()"

Retention & Storage

#!/bin/bash
echo "=== Bucket Retention Policies ==="
influx bucket list --json | jq '.[] | {name, retentionSeconds: .retentionRules[0].everySeconds, retentionDays: ((.retentionRules[0].everySeconds // 0) / 86400)}'

echo ""
echo "=== Storage Stats (API) ==="
influx_api "/api/v2/orgs/${INFLUX_ORG_ID}/usage" 2>/dev/null || echo "Usage API not available"

echo ""
echo "=== Shard Info (if available) ==="
influx_v1 "SHOW SHARDS" 2>/dev/null

Output Format

Present results as a structured report:

Analyzing Influxdb Report
═════════════════════════
Resources discovered: [count]

Resource       Status    Key Metric    Issues
──────────────────────────────────────────────
[name]         [ok/warn] [value]       [findings]

Summary: [total] resources | [ok] healthy | [warn] warnings | [crit] critical
Action Items: [list of prioritized findings]

Target ≤50 lines of output. Use tables for multi-resource comparisons.

Counter-Rationalizations

Shortcut	Counter	Why
"I'll skip discovery and check known resources"	Always run Phase 1 discovery first	Resource names change, new resources appear — assumed names cause errors
"The user only asked for a quick check"	Follow the full discovery → analysis flow	Quick checks miss critical issues; structured analysis catches silent failures
"Default configuration is probably fine"	Audit configuration explicitly	Defaults often leave logging, security, and optimization features disabled
"Metrics aren't needed for this"	Always check relevant metrics when available	API/CLI responses show current state; metrics reveal trends and intermittent issues
"I don't have access to that"	Try the command and report the actual error	Assumed permission failures prevent useful investigation; actual errors are informative

Common Pitfalls

• Unbounded range: Queries without range() scan entire bucket history — always specify start time
• High cardinality: Too many unique tag values causes memory issues — check cardinality before querying
• Tags vs fields: Tags are indexed (fast to filter), fields are not — do not store high-cardinality data as tags
• Task scheduling: Tasks have minimum interval of 1s in OSS, 1m in Cloud — check limits
• Schema-on-write: InfluxDB does not enforce schema — inconsistent field types cause query errors
• Downsampling: Use continuous queries or tasks for downsampling — querying raw high-resolution data is expensive