sentry-observability

Integrate Sentry with your observability stack — logging, metrics, APM, and dashboards. Use when connecting Sentry to winston/pino/structlog, correlating errors with business metrics, deciding between Sentry performance and Datadog/New Relic, building Sentry Discover dashboards, or linking events to external tools via extra context. Trigger: "sentry observability", "sentry logging", "sentry metrics", "sentry grafana", "sentry datadog correlation", "sentry discover dashboard".

仓库: jeremylongshore/claude-code-plugins-plus-skills
最近来源活动: 2026年7月17日 22:18
检测到的 SKILL.md 语言: 英语
星标: 2,604
分支: 378

安装方式

默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。

检查来源文件

决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。

返回搜索返回安装

name	sentry-observability
description	Integrate Sentry with your observability stack — logging, metrics, APM, and dashboards. Use when connecting Sentry to winston/pino/structlog, correlating errors with business metrics, deciding between Sentry performance and Datadog/New Relic, building Sentry Discover dashboards, or linking events to external tools via extra context. Trigger: "sentry observability", "sentry logging", "sentry metrics", "sentry grafana", "sentry datadog correlation", "sentry discover dashboard".
allowed-tools	Read, Write, Edit, Grep, Bash(node:), Bash(npx:), Bash(pip:*)
version	1.51.0
license	MIT
author	Jeremy Longshore <jeremy@intentsolutions.io>
tags	["saas","sentry","observability","logging","metrics","apm","grafana","opentelemetry"]
compatibility	Designed for Claude Code, also compatible with Codex and OpenClaw

Sentry Observability Integration

Overview

Wire Sentry into your logging, metrics, APM, and dashboard toolchain so every error carries full context and every metric correlates back to root-cause events. This skill covers three integration layers: structured logging (winston, pino, structlog) with Sentry event ID correlation, business metrics with error-rate tracking, and cross-tool linking via Sentry Discover, Grafana webhooks, and APM tools.

See also: Logging integration details | Metrics patterns | APM tool cross-linking

Prerequisites

Sentry SDK v8+ installed (@sentry/node for Node.js, sentry-sdk for Python)
At least one structured logger configured (winston, pino, or structlog)
Sentry project DSN available in environment (SENTRY_DSN)
Dashboard platform accessible (Sentry Discover, Grafana, or Datadog)
Alert routing strategy decided (who gets paged, where warnings go)

Instructions

Step 1 — Attach Sentry Event IDs to Structured Logs

The core pattern: every log line that triggers a Sentry event carries the event ID, and every Sentry event carries the log context. This creates a two-way link between your log aggregator and Sentry.

Winston (Node.js) — custom transport:

import winston from 'winston';
import * as Sentry from '@sentry/node';

class SentryTransport extends winston.Transport {
  log(info: any, callback: () => void) {
    setImmediate(callback);

    if (info.level === 'error' || info.level === ) {
       error = info.  
        ? info.
        :  (info.);

      .( {
        scope.(, );
        scope.(, {
          : info.,
          : info.,
          : info.,
        });
         eventId = .(error);
        info. = eventId;
        info. = ;
      });
    }
  }
}

 logger = winston.({
  : { :  },
  : [
     winston..({ : winston..() }),
     (),
  ],
});

import pino from 'pino';
import * as Sentry from '@sentry/node';

const logger = pino({
  hooks: {
    logMethod(inputArgs, method, level) {
      if (level >= 50) { // 50 = error, 60 = fatal
        const [obj, msg] = typeof inputArgs[0] === 'object'
          ? [inputArgs[0], inputArgs[1]]
          : [{}, inputArgs[0]];

        Sentry.withScope((scope) => {
          scope.setTag('logger', 'pino');
          const eventId = Sentry.captureException(
            obj.err instanceof Error ? obj.err : new Error(String(msg))
          );
          if (typeof inputArgs[0] === 'object') {
            inputArgs[0].sentry_event_id = eventId;
          }
        });
      }
      return method.apply(this, inputArgs);
    },
  },
});

import { randomUUID } from 'crypto';
import * as Sentry from '@sentry/node';

app.use((req, res, next) => {
  const requestId = (req.headers['x-request-id'] as string) || randomUUID();
  req.requestId = requestId;
  res.setHeader('x-request-id', requestId);
  Sentry.setTag('request_id', requestId);
  req.log = logger.child({ requestId, path: req.path });
  next();
});

import * as Sentry from '@sentry/node';

// Counter — track error rates alongside business events
Sentry.metrics.increment('checkout.attempted', 1, {
  tags: { payment_provider: 'stripe', plan: 'enterprise' },
});

Sentry.metrics.increment('checkout.failed', 1, {
  tags: { payment_provider: 'stripe', failure_reason: 'timeout' },
});

// Distribution — track latency with error correlation
Sentry.metrics.distribution('api.response_time', responseTimeMs, {
  tags: { endpoint: '/api/orders', status_code: String(res.statusCode) },
  unit: 'millisecond',
});

// Gauge — track queue depth, connection pool size
Sentry.metrics.gauge('db.pool.active', pool.activeCount, {
  tags: { database: 'primary' },
});

// Set — track unique affected users during incidents
Sentry.metrics.set('incident.affected_users', userId, {
  tags: { incident: 'payment-outage-2026-03' },
});

Scenario	Use Sentry Performance	Use Datadog/New Relic
Frontend + backend in one view	Yes — unified error + perf traces	Overkill if Sentry covers your stack
Infrastructure metrics (CPU, memory)	No — Sentry does not collect infra	Yes — native host agent collection
100+ custom metric series	Limited query constraints	Yes — built for high-cardinality
Budget-constrained, < 5 services	Yes — one tool, one bill	Unnecessary cost

import tracer from 'dd-trace';
import * as Sentry from '@sentry/node';

// dd-trace MUST be initialized before @sentry/node
Sentry.init({
  dsn: process.env.SENTRY_DSN,
  beforeSend(event) {
    const span = tracer.scope().active();
    if (span) {
      const traceId = span.context().toTraceId();
      event.tags = { ...event.tags, 'dd.trace_id': traceId };
      event.contexts = {
        ...event.contexts,
        datadog: {
          trace_url: `https://app.datadoghq.com/apm/trace/${traceId}`,
          trace_id: traceId,
        },
      };
    }
    return event;
  },
});

import * as Sentry from '@sentry/node';

function setMonitoringContext(req: Request) {
  const traceId = Sentry.getActiveSpan()?.spanContext().traceId;
  const spanId = Sentry.getActiveSpan()?.spanContext().spanId;
  const requestId = req.headers['x-request-id'] as string || crypto.randomUUID();

  // setContext creates a named section in the Sentry event sidebar
  Sentry.setContext('monitoring', {
    traceId,
    spanId,
    requestId,
    grafana_dashboard: `https://grafana.example.com/d/abc123?var-trace_id=${traceId}`,
    kibana_logs: `https://kibana.example.com/app/logs?query=request_id:${requestId}`,
    datadog_trace: traceId
      ? `https://app.datadoghq.com/apm/trace/${traceId}`
      : undefined,
  });

  Sentry.setTag('request_id', requestId);
  Sentry.setTag('trace_id', traceId || 'none');
  Sentry.setTag('deployment', process.env.DEPLOYMENT_ID || 'unknown');
}

app.use((req, res, next) => {
  setMonitoringContext(req);
  next();
});

// Receive Sentry webhook, create Grafana annotation
app.post('/sentry-to-grafana', async (req, res) => {
  const { event } = req.body;
  if (!event) return res.status(200).send('ignored');

  await fetch(`${process.env.GRAFANA_URL}/api/annotations`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${process.env.GRAFANA_API_KEY}`,
    },
    body: JSON.stringify({
      dashboardUID: process.env.GRAFANA_DASHBOARD_UID,
      panelId: 1,
      time: new Date(event.datetime).getTime(),
      tags: ['sentry', event.level, event.project],
      text: `**${event.title}**\nLevel: ${event.level}\nView in Sentry`,
    }),
  });

  res.status(201).json({ status: 'annotation_created' });
});

Issue Alert: "Critical Production Error"
  When: An event is first seen
  If: level is fatal AND environment is production
  Then: PagerDuty (Critical) + #alerts-critical Slack + Grafana annotation
  Frequency: Once per issue

Metric Alert: "Error Rate Spike"
  When: Error count > 50 in 5 minutes
  Then: PagerDuty (High) + #alerts-production Slack + webhook to Grafana
  Resolve: Error count < 5 for 10 minutes

Metric Alert: "Latency Regression"
  When: p95(transaction.duration) for /api/* > 2000ms for 10 minutes
  Then: #alerts-performance Slack + JIRA ticket via webhook
  Resolve: p95 < 1000ms for 15 minutes

Error	Cause	Solution
Sentry event IDs missing from logs	Transport/processor not wired up	Verify `SentryTransport` is in Winston transports or `sentry_processor` is in structlog chain
`beforeSend` silently dropping events	Handler throws or returns `undefined`	Wrap `beforeSend` in try/catch, always return `event` on error paths
Grafana annotations not appearing	Webhook URL wrong or API key expired	Test webhook with `curl -X POST` first; check Grafana API key has annotation write
Datadog trace IDs not matching	`dd-trace` not initialized before Sentry	Import and init `dd-trace` before `@sentry/node`
Sentry metrics not visible	Feature not enabled on plan	Custom metrics require Business plan or higher
Duplicate events from logger	SDK auto-capture and transport both fire	Use `beforeSend` to deduplicate, or disable auto-capture for handled errors
Webhook payload format changed	Sentry API version upgrade	Pin webhook to API v0; validate payload shape in receiver

import express from 'express';
import pino from 'pino';
import * as Sentry from '@sentry/node';
import { randomUUID } from 'crypto';

Sentry.init({ dsn: process.env.SENTRY_DSN, tracesSampleRate: 0.1 });
const logger = pino({ level: 'info' });
const app = express();

app.use((req, res, next) => {
  const requestId = (req.headers['x-request-id'] as string) || randomUUID();
  req.requestId = requestId;
  res.setHeader('x-request-id', requestId);
  Sentry.setTag('request_id', requestId);
  req.log = logger.child({ requestId, path: req.path, method: req.method });
  next();
});

app.get('/api/orders/:id', async (req, res) => {
  try {
    const order = await db.orders.findById(req.params.id);
    if (!order) {
      req.log.warn({ orderId: req.params.id }, 'Order not found');
      return res.status(404).json({ error: 'Not found' });
    }
    res.json(order);
  } catch (error) {
    Sentry.withScope((scope) => {
      scope.setContext('request', { params: req.params, requestId: req.requestId });
      const eventId = Sentry.captureException(error);
      req.log.error({
        err: error,
        sentry_event_id: eventId,
        sentry_url: `https://sentry.io/issues/?query=${eventId}`,
      }, 'Order fetch failed');
    });
    res.status(500).json({ error: 'Internal error', request_id: req.requestId });
  }
});

Sentry.setupExpressErrorHandler(app);