Skip to content

cloudthinker-ai/CloudSkills / skills/connections/analyzing-influxdb

analyzing-influxdb

Verified

Use when working with Influxdb — influxDB bucket management, Flux query analysis, task management, retention policies, and performance monitoring.

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

ShortcutCounterWhy
"I'll skip discovery and check known resources"Always run Phase 1 discovery firstResource names change, new resources appear — assumed names cause errors
"The user only asked for a quick check"Follow the full discovery → analysis flowQuick checks miss critical issues; structured analysis catches silent failures
"Default configuration is probably fine"Audit configuration explicitlyDefaults often leave logging, security, and optimization features disabled
"Metrics aren't needed for this"Always check relevant metrics when availableAPI/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 errorAssumed 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
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 192kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 192kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 192kUpdated Claude CodeCodexVerifiedInstall