| name | observability-baseline |
| description | Establishes logging, metrics, and tracing conventions for the codebase. Use when setting up or auditing the observability stack and standards. |
| user-invokable | false |
Observability Baseline
Reference
- ID: S-ENG-15
- Category: Engineering
- Inputs: service architecture, SLOs, existing logging/metrics setup
- Outputs: observability standards document → artifacts/engineering/
- Used by: Engineering Agent
- Tool scripts: ./tools/artifact/validate.sh
Purpose
Defines the baseline conventions for structured logging, application metrics, and distributed tracing so that every service produces consistent, queryable telemetry data from day one.
Procedure
Step 0: Tech Stack Detection
Read observability.* from company.config.yaml to determine logging, metrics, and tracing providers.
Provider-specific patterns:
| Provider | Logging | Metrics | Tracing |
|---|
| Datadog | Pino → dd-trace auto-inject | StatsD via hot-shots | dd-trace auto-instrumentation |
| Sentry | @sentry/node breadcrumbs | Sentry performance metrics | Sentry transactions |
| OpenTelemetry | OTLP exporter | OTLP metrics | OTLP spans |
| CloudWatch | winston + CloudWatch transport | CloudWatch embedded metrics | X-Ray SDK |
Structured log required fields:
{
"timestamp": "ISO-8601",
"level": "info|warn|error|debug",
"message": "Human-readable description",
"request_id": "uuid",
"user_id": "optional",
"tenant_id": "optional (if multi-tenant)",
"duration_ms": "optional (for timed operations)",
"error": { "code": "string", "stack": "string" }
}
Cross-references: See deployment-strategy for infrastructure setup, incident-response for alert routing.
- Audit the current observability setup: what logging, metrics, and tracing exist today.
- Define structured logging conventions: log levels, required fields (request_id, tenant_id, user_id), format (JSON).
- Define application metrics conventions: naming scheme, label cardinality limits, standard metrics (request duration, error rate, queue depth).
- Define distributed tracing conventions: span naming, context propagation, sampling strategy.
- Establish SLO-aligned alerting: map each SLO to a metric and define alert thresholds.
- Document correlation strategy: how to go from an alert to logs to traces.
- Define sensitive data handling in telemetry: what must never be logged (PII, secrets).
- Create example code snippets for each convention.
- Save the standards document to
artifacts/engineering/.
- Validate the artifact using
./tools/artifact/validate.sh.
Quality Checklist
