thanos-skills

thanos-skills

Claude Code skills for CNCF Thanos, Prometheus, and PromQL. Query metrics across multi-region Prometheus through a Thanos Querier, discover labels and stores, debug empty PromQL results, and inspect alerts — without hand-writing every curl.

You ask in plain language ("P99 latency for checkout across all regions, last hour"); the skill talks to the Thanos HTTP API, writes the PromQL, and hands the result back to Claude to interpret.

Contents

• What it does
• What a session looks like
• Available skills
• Install
• Connecting to Thanos
• Environment variables
• Security
• Data flow & privacy
• Repository topics
• License

What it does

• Query metrics across multiple Prometheus instances through Thanos (instant & range queries).
• Compare latency, error rate, availability, and saturation across regions or clusters.
• Discover label names, label values, metric names, and connected Thanos stores.
• Diagnose empty results caused by missing stores, upload delay, label mismatch, or stale data.
• Inspect active alerts, rules, build/runtime info, flags, and TSDB/cardinality status.

What a session looks like

You:    What's the P99 latency for the checkout service across all regions in the last hour?

Claude: → checks /api/v1/labels to confirm the metric and `region` label exist
        → runs:
            histogram_quantile(0.99,
              sum by (le, region) (
                rate(http_request_duration_seconds_bucket{service="checkout"}[5m])))
        → returns a per-region breakdown and flags us-west-2 as the outlier (412ms vs ~180ms)

More prompts that trigger the skill:

• "Show me which stores are connected to Thanos."
• "Discover all label values for region in the last 24h."
• "Why does this Thanos query return empty results?"
• "List active alerts from Thanos Ruler."
• "Compare 5xx error rate by Kubernetes cluster."
• "Find whether this metric exists in the store gateway or only in sidecars."

Available skills

Install

Via skills.sh

# all skills
npx skills add Yusin0903/thanos-skills

# only the query skill
npx skills add Yusin0903/thanos-skills --skill thanos-query

Via git clone

git clone https://github.com/Yusin0903/thanos-skills.git ~/Projects/thanos-skills
ln -s ~/Projects/thanos-skills/skills/thanos-query ~/.claude/skills/thanos-query

Connecting to Thanos

The skill runs curl from wherever Claude Code runs (your laptop, a dev container, a CI runner). That machine just needs to reach the Thanos Querier HTTP endpoint. Pick whichever path matches your deployment — they all end with a reachable THANOS_METRICS_URL:

Verify connectivity

# 1) is the endpoint a healthy Thanos?
curl -sS ${THANOS_AUTH_HEADER:+-H} ${THANOS_AUTH_HEADER:+"$THANOS_AUTH_HEADER"} \
  "$THANOS_METRICS_URL/-/healthy"
# expected: OK

# 2) does a trivial query return data?
curl -sS ${THANOS_AUTH_HEADER:+-H} ${THANOS_AUTH_HEADER:+"$THANOS_AUTH_HEADER"} \
  "$THANOS_METRICS_URL/api/v1/query?query=up" | jq '.data.result | length'
# expected: a number > 0

If something's off, you'll hit one of these:

Environment variables

THANOS_METRICS_URL    # Thanos Querier endpoint (e.g. http://localhost:10902)
THANOS_AUTH_HEADER    # Full HTTP header line, e.g. "Authorization: Bearer <token>"
                      # Leave empty for direct access; set it when behind an auth proxy.

Set them in your shell, or — if you drive the skill from Claude Code — in ~/.claude/settings.json so they load on every session:

{
  "env": {
    "THANOS_METRICS_URL": "http://localhost:10902",
    "THANOS_AUTH_HEADER": ""
  }
}

THANOS_AUTH_HEADER must be the full header line (Authorization: Bearer <token>), not just Bearer <token> — it's passed straight into curl -H "$THANOS_AUTH_HEADER".

Security

Thanos has no built-in authentication. Its HTTP API exposes:

• Read access to every metric across every connected Prometheus / store
• Arbitrary PromQL execution (a single bad query can OOM the Querier)
• Internal infrastructure detail in labels (instance IPs, pod names, namespaces, service names)

Thanos assumes the operator places it behind one of:

1. An internal-only network reachable via VPN or private connectivity
2. A reverse proxy with auth (nginx / oauth2-proxy / vmauth) in front
3. A service mesh with mTLS

Do not expose Thanos Query to the public internet.

General hardening

AWS-specific hardening

Data flow & privacy

• The skill executes curl from wherever Claude Code runs (your machine, container, or CI runner).
• Query responses — including all metric labels — are returned to Claude's context.
• That context is processed by Anthropic's API. If your labels contain confidential data (internal hostnames, infrastructure CIDRs, customer identifiers), treat skill output as information shared with Claude.

Repository topics

Set these on the repo to help others find it:

claude-code  claude-skills  thanos  prometheus  promql
observability  kubernetes  cncf  sre

License

Released under the MIT License.