SOURCE: getsentry/sentry-for-claude

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

DO NOT EDIT: This file is synced from external source

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:

Type	Purpose	Use Cases	Aggregations
Counter	Track cumulative occurrences	Button clicks, API calls, errors	sum, per_second, per_minute
Gauge	Point-in-time snapshots	Queue depth, memory usage, connections	min, max, avg
Distribution	Statistical analysis of values	Response times, cart amounts, query duration	p50, p75, p95, p99, avg, min, max

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() are required unless user wants to disable or filter.

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:

Category	Units
Time	nanosecond, microsecond, millisecond, second, minute, hour, day, week
Size	bit, byte, kilobyte, megabyte, gigabyte, terabyte
Currency	usd, eur, gbp (or any ISO currency code)
Rate	ratio, percent
Other	none (default), or custom string

---

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

Platform	SDK Version	API Namespace
JavaScript	10.25.0+	Sentry.metrics.*
Python	2.44.0+	sentry_sdk.metrics.*

Method	JavaScript	Python
Counter	Sentry.metrics.count(name, value, options)	sentry_sdk.metrics.count(name, value, **kwargs)
Gauge	Sentry.metrics.gauge(name, value, options)	sentry_sdk.metrics.gauge(name, value, **kwargs)
Distribution	Sentry.metrics.distribution(name, value, options)	sentry_sdk.metrics.distribution(name, value, **kwargs)

Option	JavaScript	Python
Unit	{ unit: "millisecond" }	unit="millisecond"
Attributes	{ attributes: { key: "value" } }	attributes={"key": "value"}