SOURCE: getsentry/sentry-for-claude

PATH: skills/sentry-setup-metrics/SKILL.md

Setup Sentry Metrics

This skill helps configure Sentry's custom metrics feature to track counters, gauges, and distributions across your applications.

When to Use This Skill

Invoke this skill when:

• User asks to "setup Sentry metrics" or "add custom metrics"
• User wants to "track metrics in Sentry"
• User requests "counters", "gauges", or "distributions" with Sentry
• User mentions they want to track business KPIs or application health
• User asks about

  Sentry.metrics

  or

  sentry_sdk.metrics

• User wants to instrument performance metrics

Platform Support

Supported Platforms:

• JavaScript/TypeScript (SDK 10.25.0+): Next.js, React, Node.js, Browser
• Python (SDK 2.44.0+): Django, Flask, FastAPI, general Python

Note: Ruby does not currently have dedicated metrics support in the Sentry SDK.

Metric Types Overview

Before setup, explain the three metric types to the user:

Platform Detection

JavaScript/TypeScript Detection

Check for these files:

• package.json

  - Read to identify framework and Sentry SDK version
• Look for

  @sentry/nextjs

  ,

  @sentry/react

  ,

  @sentry/node

  ,

  @sentry/browser

• Check if SDK version is 10.25.0+ (required for metrics)

Python Detection

Check for:

• requirements.txt

  ,

  pyproject.toml

  ,

  setup.py

  , or

  Pipfile

• Look for

  sentry-sdk

  version 2.44.0+ (required for metrics)

Required Information

Ask the user:

I'll help you set up Sentry Metrics. First, let me check your project setup.

After detecting the platform:

1. **What metrics do you want to track?**
   - Counters: Event counts (clicks, API calls, errors)
   - Gauges: Point-in-time values (queue depth, memory)
   - Distributions: Value analysis (response times, amounts)

2. **Do you need metric filtering?**
   - Yes: Configure beforeSendMetric to filter/modify metrics
   - No: Send all metrics as-is

JavaScript/TypeScript Configuration

Minimum SDK Version

• All JS platforms:

  10.25.0+

Step 1: Verify SDK Version

grep -E '"@sentry/(nextjs|react|node|browser)"' package.json

If version is below 10.25.0, inform user to upgrade:

npm install @sentry/nextjs@latest  # or appropriate package

Step 2: Verify Metrics Are Enabled

Metrics are enabled by default in SDK 10.25.0+. No changes to

Sentry.init()

Locate init files:

• Next.js:

  instrumentation-client.ts

  ,

  sentry.server.config.ts

  ,

  sentry.edge.config.ts

• React:

  src/index.tsx

  ,

  src/main.tsx

  , or dedicated sentry config file
• Node.js: Entry point file or dedicated sentry config
• Browser: Entry point or config file

Optional: Explicitly enable (not required):

import * as Sentry from "@sentry/nextjs"; // or @sentry/react, @sentry/node

Sentry.init({
  dsn: "YOUR_DSN_HERE",

  // Metrics enabled by default, but can be explicit
  enableMetrics: true,

  // ... other existing config
});

Step 3: Add Metric Filtering (Optional)

If user wants to filter metrics before sending:

Sentry.init({
  dsn: "YOUR_DSN_HERE",

  beforeSendMetric: (metric) => {
    // Drop metrics with sensitive attributes
    if (metric.attributes?.sensitive === true) {
      return null;
    }

    // Remove specific attribute before sending
    if (metric.attributes?.internal) {
      delete metric.attributes.internal;
    }

    return metric;
  },
});

Step 4: Disable Metrics (If Requested)

If user explicitly wants to disable metrics:

Sentry.init({
  dsn: "YOUR_DSN_HERE",
  enableMetrics: false,
});

JavaScript Metrics API Examples

Provide these examples to the user based on their use case:

Counter Examples

// Basic counter - increment by 1
Sentry.metrics.count("button_click", 1);

// Counter with attributes for filtering/grouping
Sentry.metrics.count("api_call", 1, {
  attributes: {
    endpoint: "/api/users",
    method: "GET",
    status_code: 200,
  },
});

// Counter for errors
Sentry.metrics.count("checkout_error", 1, {
  attributes: {
    error_type: "payment_declined",
    payment_provider: "stripe",
  },
});

// Counter for business events
Sentry.metrics.count("email_sent", 1, {
  attributes: {
    template: "welcome",
    recipient_type: "new_user",
  },
});

Gauge Examples

// Basic gauge
Sentry.metrics.gauge("queue_depth", 42);

// Memory usage gauge
Sentry.metrics.gauge("memory_usage", process.memoryUsage().heapUsed, {
  unit: "byte",
  attributes: {
    process: "main",
  },
});

// Connection pool gauge
Sentry.metrics.gauge("db_connections", 15, {
  attributes: {
    pool: "primary",
    max_connections: 100,
  },
});

// Active users gauge
Sentry.metrics.gauge("active_users", currentUserCount, {
  attributes: {
    region: "us-east",
  },
});

Distribution Examples

// Response time distribution
Sentry.metrics.distribution("response_time", 187.5, {
  unit: "millisecond",
  attributes: {
    endpoint: "/api/products",
    method: "GET",
  },
});

// Cart value distribution
Sentry.metrics.distribution("cart_value", 149.99, {
  unit: "usd",
  attributes: {
    customer_tier: "premium",
  },
});

// Query duration distribution
Sentry.metrics.distribution("db_query_duration", 45.2, {
  unit: "millisecond",
  attributes: {
    query_type: "select",
    table: "users",
  },
});

// File size distribution
Sentry.metrics.distribution("upload_size", 2048576, {
  unit: "byte",
  attributes: {
    file_type: "image",
  },
});

Manual Flush

// Force pending metrics to send immediately
await Sentry.flush();

// Useful before process exit or after critical operations
process.on("beforeExit", async () => {
  await Sentry.flush();
});

Python Configuration

Minimum SDK Version

• sentry-sdk

  version

  2.44.0+

Step 1: Verify SDK Version

pip show sentry-sdk | grep Version

If version is below 2.44.0:

pip install --upgrade sentry-sdk

Step 2: Verify Metrics Are Enabled

Metrics are enabled by default in SDK 2.44.0+. No changes required unless filtering is needed.

Common init locations:

• Django:

  settings.py

• Flask:

  app.py

  or

  __init__.py

• FastAPI:

  main.py

• General: Entry point or dedicated config file

Step 3: Add Metric Filtering (Optional)

import sentry_sdk

def before_send_metric(metric, hint):
    # Drop metrics with specific attributes
    if metric.get("attributes", {}).get("sensitive"):
        return None

    # Modify metric before sending
    if metric.get("attributes", {}).get("internal"):
        del metric["attributes"]["internal"]

    return metric

sentry_sdk.init(
    dsn="YOUR_DSN_HERE",
    before_send_metric=before_send_metric,
)

Python Metrics API Examples

Counter Examples

import sentry_sdk

# Basic counter
sentry_sdk.metrics.count("button_click", 1)

# Counter with attributes
sentry_sdk.metrics.count(
    "api_call",
    1,
    attributes={
        "endpoint": "/api/users",
        "method": "GET",
        "status_code": 200,
    }
)

# Counter for errors
sentry_sdk.metrics.count(
    "checkout_error",
    1,
    attributes={
        "error_type": "payment_declined",
        "payment_provider": "stripe",
    }
)

# Business event counter
sentry_sdk.metrics.count(
    "email_sent",
    5,  # Can increment by more than 1
    attributes={
        "template": "newsletter",
        "batch_id": "batch_123",
    }
)

Gauge Examples

import sentry_sdk
import psutil

# Basic gauge
sentry_sdk.metrics.gauge("queue_depth", 42)

# Memory usage gauge
sentry_sdk.metrics.gauge(
    "memory_usage",
    psutil.virtual_memory().used,
    unit="byte",
    attributes={"host": "web-01"}
)

# Database connection gauge
sentry_sdk.metrics.gauge(
    "db_connections",
    connection_pool.size(),
    attributes={
        "pool": "primary",
        "max": connection_pool.max_size,
    }
)

# Cache hit rate gauge
sentry_sdk.metrics.gauge(
    "cache_hit_rate",
    0.85,
    attributes={"cache": "redis"}
)

Distribution Examples

import sentry_sdk
import time

# Response time distribution
start = time.time()
# ... do work ...
duration_ms = (time.time() - start) * 1000

sentry_sdk.metrics.distribution(
    "response_time",
    duration_ms,
    unit="millisecond",
    attributes={
        "endpoint": "/api/products",
        "method": "GET",
    }
)

# Order value distribution
sentry_sdk.metrics.distribution(
    "order_value",
    order.total,
    unit="usd",
    attributes={
        "customer_tier": customer.tier,
        "payment_method": order.payment_method,
    }
)

# Query duration distribution
sentry_sdk.metrics.distribution(
    "db_query_duration",
    query_time_ms,
    unit="millisecond",
    attributes={
        "query_type": "select",
        "table": "orders",
    }
)

Framework-Specific Notes

Next.js

• Metrics work on both client and server
• Consider tracking in API routes and server components
• Use attributes to distinguish client vs server metrics

React (Browser)

• Track user interactions (clicks, form submissions)
• Monitor component render performance
• Be mindful of metric volume from client-side

Node.js

• Track API response times, queue depths, background job metrics
• Use gauges for resource monitoring
• Flush metrics before process exit

Django

• Track view response times
• Monitor database query performance
• Use middleware for automatic request metrics

Flask/FastAPI

• Track endpoint performance
• Monitor external API call durations
• Use decorators or middleware for automatic instrumentation

Common Units

Use these units for better readability in Sentry dashboard:

nanosecond

microsecond

millisecond

second

minute

hour

day

week

bit

byte

kilobyte

megabyte

gigabyte

terabyte

usd

eur

gbp

ratio

percent

none

Best Practices

DO Use Metrics For:

• Business KPIs (orders, signups, revenue)
• Application health (error rates, latency)
• Resource utilization (queue depth, connections)
• User actions (clicks, page views, feature usage)

DON'T Use Metrics For:

• Infrastructure monitoring (use dedicated tools)
• Log aggregation (use Sentry Logs instead)
• Full request tracing (use Sentry Tracing)
• High-cardinality data in attributes

Naming Conventions:

# Good - descriptive, namespaced
api.request.duration
checkout.cart.value
user.signup.completed

# Avoid - vague, inconsistent
duration
value1
myMetric

Attribute Guidelines:

• Keep cardinality low (avoid user IDs, request IDs)
• Use consistent attribute names across metrics
• Include relevant context for filtering
• Avoid sensitive data in attributes

Instrumentation Patterns

Timing Helper (JavaScript)

async function withTiming(name, fn, attributes = {}) {
  const start = performance.now();
  try {
    return await fn();
  } finally {
    const duration = performance.now() - start;
    Sentry.metrics.distribution(name, duration, {
      unit: "millisecond",
      attributes,
    });
  }
}

// Usage
const result = await withTiming(
  "api.external.duration",
  () => fetch("https://api.example.com/data"),
  { service: "example-api" }
);

Timing Decorator (Python)

import functools
import time
import sentry_sdk

def track_duration(metric_name, **extra_attrs):
    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            start = time.time()
            try:
                return func(*args, **kwargs)
            finally:
                duration_ms = (time.time() - start) * 1000
                sentry_sdk.metrics.distribution(
                    metric_name,
                    duration_ms,
                    unit="millisecond",
                    attributes=extra_attrs,
                )
        return wrapper
    return decorator

# Usage
@track_duration("db.query.duration", query_type="user_lookup")
def get_user_by_id(user_id):
    return db.query(User).filter(User.id == user_id).first()

Request Middleware (Express/Node.js)

function metricsMiddleware(req, res, next) {
  const start = performance.now();

  res.on("finish", () => {
    const duration = performance.now() - start;

    Sentry.metrics.distribution("http.request.duration", duration, {
      unit: "millisecond",
      attributes: {
        method: req.method,
        route: req.route?.path || req.path,
        status_code: res.statusCode,
      },
    });

    Sentry.metrics.count("http.request.count", 1, {
      attributes: {
        method: req.method,
        status_code: res.statusCode,
      },
    });
  });

  next();
}

app.use(metricsMiddleware);

Django Middleware

import time
import sentry_sdk

class SentryMetricsMiddleware:
    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        start = time.time()
        response = self.get_response(request)
        duration_ms = (time.time() - start) * 1000

        sentry_sdk.metrics.distribution(
            "http.request.duration",
            duration_ms,
            unit="millisecond",
            attributes={
                "method": request.method,
                "path": request.path,
                "status_code": response.status_code,
            },
        )

        return response

# Add to MIDDLEWARE in settings.py

Verification Steps

After setup, provide these verification instructions:

JavaScript Verification

// Add this temporarily to test
Sentry.metrics.count("test_metric", 1, {
  attributes: { test: true },
});

Sentry.metrics.gauge("test_gauge", 42);

Sentry.metrics.distribution("test_distribution", 100, {
  unit: "millisecond",
});

// Force flush to send immediately
await Sentry.flush();

Python Verification

import sentry_sdk

sentry_sdk.metrics.count("test_metric", 1, attributes={"test": True})
sentry_sdk.metrics.gauge("test_gauge", 42)
sentry_sdk.metrics.distribution("test_distribution", 100, unit="millisecond")

Tell user to check their Sentry dashboard under Metrics section to verify metrics are arriving.

Common Issues and Solutions

Issue: Metrics not appearing in Sentry

Solutions:

1. Verify SDK version meets minimum requirements (JS: 10.25.0+, Python: 2.44.0+)
2. Ensure metrics aren't disabled (

   enableMetrics: false

   )
3. Check DSN is correct
4. Wait a few minutes - metrics are buffered before sending
5. Try manual flush:

   await Sentry.flush()

   or check aggregation window

Issue: Too many metrics being sent

Solutions:

1. Use

   beforeSendMetric

   to filter unnecessary metrics
2. Reduce attribute cardinality
3. Sample metrics on high-traffic paths
4. Aggregate client-side before sending

Issue: High cardinality warnings

Solutions:

1. Avoid user IDs, request IDs, timestamps in attributes
2. Use categories instead of specific values
3. Limit unique attribute value combinations

Issue: Metrics not linked to traces

Solutions:

1. Ensure tracing is enabled alongside metrics
2. Emit metrics within traced spans
3. Check that trace sampling isn't dropping related traces

Summary Checklist

Provide this checklist after setup:

## Sentry Metrics Setup Complete

### Configuration Applied:
- [ ] SDK version verified (JS: 10.25.0+, Python: 2.44.0+)
- [ ] Metrics enabled (default) or explicitly configured
- [ ] Metric filtering configured (if requested)

### Instrumentation Added:
- [ ] Counter metrics for events/actions
- [ ] Gauge metrics for point-in-time values
- [ ] Distribution metrics for timing/values
- [ ] Appropriate units specified
- [ ] Meaningful attributes added

### Next Steps:
1. Run your application
2. Trigger actions that emit metrics
3. Check Sentry dashboard > Metrics section
4. Create dashboards and alerts based on metrics

Quick Reference

Sentry.metrics.*

sentry_sdk.metrics.*

Sentry.metrics.count(name, value, options)

sentry_sdk.metrics.count(name, value, **kwargs)

Sentry.metrics.gauge(name, value, options)

sentry_sdk.metrics.gauge(name, value, **kwargs)

Sentry.metrics.distribution(name, value, options)

sentry_sdk.metrics.distribution(name, value, **kwargs)

{ unit: "millisecond" }

unit="millisecond"

{ attributes: { key: "value" } }

attributes={"key": "value"}