Adds or reviews distributed tracing, metrics, and structured logging using OpenTelemetry SDK with OTLP export.
Add or review OpenTelemetry instrumentation across the application. Cover the three observability pillars: distributed traces (spans), metrics (counters, histograms, gauges), and structured logs with trace correlation. Use OTLP exporter for vendor-agnostic collection.
Include this skill when observability is not "none" in the project configuration.
/x-obs-instrument full -- instrument all components/x-obs-instrument transaction-service -- instrument a specific component/x-obs-instrument persistence-layer -- instrument a specific layer| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
component | String | No | full | Component name to instrument, or full for all |
| Pack | Files | Purpose |
|---|---|---|
| observability | skills/observability/references/observability-principles.md | 3 pillars (traces, metrics, logs), span tree pattern, mandatory attributes, health checks |
http://otel-collector:4317)Check {{BUILD_FILE}} for:
Verify OTel properties:
otel.service.name set to project nameotel.exporter.otlp.endpoint externalized (env var)parentbased_always_on)For the target component:
Add application-specific metrics:
{{PROJECT_PREFIX}}.metric.nameSet up structured logging:
Implement probes:
Run {{BUILD_COMMAND}} and verify:
{{PROJECT_PREFIX}}.. (dot)seconds, bytes, 1 (dimensionless count)grpc.{package}.{service}/{method}rpc.system=grpc, rpc.method, rpc.service, rpc.grpc.status_coderpc.server.duration, rpc.server.request.size, rpc.server.response.sizegraphql.operation.name, graphql.operation.type, graphql.document (sanitized)graphql.operation.duration, graphql.resolver.duration, graphql.error.count{topic} send (span kind: PRODUCER){topic} receive (span kind: CONSUMER)messaging.system, messaging.destination, messaging.operation, messaging.message.idwebsocket.connection.id, websocket.message.typewebsocket.connections.active, websocket.messages.sent, websocket.messages.received| Scenario | Action |
|---|---|
| OTel SDK dependency missing | Report missing dependency with install instructions |
| OTLP endpoint unreachable | Warn and continue; instrumentation code is independent of collector availability |
| Build fails after instrumentation | Roll back changes, report compilation errors with file and line |