sentry-setup-metrics

# 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 attributes={ "template": "newsletter", "batch_id": "batch_123", } ) ``` ### Gauge Examples ```python 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 ```python 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` |