/api-observability-axiom-pino-sentry

name: api-observability-axiom-pino-sentry
description: Pino logging, Sentry error tracking, Axiom - structured logging with correlation IDs, error boundaries, performance monitoring, alerting

Observability Patterns (Logging, Tracing, Error Handling)

> **Quick Guide:** Structured logging with Pino (debug/info/warn/error). Correlation IDs for request tracing. Sentry error boundaries in React. Attach user context after auth. Filter expected errors (404s). Create Axiom monitors for alerts.

---

<critical_requirements>

CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST include correlation ID in ALL log statements for request tracing)**

**(You MUST use structured logging with required fields: level, message, correlationId, timestamp)**

**(You MUST filter expected errors (404, validation) from Sentry to avoid quota waste)**

**(You MUST attach user context to Sentry AFTER authentication completes)**

**(You MUST use child loggers with context instead of repeating fields in every log call)**

</critical_requirements>

---

**Auto-detection:** log, logger, pino, Sentry, error boundary, correlation ID, trace, span, observability, monitoring, alerting

**When to use:**

• Adding logging to new feature code
• Implementing error handling patterns
• Setting up request tracing with correlation IDs
• Creating custom traces and spans for performance debugging
• Configuring Sentry error boundaries in React components
• Creating Axiom monitors and alerts

**When NOT to use:**

• Initial project setup and dependency installation (one-time setup; follow official docs)
• Framework-specific configuration files (follow framework SDK docs)

**Key patterns covered:**

• Log levels decision tree (when to use debug/info/warn/error)
• Structured logging with required fields
• Correlation IDs: generating, propagating, attaching to logs
• Custom traces/spans with OpenTelemetry
• Sentry error boundaries in React
• Attaching user context to Sentry after auth
• Creating Axiom monitors and alerts
• Filtering noise (expected errors like 404s)
• Performance monitoring patterns
• Debugging guide: tracing a request through the system

**Detailed Resources:**

• For code examples, see [examples/core.md](examples/core.md) (essential patterns always loaded)
• For decision frameworks and anti-patterns, see [reference.md](reference.md)

**Extended Examples:**

• [examples/correlation-ids.md](examples/correlation-ids.md) - Middleware for request tracing
• [examples/tracing.md](examples/tracing.md) - OpenTelemetry spans and custom instrumentation
• [examples/error-boundaries.md](examples/error-boundaries.md) - React error boundaries with Sentry
• [examples/sentry-config.md](examples/sentry-config.md) - User context and error filtering
• [examples/axiom.md](examples/axiom.md) - Monitors, alerts, and debugging queries
• [examples/performance.md](examples/performance.md) - Query and API call tracking

---

<philosophy>

Philosophy

**Good observability answers three questions:**

1. **What happened?** (Structured logs with context) 2. **Why did it happen?** (Error tracking with stack traces) 3. **How do I find it?** (Correlation IDs linking related events)

Logging should be **intentional, not defensive**. Every log statement should answer a specific question you might ask when debugging. Avoid logging "just in case" - it creates noise that makes real issues harder to find.

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Log Levels Decision Tree

Choose the appropriate log level based on the situation.

What are you logging?
├─ Development-only debugging info?
│   └─ debug (filtered in production)
├─ Normal operation events?
│   ├─ Request started/completed → info
│   ├─ User action completed → info
│   └─ Background job finished → info
├─ Something unexpected but recoverable?
│   ├─ Retry attempt → warn
│   ├─ Fallback used → warn
│   └─ Deprecation notice → warn
└─ Something that needs attention?
    ├─ Unhandled exception → error
    ├─ External service failure → error
    └─ Data integrity issue → error

**Level Guidelines:**

| Level | Production | When to Use | | ------- | --------------- | -------------------------------------------------- | | `debug` | Filtered | Development debugging, verbose tracing | | `info` | Visible | Normal operations, request lifecycle, user actions | | `warn` | Visible | Recoverable issues, retries, fallbacks | | `error` | Visible + Alert | Unrecoverable issues, failures, exceptions |

For code examples, see [examples/core.md](examples/core.md#pattern-1-log-levels).

---

Pattern 2: Structured Logging with Required Fields

Every log statement should include structured context for searchability.

**Required Fields:**

| Field | Type | Purpose | | --------------- | ------- | ----------------------------------------------------- | | `correlationId` | string | Links all logs from same request | | `service` | string | Identifies the service (api, web, worker) | | `operation` | string | What action is being performed | | `userId` | string? | User performing the action (if authenticated) | | `duration` | number? | Time taken in milliseconds (for completed operations) |

For code examples, see [examples/core.md](examples/core.md#pattern-2-structured-logging).

---

Pattern 3: Correlation IDs for Request Tracing

Generate and propagate correlation IDs to trace requests across services.

**Key Components:**

1. **Correlation ID Middleware** - Generates/extracts correlation ID from headers 2. **Request Logger Middleware** - Creates request-scoped logger with correlation context 3.