跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

prometheus

Prometheus instrumentation discipline: right metric type, right name, right labels. Invoke whenever task involves any interaction with Prometheus metrics — instrumenting application code, writing PromQL queries, defining alerting or recording rules, choosing metric types, managing label cardinality, building exporters, or reviewing monitoring configuration.

xobotyi · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add xobotyi/cc-foundry --skill prometheus

技能说明


name: prometheus description: >- Prometheus instrumentation discipline: right metric type, right name, right labels. Invoke whenever task involves any interaction with Prometheus metrics — instrumenting application code, writing PromQL queries, defining alerting or recording rules, choosing metric types, managing label cardinality, building exporters, or reviewing monitoring configuration.

Prometheus

Choose the right metric type, name it clearly, label it sparingly. Prometheus is a pull-based monitoring system built on a dimensional data model — every metric is a time series identified by a name and key-value label pairs. Getting this right at instrumentation time prevents rework later.

References

  • Metric types — [${CLAUDE_SKILL_DIR}/references/metric-types.md] Extended type comparison, histogram bucket tuning, summary configuration
  • Naming — [${CLAUDE_SKILL_DIR}/references/naming.md] Full naming examples, base units table, character rules, label best practices
  • Instrumentation — [${CLAUDE_SKILL_DIR}/references/instrumentation.md] Code patterns per system type, library instrumentation, performance tuning
  • PromQL — [${CLAUDE_SKILL_DIR}/references/promql.md] Full operator catalog, vector matching, over-time aggregation, operator precedence
  • Alerting and rules — [${CLAUDE_SKILL_DIR}/references/alerting-and-rules.md] Alert design, recording rule naming, aggregation patterns, anti-patterns
  • Exporters — [${CLAUDE_SKILL_DIR}/references/exporters.md] Exporter architecture, collectors, help strings, push-based sources

Metric Type Selection

Choose correctly at instrumentation time — changing later requires migrating dashboards, alerts, and recording rules.

QuestionAnswerType
Can the value decrease?NoCounter
Is it a snapshot of current state?YesGauge
Observing a distribution needing cross-instance aggregation?YesHistogram
Need accurate quantiles from a single instance, known at instrumentation time?YesSummary
None of the above—Gauge

Counter

Monotonically increasing value — resets to zero only on restart.

  • Use for: requests served, errors occurred, bytes transferred, tasks completed
  • API: inc(), inc(v) where v >= 0
  • Always suffix with _total: http_requests_total
  • Always apply rate() or increase() in queries — raw values are meaningless
  • Prometheus handles counter resets automatically in rate()
  • Never use a counter for values that can decrease — that is a gauge

Gauge

Value that goes up and down arbitrarily.

  • Use for: temperature, memory usage, in-progress requests, queue depth, timestamps
  • API: inc(), dec(), set(v), set_to_current_time()
  • No _total suffix
  • Never apply rate() to a gauge — use deriv() or delta()
  • Timestamp pattern: store Unix epoch seconds as myapp_last_success_timestamp_seconds; compute elapsed time with time() - metric in PromQL
  • Info metric pattern: myapp_build_info{version="1.2.3", commit="abc"} 1 — metadata as labels with constant value 1

Histogram

Samples observations into configurable buckets. Produces _bucket{le="..."}, _sum, _count.

  • Use for: request latencies, response sizes, any distribution needing percentiles or cross-instance aggregation
  • API: observe(v)
  • Buckets are cumulative — le="0.5" includes all observations <= 0.5
  • Must include +Inf bucket (equal to _count)
  • Choose buckets matching expected value range; place more buckets near SLO boundaries
  • Buckets cannot be changed after metric creation
  • Use histogram_quantile() in PromQL to calculate percentiles
  • Aggregatable across instances — the primary advantage over summary

Summary

Calculates streaming quantiles on the client side. Produces {quantile="..."}, _sum, _count.

  • Cannot be aggregated across instances — avg(x{quantile="0.95"}) is statistically invalid
  • _sum and _count without quantiles is a valid and useful configuration

Use summary over histogram only when ALL of these are true:

  1. You need accurate quantiles (not approximate)
  2. From a single instance (no cross-instance aggregation)
  3. You know the exact quantiles at instrumentation time
  4. You accept that adding new quantiles requires code changes

Default choice: histogram. See ${CLAUDE_SKILL_DIR}/references/metric-types.md for detailed comparison.

Naming

Format: <namespace>_<subsystem>_<name>_<unit>_<suffix>. Not all parts required — minimum is namespace + meaningful name + unit/suffix.

Naming Rules

  1. Use snake_case — lowercase with underscores, matching [a-zA-Z_:][a-zA-Z0-9_:]*
  2. Colons (:) are reserved for recording rules — never use in direct instrumentation
  3. Double underscore prefix (__) is reserved for Prometheus internals
  4. Every metric MUST have a namespace prefix identifying its origin
  5. Always use base units — seconds not milliseconds, bytes not megabytes. Let visualization tools handle conversion.
  6. Append unit to metric name in plural form: http_request_duration_seconds
  7. Suffix counters with _total, counter-with-unit as _<unit>_total (e.g., process_cpu_seconds_total)
  8. Suffix info metrics with _info, timestamps with _timestamp_seconds
  9. A metric MUST represent the same logical thing across all its label dimensions — sum() or avg() across all dimensions should be meaningful. If nonsensical, split into separate metrics.

See ${CLAUDE_SKILL_DIR}/references/naming.md for base units table, component ordering, and full examples.

Labels

阅读完整来源 ↗