Labsco
getsentry logo

sentry-setup-metrics

✓ Official★ 2

by sentry · part of getsentry/sentry-for-cursor

Setup Sentry Metrics in any project. Use this when asked to add Sentry metrics, track custom metrics, setup counters/gauges/distributions, or instrument application performance metrics. Supports JavaScript, TypeScript, Python, React, Next.js, and Node.js.

🔥🔥🔥✓ VerifiedFreeQuick setup
#email#automation#payments#database#git#maps#monitoring
🧰 Not standalone. This skill ships with getsentry/sentry-for-cursor and only works together with that tool — install the tool first, then add this skill.

This is the playbook your agent receives when the skill activates — you don't need to read it to use the skill, but it's here to audit before installing.

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:

TypePurposeUse CasesAggregations
CounterTrack cumulative occurrencesButton clicks, API calls, errorssum, per_second, per_minute
GaugePoint-in-time snapshotsQueue depth, memory usage, connectionsmin, max, avg
DistributionStatistical analysis of valuesResponse times, cart amounts, query durationp50, 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 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 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:

CategoryUnits
Timenanosecond, microsecond, millisecond, second, minute, hour, day, week
Sizebit, byte, kilobyte, megabyte, gigabyte, terabyte
Currencyusd, eur, gbp (or any ISO currency code)
Rateratio, percent
Othernone (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.

Summary Checklist

Provide this checklist after setup:


## 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"}` |