Observability Baseline Installer

What this skill does

Adds an OpenTelemetry-based observability baseline to a Node.js service: a single instrumentation.ts bootstrapped before app code, automatic HTTP and DB spans, RED metrics, and structured JSON logs that include trace_id and span_id.

Inputs

• repo_dir: project root.
• entry_file: the service's main entry (e.g., src/server.ts).
• service_name: logical service name for the OTel resource (e.g., payments-api).
• Optional otlp_endpoint: defaults to http://localhost:4318/v1/<signal> (HTTP exporter).

Steps

1. Add dependencies: npm install --save @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node @opentelemetry/exporter-trace-otlp-http @opentelemetry/exporter-metrics-otlp-http @opentelemetry/exporter-logs-otlp-http @opentelemetry/api.
2. Create src/instrumentation.ts that initializes NodeSDK with: Resource containing service.name, automatic instrumentations, OTLP HTTP trace exporter, periodic metric reader (60s), log exporter.
3. Wire the bootstrap: change the npm start script to node --import ./instrumentation.js dist/server.js (or use --require for CJS).
4. Replace the existing logger (console.log or pino) with a pino instance configured with formatters that inject trace_id and span_id from the active span using trace.getSpan(context.active()).
5. Define the four RED metrics as Counter/Histogram instruments named http.server.requests, http.server.duration, http.server.errors, http.server.in_flight.
6. Add a one-line export to instrumentation.ts that registers an HTTP middleware to populate these metrics on each request.
7. Generate a docker-compose.observability.yml with otel-collector + Tempo + Prometheus + Loki for local validation.
8. Add a smoke-test script: hit /health via curl, then poll Tempo's API to confirm a trace with the request's path appeared.
9. Commit with a "feat: otel baseline" message scaffold.

Output

Files written: src/instrumentation.ts, docker-compose.observability.yml, an updated package.json start script, and docs/observability.md documenting how to run the local collector. Stdout prints the number of routes auto-instrumented.

Verification

Run docker-compose -f docker-compose.observability.yml up -d, start the service, send 10 requests, and confirm: traces appear in Tempo (curl /api/search?tags=service.name=<name>), metrics appear at /metrics on the otel-collector's Prometheus exporter, and a sample log line includes a non-empty trace_id. If any of the three signals is missing, the install is incomplete and the report should fail.

Edge cases

• Services using ESM with custom loaders: use NODE_OPTIONS=--import rather than --require.
• Services already using a manual instrumentation library: detect and warn; do not double-instrument the same library.
• Lambda or serverless runtimes: NodeSDK lifecycle differs; use @opentelemetry/sdk-node's lambda handler wrapper instead.
• Logging at very high volume: enable sampling via SAMPLER_ARG env var; default 100% sampling is fine for staging only.