api-observability-axiom-pino-sentry

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. Route Handler Usage - Child loggers inherit correlation ID automatically

Modern Alternative: AsyncLocalStorage + Mixin

For larger applications, use AsyncLocalStorage with Pino's mixin option for automatic context injection without manual child logger creation in every handler.

For implementation examples of both approaches, see [examples/correlation-ids.md](examples/correlation-ids.md).

Pattern 4: Custom Traces and Spans with OpenTelemetry

Add custom instrumentation for performance debugging.

Key Utilities:

• withSpan() - Wrap async operations in traced spans
• createSpan() - Create simple spans for synchronous operations

For code examples, see [examples/tracing.md](examples/tracing.md).

Pattern 5: Sentry Error Boundaries in React

Catch and report React component errors with recovery capability.

Key Components:

1. ErrorBoundary - Class component for catching render errors
2. global-error.tsx - SSR framework global error handler
3. Feature-level boundaries - Wrap feature sections with custom fallbacks

For implementation examples, see [examples/error-boundaries.md](examples/error-boundaries.md).

Pattern 6: Attaching User Context to Sentry

Add user information to Sentry after authentication for better debugging.

Key Functions:

• setSentryUser() - Call after successful authentication
• clearSentryUser() - Call on logout
• setSentryContext() - Add additional context per-feature

For code examples, see [examples/sentry-config.md](examples/sentry-config.md#pattern-setting-user-context).

Pattern 7: Filtering Expected Errors

Prevent expected errors from polluting Sentry quota and alerts.

Filtering Strategies:

1. beforeSend hook - Filter by error message patterns
2. HTTP status filtering - Skip 404, 401, 403
3. beforeBreadcrumb hook - Remove noisy console.log breadcrumbs

For configuration examples, see [examples/sentry-config.md](examples/sentry-config.md#pattern-error-filtering-configuration).

Pattern 8: Creating Axiom Monitors and Alerts

Set up proactive monitoring for production issues.

Monitor Types:

1. Error Rate Monitor - Alert w