---
name: "promtail-log-shipper-tuning"
description: "Collect, transform, and ship system and container logs to Loki without excessive cardinality."
metadata:
  author: "Grafana Labs"
  version: "1.0.0"
  runtime_compatibility:
    - "codex"
    - "claude-code"
    - "cursor"
    - "windsurf"
triggers:
  - "configure promtail pipeline_stages"
  - "prevent high cardinality loki promtail"
  - "ship logs to loki"
permissions:
  fs_read: true
  fs_write: "workspace"
  shell_exec: false
  net_access: false
---

# Promtail Log Shipping & Pipeline Scrape Configuration

Configures Promtail log collection: writing promtail.yaml, configuring pipeline_stages (json, regex, timestamp, labels), dropping noisy debug lines, preventing high-cardinality label explosions, and positions file tracking.

## When to Invoke
Invoke this skill whenever you need to:
- configure promtail pipeline_stages
- prevent high cardinality loki promtail
- ship logs to loki

## Execution SOP & Rules
1. Define scrape_configs in promtail.yaml targeting /var/log/containers/*.log.
2. Add pipeline_stages: - match: { selector: '{app="web"}', stages: [{ drop: { expression: ".*healthz.*" } }] }.
3. Extract timestamp from JSON log body to prevent ingestion timestamp drift.
4. Verify positions file tracking at /var/log/positions.yaml to ensure zero dropped logs on restarts.

## Verification Checklist
- Run local linting, syntax validation, and type-checks before reporting completion.
- Ensure all created or modified files adhere to workspace boundaries and avoid uncommitted secrets.
- Verify tests or build commands exit cleanly with return code 0.