observability-setup — Claude Code skill: traces, metrics, logs
observability-setup brings OpenTelemetry tracing, Prometheus metrics and structured logging into one setup, with a Grafana dashboard and starter alert rules attached.
MIT 289 installs ★ 64 updated 2026-01-12
npx skills add patricio0312rev/skills --skill observability-setup -a claude-codeWhat observability-setup does
The skill walks through all three pillars at once: traces, metrics, logs. You get TypeScript snippets — a NodeTracerProvider with HTTP, Express and Prisma auto-instrumentation, custom spans carrying attributes and status, counters and histograms on prom-client. A middleware times each request and a /metrics handler serves the registry.
Logging runs on pino, with service and environment fields and the level taken from LOG_LEVEL. Alongside the metrics comes a Grafana dashboard JSON: request rate, error share, p95 latency, open connections. A separate file holds Prometheus alert rules for 5xx growth, p95 above 2 seconds and availability under 95%.
Express and Prisma sit in the instrumentation list, so a project built on something else needs those registrations swapped for its own libraries. A closing checklist covers tracing, metrics, logging, dashboards, alerts and the exposed endpoint.
What it helps with
- wire OpenTelemetry tracing into a Node service
- expose Prometheus metrics on a
/metricsendpoint - switch logging to structured
pinooutput - assemble a Grafana dashboard from ready panels
- draft Prometheus alert rules for error rate and latency
Example prompts for the agent
- Add OpenTelemetry tracing to my Express API and register the HTTP and Prisma instrumentations.
- Expose a
/metricsendpoint with a request counter and a duration histogram. - Write Prometheus alert rules for 5xx growth and p95 latency over 2 seconds.
How to install observability-setup
1Skills CLI (Vercel)
npx skills add patricio0312rev/skills --skill observability-setup -a claude-code2Manually: put the files in place
~/.claude/skills/observability-setup/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/observability-setup/
1Skills CLI (Vercel)
npx skills add patricio0312rev/skills --skill observability-setup -a codex2Manually: put the files in place
.agents/skills/observability-setup/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add patricio0312rev/skills --skill observability-setup -a cursor2Manually: put the files in place
.cursor/skills/observability-setup/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install patricio0312rev/skills performance/observability-setup/SKILL.md2Manually: put the files in place
.github/skills/observability-setup/SKILL.md1Skills CLI (Vercel)
npx skills add patricio0312rev/skills --skill observability-setup -a gemini-cli2Platform CLI
gemini skills install https://github.com/patricio0312rev/skills --path performance/observability-setupManually: put the files in place
.devin/skills/observability-setup/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add patricio0312rev/skills --skill observability-setup -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about observability-setup
How do I install observability-setup in Claude Code?
Run npx skills add patricio0312rev/skills --skill observability-setup -a claude-code. The skill lands at ~/.claude/skills/observability-setup/SKILL.md.
What does observability-setup do?
It adds OpenTelemetry traces, Prometheus metrics and pino logging to a service, plus a Grafana dashboard and draft alert rules.
Does it work outside Express?
The instrumentation examples register HTTP, Express and Prisma. On another framework or ORM you swap those registrations for the matching packages.
Source text
SKILL.md · MIT
---
name: observability-setup
description: Implements comprehensive observability with OpenTelemetry tracing, Prometheus metrics, and structured logging. Includes instrumentation plans, sample dashboards, and alert candidates. Use for "observability", "monitoring", "tracing", or "metrics".
---
# Observability Setup
Implement the three pillars: Traces, Metrics, and Logs.
## OpenTelemetry Tracing
```typescript
// tracing.ts
import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
import { Resource } from "@opentelemetry/resources";
import { SemanticResourceAttributes } from "@opentelemetry/semantic-conventions";
import { registerInstrumentations } from "@opentelemetry/instrumentation";
import { HttpInstrumentation } from "@opentelemetry/instrumentation-http";
import { ExpressInstrumentation } from "@opentelemetry/instrumentation-express";
import { PrismaInstrumentation } from "@prisma/instrumentation";
const provider = new NodeTracerProvider({
resource: new Resource({
[SemanticResourceAttributes.SERVICE_NAME]: "my-api",
[SemanticResourceAttributes.SERVICE_VERSION]: "1.0.0",
}),
});
registerInstrumentations({
instrumentations: [
new HttpInstrumentation(),
new ExpressInstrumentation(),
new PrismaInstrumentation(),
],
});
provider.register();
// Custom spans
import { trace } from "@opentelemetry/api";
const tracer = trace.getTracer("my-app");
async function processOrder(orderId: string) {
const span = tracer.startSpan("processOrder");
span.setAttribute("order.id", orderId);
try {
await validateOrder(orderId);
await chargePayment(orderId);
await fulfillOrder(orderId);
span.setStatus({ code: 0 }); // OK
} catch (error) {
span.setStatus({ code: 2, message: error.message }); // ERROR
throw error;
} finally {
span.end();
}
}
```
## Prometheus Metrics
```typescript
// metrics.ts
import { Registry, Counter, Histogram, Gauge } from "prom-client";
const register = new Registry();
// HTTP request counter
export const httpRequestCounter = new Counter({
name: "http_requests_total",
help: "Total HTTP requests",
labelNames: ["method", "route", "status_code"],
registers: [register],
});
// HTTP request duration
export const httpRequestDuration = new Histogram({
name: "http_request_duration_seconds",
help: "HTTP request duration in seconds",
labelNames: ["method", "route", "status_code"],
buckets: [0.1, 0.5, 1, 2, 5, 10],
registers: [register],
});
// Active connections
export const activeConnections = new Gauge({
name: "active_connections",
help: "Number of active connections",
registers: [register],
});
// Business metrics
export const ordersProcessed = new Counter({
name: "orders_processed_total",
help: "Total orders processed",
labelNames: ["status"],
registers: [register],
});
// Middleware
app.use((req, res, next) => {
const start = Date.now();
res.on("finish", () => {
const duration = (Date.now() - start) / 1000;
const route = req.route?.path || "unknown";
httpRequestCounter.inc({
method: req.method,
route,
status_code: res.statusCode,
});
httpRequestDuration.observe(
{ method: req.method, route, status_code: res.statusCode },
duration
);
});
next();
});
// Metrics endpoint
app.get("/metrics", async (req, res) => {
res.set("Content-Type", register.contentType);
res.end(await register.metrics());
});
```
## Structured Logging
```typescript
// logger.ts
import pino from "pino";
export const logger = pino({
level: process.env.LOG_LEVEL || "info",
formatters: {
level: (label) => ({ level: label }),
},
base: {
service: "my-api",
environment: process.env.NODE_ENV,
},
});
// Usage
logger.info({ userId: "123", action: "login" }, "User logged in");
logger.error({ err: error, orderId: "456" }, "Order processing failed");
```
## Sample Dashboard (Grafana)
```json
{
"dashboard": {
"title": "API Overview",
"panels": [
{
"title": "Request Rate",
"targets": [{
"expr": "rate(http_requests_total[5m])"
}]
},
{
"title": "Error Rate",
"targets": [{
"expr": "rate(http_requests_total{status_code=~"5.."}[5m])"
}]
},
{
"title": "p95 Latency",
"targets": [{
"expr": "histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m]))"
}]
},
{
"title": "Active Connections",
"targets": [{
"expr": "active_connections"
}]
}
]
}
}
```
## Alert Candidates
```yaml
# alerts.yml
groups:
- name: api_alerts
interval: 30s
rules:
- alert: HighErrorRate
expr: rate(http_requests_total{status_code=~"5.."}[5m]) > 0.05
for: 5m
labels:
severity: critical
annotations:
summary: "High error rate detected"
- alert: HighLatency
expr: histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m])) > 2
for: 10m
labels:
severity: warning
annotations:
summary: "p95 latency above 2s"
- alert: LowAvailability
expr: rate(http_requests_total{status_code="200"}[5m]) / rate(http_requests_total[5m]) < 0.95
for: 5m
labels:
severity: critical
annotations:
summary: "Availability below 95%"
```
## Output Checklist
- [ ] OpenTelemetry tracing configured
- [ ] Prometheus metrics instrumented
- [ ] Structured logging implemented
- [ ] Sample dashboards created
- [ ] Alert rules defined
- [ ] Metrics endpoint exposed
- [ ] Instrumentation tested
ENDFILE
© patricio0312rev · MIT · patricio0312rev/skills