Claude Skill

api-observability-setup-axiom-pino-sentry

Pino, Axiom, Sentry installation - one-time project setup for logging and error tracking with source maps upload

LLM Mart · 0 points · 2 views 0 listing impressions 0 install-command copies
Download agents-inc-skills-dist_plugins_api-observability-setup-axiom-pino-sentry_skills_api-observability-setup-axiom-pino-sentry-707467a.zip · 14 KB

Install

skills CLI npx skills add https://github.com/agents-inc/skills/tree/main/dist/plugins/api-observability-setup-axiom-pino-sentry/skills/api-observability-setup-axiom-pino-sentry
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install agents-inc-skills@llmmart
Git git clone https://github.com/agents-inc/skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole agents-inc/skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Observability Setup (Pino + Axiom + Sentry)

Quick Guide: One-time project setup for observability. Install pino, next-axiom, @sentry/nextjs. Configure Axiom dataset + Vercel integration. Set up Sentry DSN and config files. Wrap next.config.ts with withAxiom then withSentryConfig. Add instrumentation.ts for runtime-specific Sentry init. Source maps are uploaded automatically when SENTRY_AUTH_TOKEN is set in CI.


Detailed Resources:


<critical_requirements>

CRITICAL: Before Using This Skill

(You MUST create separate Axiom datasets for each environment - development, staging, production)

(You MUST configure all three Sentry config files - sentry.client.config.ts, sentry.server.config.ts, sentry.edge.config.ts)

(You MUST add source maps upload to CI/CD - Sentry needs source maps for readable stack traces)

(You MUST install pino-pretty as a devDependency only - never use in production)

</critical_requirements>


Auto-detection: pino, next-axiom, @sentry/nextjs, Axiom, Sentry, observability setup, logging setup, error tracking setup, source maps, sentry.client.config, sentry.server.config, sentry.edge.config, withAxiom, withSentryConfig

When to use:

  • Setting up a new project that needs logging and error tracking
  • Adding observability to an existing project without it
  • Migrating from another logging/error tracking solution to Axiom + Sentry

When NOT to use:

  • Adding new log statements to existing code (ongoing usage, not initial setup)
  • Configuring alerts, monitors, or dashboards after initial setup
  • Debugging production issues with existing observability

Key patterns covered:

  • Dependency installation (Pino, next-axiom, @sentry/nextjs, pino-pretty)
  • Environment variables template (.env.example)
  • next.config.ts with withAxiom() and withSentryConfig() wrappers
  • Sentry configuration files (client, server, edge)
  • instrumentation.ts for Sentry initialization
  • GitHub Actions for source maps upload
  • Pino logger with development/production modes
  • Health check endpoints
  • Initial Axiom dashboard setup



<decision_framework>

Decision Framework

See reference.md for complete decision trees:

  • Log Destinations: Where logs should go in each environment
  • Sentry vs Axiom for Errors: Which system handles which error types

</decision_framework>


<red_flags>

RED FLAGS

See reference.md for complete list.

High Priority:

  • Committing Axiom tokens or Sentry DSN to version control
  • Using pino-pretty in production
  • Missing source maps upload in CI
  • Same Axiom dataset for all environments

Common Mistakes:

  • Forgetting to wrap next.config.ts with withAxiom
  • Missing instrumentation.ts
  • Using removed Sentry options (hideSourceMaps, enableTracing, disableServerWebpackPlugin)
  • Hardcoding sample rates instead of named constants

</red_flags>


<critical_reminders>

CRITICAL REMINDERS

(You MUST create separate Axiom datasets for each environment - development, staging, production)

(You MUST configure all three Sentry config files - sentry.client.config.ts, sentry.server.config.ts, sentry.edge.config.ts)

(You MUST add source maps upload to CI/CD - Sentry needs source maps for readable stack traces)

(You MUST install pino-pretty as a devDependency only - never use in production)

Failure to follow these rules will result in missing logs, unreadable errors, and security vulnerabilities.

</critical_reminders>

Files (skills)
  • examples
    • axiom-integration.md 1.8 KB
      Loading…
    • ci-cd.md 2.4 KB
      Loading…
    • core.md 4.6 KB
      Loading…
    • health-check.md 2.3 KB
      Loading…
    • pino-logger.md 2 KB
      Loading…
    • sentry-config.md 5.5 KB
      Loading…
  • reference.md 7.8 KB
    Loading…
  • SKILL.md 10.5 KB
    ---
    name: api-observability-setup-axiom-pino-sentry
    description: Pino, Axiom, Sentry installation - one-time project setup for logging and error tracking with source maps upload
    ---
    
    # Observability Setup (Pino + Axiom + Sentry)
    
    > **Quick Guide:** One-time project setup for observability. Install `pino`, `next-axiom`, `@sentry/nextjs`. Configure Axiom dataset + Vercel integration. Set up Sentry DSN and config files. Wrap `next.config.ts` with `withAxiom` then `withSentryConfig`. Add `instrumentation.ts` for runtime-specific Sentry init. Source maps are uploaded automatically when `SENTRY_AUTH_TOKEN` is set in CI.
    
    ---
    
    **Detailed Resources:**
    
    - For code examples, see [examples/](examples/) folder:
      - [examples/core.md](examples/core.md) - Dependencies, env vars, next.config.ts, instrumentation
      - [examples/sentry-config.md](examples/sentry-config.md) - Sentry configuration files (client, server, edge)
      - [examples/pino-logger.md](examples/pino-logger.md) - Pino logger setup with redaction
      - [examples/axiom-integration.md](examples/axiom-integration.md) - Web Vitals and dashboard queries
      - [examples/ci-cd.md](examples/ci-cd.md) - GitHub Actions source maps upload
      - [examples/health-check.md](examples/health-check.md) - Health check endpoints
    - For decision frameworks and anti-patterns, see [reference.md](reference.md)
    
    ---
    
    <critical_requirements>
    
    ## CRITICAL: Before Using This Skill
    
    **(You MUST create separate Axiom datasets for each environment - development, staging, production)**
    
    **(You MUST configure all three Sentry config files - `sentry.client.config.ts`, `sentry.server.config.ts`, `sentry.edge.config.ts`)**
    
    **(You MUST add source maps upload to CI/CD - Sentry needs source maps for readable stack traces)**
    
    **(You MUST install `pino-pretty` as a devDependency only - never use in production)**
    
    </critical_requirements>
    
    ---
    
    **Auto-detection:** pino, next-axiom, @sentry/nextjs, Axiom, Sentry, observability setup, logging setup, error tracking setup, source maps, sentry.client.config, sentry.server.config, sentry.edge.config, withAxiom, withSentryConfig
    
    **When to use:**
    
    - Setting up a new project that needs logging and error tracking
    - Adding observability to an existing project without it
    - Migrating from another logging/error tracking solution to Axiom + Sentry
    
    **When NOT to use:**
    
    - Adding new log statements to existing code (ongoing usage, not initial setup)
    - Configuring alerts, monitors, or dashboards after initial setup
    - Debugging production issues with existing observability
    
    **Key patterns covered:**
    
    - Dependency installation (Pino, next-axiom, @sentry/nextjs, pino-pretty)
    - Environment variables template (`.env.example`)
    - `next.config.ts` with `withAxiom()` and `withSentryConfig()` wrappers
    - Sentry configuration files (client, server, edge)
    - `instrumentation.ts` for Sentry initialization
    - GitHub Actions for source maps upload
    - Pino logger with development/production modes
    - Health check endpoints
    - Initial Axiom dashboard setup
    
    ---
    
    <philosophy>
    
    ## Philosophy
    
    **Observability is not optional for production apps.** Without logging and error tracking, debugging production issues becomes guesswork. The Pino + Axiom + Sentry stack provides:
    
    - **Pino**: Fast structured JSON logging (5x faster than Winston)
    - **Axiom**: Unified logs, traces, and metrics with Vercel integration
    - **Sentry**: Error tracking with source maps and release tracking
    
    **This skill covers one-time setup only.** For ongoing usage patterns (log levels, structured fields, correlation IDs, alert configuration), use your observability usage skill.
    
    </philosophy>
    
    ---
    
    <patterns>
    
    ## Core Patterns
    
    ### Pattern 1: Dependency Installation
    
    Install all observability packages with correct dependency types.
    
    ```bash
    # Production dependencies
    npm install pino next-axiom @sentry/nextjs
    
    # Development dependencies (pretty printing for local dev)
    npm install -D pino-pretty
    ```
    
    **Why:** `pino-pretty` as devDependency prevents production bundle bloat (~500KB), all core packages are production dependencies for runtime use.
    
    For detailed code examples with good/bad comparisons, see [examples/core.md](examples/core.md#pattern-1-dependency-installation).
    
    ---
    
    ### Pattern 2: Environment Variables Template
    
    Create `.env.example` with all required observability variables documented. Group by service, use comments to explain where to get each value, and maintain separate datasets per environment.
    
    Key variables needed:
    
    - `NEXT_PUBLIC_AXIOM_DATASET` - Dataset name (e.g., `myapp-dev`, `myapp-prod`)
    - `NEXT_PUBLIC_AXIOM_TOKEN` - API token with ingest permission
    - `NEXT_PUBLIC_SENTRY_DSN` - Sentry DSN from project settings
    - `SENTRY_AUTH_TOKEN` - For source maps upload in CI
    - `SENTRY_ORG` / `SENTRY_PROJECT` - Organization and project slugs
    
    For complete template with all variables, see [examples/core.md](examples/core.md#pattern-2-environment-variables-template).
    
    ---
    
    ### Pattern 3: next.config.ts with withAxiom and withSentryConfig
    
    Wrap Next.js config with `withAxiom` for logging integration, then `withSentryConfig` for source map handling.
    
    Key configuration points:
    
    - `withAxiom` wraps first (inner), Sentry wraps outer
    - `silent: !process.env.CI` suppresses source map upload logs locally
    - Source maps are hidden by default in v9+ (no `hideSourceMaps` needed)
    - Use `sourcemaps.deleteSourcemapsAfterUpload` to clean up after upload
    
    ```typescript
    import { withSentryConfig } from "@sentry/nextjs";
    import { withAxiom } from "next-axiom";
    
    const nextConfig = {
      /* your config */
    };
    
    export default withSentryConfig(withAxiom(nextConfig), {
      org: process.env.SENTRY_ORG,
      project: process.env.SENTRY_PROJECT,
      authToken: process.env.SENTRY_AUTH_TOKEN,
      silent: !process.env.CI,
    });
    ```
    
    For complete configuration example, see [examples/core.md](examples/core.md#pattern-3-nextconfigts-with-withaxiom).
    
    ---
    
    ### Pattern 4: Sentry Configuration Files
    
    Create all three Sentry config files for client, server, and edge runtimes.
    
    **Required files:**
    
    - `sentry.client.config.ts` - Client-side with replay integration
    - `sentry.server.config.ts` - Server-side with local variables capture
    - `sentry.edge.config.ts` - Edge runtime with limited features
    
    Key considerations:
    
    - Use named constants for sample rates
    - Environment-specific configuration (debug mode, sample rates)
    - Filter expected errors with `beforeSend`
    - v9+: `hideSourceMaps` and `enableTracing` removed, source maps hidden by default
    
    For complete file templates, see [examples/sentry-config.md](examples/sentry-config.md#pattern-4-sentry-configuration-files).
    
    ---
    
    ### Pattern 5: Instrumentation File
    
    Create `instrumentation.ts` for proper Sentry initialization in Next.js. Uses dynamic imports to load the correct config for each runtime.
    
    ```typescript
    import * as Sentry from "@sentry/nextjs";
    
    export async function register() {
      if (process.env.NEXT_RUNTIME === "nodejs") {
        await import("./sentry.server.config");
      }
    
      if (process.env.NEXT_RUNTIME === "edge") {
        await import("./sentry.edge.config");
      }
    }
    
    // Next.js 15+ error handling hook
    export const onRequestError = Sentry.captureRequestError;
    ```
    
    **Why:** Dynamic imports prevent loading wrong config for runtime, `onRequestError` hook captures Server Component errors automatically (Next.js 15+).
    
    ---
    
    ### Pattern 6: Web Vitals Component
    
    Add `<AxiomWebVitals />` component to root layout for automatic Core Web Vitals (LCP, INP, CLS) reporting to Axiom.
    
    **Note:** Web Vitals are only sent from production deployments, not local development.
    
    For implementation example, see [examples/axiom-integration.md](examples/axiom-integration.md#pattern-6-web-vitals-component).
    
    ---
    
    ### Pattern 7: GitHub Actions Source Maps Upload
    
    Configure CI/CD to upload source maps to Sentry on deployment. Key requirements:
    
    - `SENTRY_AUTH_TOKEN` in build environment enables automatic upload
    - Use `getsentry/action-release@v3` for release creation
    - Tie version to git SHA for release tracking
    
    For complete workflow template, see [examples/ci-cd.md](examples/ci-cd.md#pattern-7-github-actions-source-maps-upload).
    
    ---
    
    ### Pattern 8: Health Check Endpoint
    
    Add health check endpoints that integrate with your observability stack:
    
    - **Shallow check** - Fast response for load balancer probes, includes version for Sentry release correlation
    - **Deep check** - Verifies dependencies, logs failures via Pino for Axiom dashboard visibility
    
    For implementation examples, see [examples/health-check.md](examples/health-check.md#pattern-8-health-check-endpoint).
    
    ---
    
    ### Pattern 9: Pino Logger Setup
    
    Configure Pino with development/production modes:
    
    - Development: `pino-pretty` for human-readable output
    - Production: JSON for log aggregation ingestion
    - Base fields for context in every log
    - Redaction of sensitive fields
    
    For complete configuration, see [examples/pino-logger.md](examples/pino-logger.md#pattern-9-pino-logger-setup).
    
    ---
    
    ### Pattern 10: Axiom Dashboard Setup
    
    After setting up, create initial dashboards in Axiom:
    
    - Request volume per minute
    - Error rate percentage
    - Response time P95
    - Top errors
    - Web Vitals metrics
    
    For APL query examples, see [examples/axiom-integration.md](examples/axiom-integration.md#pattern-10-axiom-dashboard-setup).
    
    </patterns>
    
    ---
    
    <decision_framework>
    
    ## Decision Framework
    
    See [reference.md](reference.md#decision-framework) for complete decision trees:
    
    - **Log Destinations**: Where logs should go in each environment
    - **Sentry vs Axiom for Errors**: Which system handles which error types
    
    </decision_framework>
    
    ---
    
    <red_flags>
    
    ## RED FLAGS
    
    See [reference.md](reference.md#red-flags) for complete list.
    
    **High Priority:**
    
    - Committing Axiom tokens or Sentry DSN to version control
    - Using pino-pretty in production
    - Missing source maps upload in CI
    - Same Axiom dataset for all environments
    
    **Common Mistakes:**
    
    - Forgetting to wrap `next.config.ts` with `withAxiom`
    - Missing `instrumentation.ts`
    - Using removed Sentry options (`hideSourceMaps`, `enableTracing`, `disableServerWebpackPlugin`)
    - Hardcoding sample rates instead of named constants
    
    </red_flags>
    
    ---
    
    <critical_reminders>
    
    ## CRITICAL REMINDERS
    
    **(You MUST create separate Axiom datasets for each environment - development, staging, production)**
    
    **(You MUST configure all three Sentry config files - `sentry.client.config.ts`, `sentry.server.config.ts`, `sentry.edge.config.ts`)**
    
    **(You MUST add source maps upload to CI/CD - Sentry needs source maps for readable stack traces)**
    
    **(You MUST install `pino-pretty` as a devDependency only - never use in production)**
    
    **Failure to follow these rules will result in missing logs, unreadable errors, and security vulnerabilities.**
    
    </critical_reminders>
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.