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…

🔥🔥🔥✓ 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.

Setup Sentry Metrics in any project. Use this when asked to add Sentry metrics, track custom metrics, setup counters/gauges/distributions, or instrument…

Inspect the full instructions your agent will receiveExpand

This is the exact playbook injected into your agent when the skill activates — shown here so you can audit it before installing. You don't need to read it to use the skill.

by sentry

Setup Sentry Metrics in any project. Use this when asked to add Sentry metrics, track custom metrics, setup counters/gauges/distributions, or instrument… npx skills add https://github.com/getsentry/sentry-for-cursor --skill sentry-setup-metrics Download ZIPGitHub2

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:

Copy & paste — that's it
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

Copy & paste — that's it
// 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

Copy & paste — that's it
// 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

Copy & paste — that's it
// 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

Copy & paste — that's it
// 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

Copy & paste — that's it
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

Copy & paste — that's it
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

Copy & paste — that's it
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:

Copy & paste — that's it
# 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)

Copy & paste — that's it
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)

Copy & paste — that's it
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)

Copy & paste — that's it
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

Copy & paste — that's it
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

Copy & paste — that's it
// 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

Copy & paste — that's it
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:

Copy & paste — that's it

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