sentry-setup-metrics

OverviewHistoryStatsSecurity

npx skills add getsentry/sentry-for-cursor --skill sentry-setup-metrics

Documentation

SKILL.md

npx skills add ...

Documentation

SKILL.md

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.

npx skills add getsentry/sentry-for-cursor --skill sentry-setup-metrics

Documentation

SKILL.mdView 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:

Verify SDK version meets minimum requirements (JS: 10.25.0+, Python: 2.44.0+)
Ensure metrics aren't disabled (enableMetrics: false)
Check DSN is correct
Wait a few minutes - metrics are buffered before sending
Try manual flush: await Sentry.flush() or check aggregation window

Issue: Too many metrics being sent

Solutions:

Use beforeSendMetric to filter unnecessary metrics
Reduce attribute cardinality
Sample metrics on high-traffic paths
Aggregate client-side before sending

Issue: High cardinality warnings

Solutions:

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

Issue: Metrics not linked to traces

Solutions:

Ensure tracing is enabled alongside metrics
Emit metrics within traced spans
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"}`

npx skills add getsentry/sentry-for-cursor --skill sentry-setup-metrics

Documentation

SKILL.md

npx skills add getsentry/sentry-for-cursor --skill sentry-setup-metrics

Documentation

SKILL.mdView 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:

Verify SDK version meets minimum requirements (JS: 10.25.0+, Python: 2.44.0+)
Ensure metrics aren't disabled (enableMetrics: false)
Check DSN is correct
Wait a few minutes - metrics are buffered before sending
Try manual flush: await Sentry.flush() or check aggregation window

Issue: Too many metrics being sent

Solutions:

Use beforeSendMetric to filter unnecessary metrics
Reduce attribute cardinality
Sample metrics on high-traffic paths
Aggregate client-side before sending

Issue: High cardinality warnings

Solutions:

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

Issue: Metrics not linked to traces

Solutions:

Ensure tracing is enabled alongside metrics
Emit metrics within traced spans
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"}`