mirror of
https://github.com/magnus919/agent-skills.git
synced 2026-09-21 00:26:23 +03:00
f83d48ba53
Adds one top-level telemetry skill covering the observability stack that deploys as one unit: Prometheus (scrape config, recording/alerting rules, relabeling, retention, HA), the OpenTelemetry Collector (pipelines, receivers/processors/exporters, sampling, trace/span correlation), and Loki (ingest, LogQL, retention, labels). Ships the read-only telemetry-check script (stdlib-only, --json): Prometheus rule sanity mirroring promtool check rules plus scrape-target reachability probes, fixture-tested with 16 unittest/pytest cases. Includes five dated references, a human-facing README, and six eval cases covering rule authoring, pipeline design, and retention. Routes up to platform-engineering and grafana without duplicating their content. Regenerates the llms.txt / marketplace / plugin catalogs and adds the README index entry. Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
67 lines
3.8 KiB
Markdown
67 lines
3.8 KiB
Markdown
# Telemetry Operations — Source Index
|
|
|
|
> **Last Updated:** 2026-08-03
|
|
|
|
This index tracks the authoritative sources behind the telemetry skill
|
|
(Prometheus + OpenTelemetry Collector + Loki as one stack) and the refresh
|
|
procedure for keeping it current.
|
|
|
|
## Canonical sources
|
|
|
|
| Component | Source |
|
|
|---|---|
|
|
| Prometheus documentation (current) | https://prometheus.io/docs/introduction/overview/ |
|
|
| Prometheus configuration (scrape config, relabeling) | https://prometheus.io/docs/prometheus/latest/configuration/configuration/ |
|
|
| Prometheus recording rules | https://prometheus.io/docs/prometheus/latest/configuration/recording_rules/ |
|
|
| Prometheus alerting rules | https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules/ |
|
|
| Prometheus storage and retention | https://prometheus.io/docs/prometheus/latest/storage/ |
|
|
| `promtool` rule checking | https://prometheus.io/docs/prometheus/latest/command-line/promtool/ |
|
|
| Prometheus rule format reference (rulefmt) | https://github.com/prometheus/prometheus/blob/main/model/rulefmt/rulefmt.go |
|
|
| OpenTelemetry Collector | https://opentelemetry.io/docs/collector/ |
|
|
| Collector components (receivers/processors/exporters) | https://opentelemetry.io/docs/collector/configuration/ |
|
|
| Collector sampling | https://opentelemetry.io/docs/collector/sampling/ |
|
|
| OpenTelemetry traces and spans | https://opentelemetry.io/docs/concepts/signals/traces/ |
|
|
| Loki documentation (current) | https://grafana.com/docs/loki/latest/ |
|
|
| Loki storage and retention | https://grafana.com/docs/loki/latest/operations/storage/retention/ |
|
|
| LogQL | https://grafana.com/docs/loki/latest/query/ |
|
|
| Loki label design guidance | https://grafana.com/docs/loki/latest/get-started/labels/ |
|
|
|
|
## Version observations (as of this refresh)
|
|
|
|
- Prometheus 3.x defaults to UTF-8 metric-name validation; the legacy metric
|
|
name pattern `[a-zA-Z_:][a-zA-Z0-9_:]*` remains the documented pattern for
|
|
recording rule names and is what `promtool` enforces under legacy validation.
|
|
- `promtool check rules` validates rule files structurally and parses every
|
|
expression with the full PromQL parser; `telemetry-check` deliberately
|
|
covers the structural subset so it can run with no Prometheus tooling.
|
|
- The OpenTelemetry Collector's `memory_limiter` processor is recommended
|
|
before every exporter; `tail_sampling` and `probabilistic_sampler` are the
|
|
two supported sampler processors for traces.
|
|
- Loki retention is enforced by the compactor on a per-tenant basis;
|
|
`retention_period` and `retention_size` are per-tenant limits, and
|
|
`retention_enabled` must be `true` for period-based retention.
|
|
- OTLP is the current stable protocol; the Collector can also receive/export
|
|
Prometheus exposition format, and its Loki exporter translates structured
|
|
log records into LogQL-compatible streams.
|
|
|
|
## Refresh procedure
|
|
|
|
1. Re-check the sources above for new minor or major releases.
|
|
2. Update the version observations that changed (defaults, renamed components,
|
|
new processors, changed retention semantics).
|
|
3. Re-run the bundled checker against a rules fixture and a scrape config and
|
|
confirm every check still parses: `telemetry/scripts/telemetry-check
|
|
--rules telemetry/fixtures/prometheus-rules.yml --json`.
|
|
4. Re-verify the SKILL.md keyword sweep from the validation contract and the
|
|
routing links to `platform-engineering` and `grafana`.
|
|
|
|
## Related skill sources
|
|
|
|
- `platform-engineering` owns observability strategy (SLIs, SLOs, what to
|
|
instrument) and its observability reference treats Prometheus, OTel, and
|
|
Loki as one stack; this skill owns operating that stack.
|
|
- `grafana` owns dashboards, panels, and Grafana-side alerting; it queries
|
|
Prometheus (PromQL) and Loki (LogQL) but does not operate the backends.
|
|
- `traefik` ships Prometheus and OTel configuration for the edge; its
|
|
observability reference documents the metric names this stack ingests.
|