Setup Sentry Metrics Skill

Setup Sentry Metrics

Configure Sentry's custom metrics for tracking counters, gauges, and distributions.

Invoke This Skill When

User asks to "add Sentry metrics" or "track custom metrics"
User wants counters, gauges, or distributions
User asks about Sentry.metrics or sentry_sdk.metrics

Quick Reference

| Platform | Min SDK | API | |----------|---------|-----| | JavaScript | 10.25.0+ | Sentry.metrics.* | | Python | 2.44.0+ | sentry_sdk.metrics.* |

Note: Ruby does not have metrics support.

Metric Types

| Type | Purpose | Example Use Cases | |------|---------|-------------------| | Counter | Cumulative counts | API calls, clicks, errors | | Gauge | Point-in-time values | Queue depth, memory, connections | | Distribution | Statistical values | Response times, cart amounts |

JavaScript Setup

Metrics are enabled by default in SDK 10.25.0+.

Counter

Sentry.metrics.count("api_call", 1, {
  attributes: { endpoint: "/api/users", status_code: 200 },
});

Gauge

Sentry.metrics.gauge("queue_depth", 42, {
  unit: "none",
  attributes: { queue: "jobs" },
});

Distribution

Sentry.metrics.distribution("response_time", 187.5, {
  unit: "millisecond",
  attributes: { endpoint: "/api/products" },
});

Filtering (optional)

Sentry.init({
  beforeSendMetric: (metric) => {
    if (metric.attributes?.sensitive) return null;
    return metric;
  },
});

Python Setup

Metrics are enabled by default in SDK 2.44.0+.

Counter

sentry_sdk.metrics.count("api_call", 1, attributes={"endpoint": "/api/users"})

Gauge

sentry_sdk.metrics.gauge("queue_depth", 42, attributes={"queue": "jobs"})

Distribution

sentry_sdk.metrics.distribution(
    "response_time", 187.5,
    unit="millisecond",
    attributes={"endpoint": "/api/products"}
)

Filtering (optional)

def before_send_metric(metric, hint):
    if metric.get("attributes", {}).get("sensitive"):
        return None
    return metric

sentry_sdk.init(dsn="YOUR_DSN", before_send_metric=before_send_metric)

Common Units

| Category | Values | |----------|--------| | Time | millisecond, second, minute, hour | | Size | byte, kilobyte, megabyte | | Currency | usd, eur, gbp | | Other | none, percent, ratio |

Timing Helper Pattern

JavaScript

async function withTiming(name, fn, attrs = {}) {
  const start = performance.now();
  try { return await fn(); }
  finally {
    Sentry.metrics.distribution(name, performance.now() - start, {
      unit: "millisecond", attributes: attrs,
    });
  }
}

Python

import time, sentry_sdk

def track_duration(name, **attrs):
    def decorator(fn):
        def wrapper(*args, **kwargs):
            start = time.time()
            try: return fn(*args, **kwargs)
            finally:
                sentry_sdk.metrics.distribution(
                    name, (time.time() - start) * 1000,
                    unit="millisecond", attributes=attrs
                )
        return wrapper
    return decorator

Best Practices

Low cardinality: Avoid user IDs, request IDs in attributes
Namespaced names: api.request.duration, not duration
Flush on exit: Call Sentry.flush() before process exit

Troubleshooting

| Issue | Solution | |-------|----------| | Metrics not appearing | Verify SDK version, check DSN, wait for buffer flush | | High cardinality warning | Remove unique IDs from attributes | | Too many metrics | Use beforeSendMetric to filter |

Agent Skills: Setup Sentry Metrics

Skill Files