sentry-setup-metrics

What this skill does

# 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

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

If version is below 10.25.0, inform user to upgrade:
```bash
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):**

```javascript
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:

```javascript
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:

```javascript
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

```javascript
// 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

```javascript
// 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

```javascript
// 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

```javascript
// 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

```bash
pip show sentry-sdk | grep Version
```

If version is below 2.44.0:
```bash
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)

```python
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

```python
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
    a