Observability with OpenTelemetry Rules for Cursor

# Observability with OpenTelemetry Rules for Cursor

# Observability with OpenTelemetry Rules

## The Three Pillars
- **Traces**: distributed request flow across services — OpenTelemetry SDK
- **Metrics**: aggregated measurements — Prometheus + Grafana or Datadog
- **Logs**: structured events — always JSON, always with trace ID

## Instrumentation Setup
```typescript
// Initialize BEFORE importing application code
import { NodeSDK } from '@opentelemetry/sdk-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';

const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter({ url: process.env.OTEL_ENDPOINT }),
  instrumentations: [getNodeAutoInstrumentations()], // HTTP, express, DB auto-instrumented
});
sdk.start();
```

## Trace Conventions
- Service name: lowercase, hyphenated (`user-service`, `payment-api`)
- Every HTTP request: automatic via auto-instrumentation
- Custom spans for business operations: `tracer.startActiveSpan('process-payment', ...)`
- Span attributes: `user.id`, `order.id`, `payment.amount` — queryable in Jaeger/Tempo
- Error spans: `span.setStatus({ code: SpanStatusCode.ERROR, message: err.message })`

## Structured Logging
```typescript
// Every log includes trace context
const logger = {
  info: (msg: string, attrs?: object) => {
    const span = trace.getActiveSpan();
    const ctx = span?.spanContext();
    console.log(JSON.stringify({
      level: 'info', message: msg, timestamp: new Date().toISOString(),
      traceId: ctx?.traceId, spanId: ctx?.spanId,
      ...attrs