Custom Metrics

Emit custom metrics from your applications to track business KPIs, performance indicators, and operational data alongside your traces.

What are Custom Metrics?

Custom metrics allow you to track any numerical data from your application - user signups, queue lengths, cache hit rates, payment amounts, or any business metric that matters to you.

📊

Business Metrics

Revenue, signups, orders

⚡

Performance Metrics

Queue size, cache hits, latencies

🔧

Operational Metrics

Connection pools, memory, threads

How It Works

Instrument

Add metric calls in your code using our SDK

Collect

Metrics are batched and sent via OTLP protocol

Visualize

Explore in Metrics Explorer or add to dashboards

Metric Types

TraceKit supports three types of metrics, each suited for different use cases:

Counter

Monotonic

A value that only increases. Use for counting events that happen over time.

Example use cases:

• Total HTTP requests served
• Number of user signups
• Orders processed
• Emails sent

Gauge

Point-in-time

A value that can go up or down. Use for measuring current state at a point in time.

Example use cases:

• Current queue length
• Active user sessions
• Memory usage percentage
• Database connection pool size

Histogram

Distribution

Records the distribution of values. Use for measuring things like response times or request sizes.

Example use cases:

• API response times
• Request payload sizes
• Database query durations
• File upload sizes

Metrics vs Traces

Both metrics and traces are valuable for observability, but they serve different purposes:

Custom Metrics

✓ Aggregated numerical data
✓ Low overhead, high volume
✓ Business KPIs and SLIs
✓ Real-time dashboards
✓ Alerting thresholds

Distributed Traces

✓ Individual request flows
✓ Detailed context and attributes
✓ Root cause analysis
✓ Service dependencies
✓ Error debugging

Pro Tip: Use metrics for "what's happening" (rates, counts, current values) and traces for "why it's happening" (detailed request flow, error context).

Naming Conventions

Consistent naming makes metrics easier to discover, query, and understand.

Recommended Pattern

<namespace>.<subsystem>.<metric_name>_<unit>

Good examples:

• app.users.signups_total
• app.orders.revenue_usd
• app.cache.hit_ratio
• app.queue.length
• app.api.response_time_ms

Avoid:

• signups (too vague)
• my-metric (use underscores)
• UserSignupCount (use lowercase)
• response_time (missing unit)

Tags & Labels

Tags (also called labels or attributes) add dimensions to your metrics for filtering and grouping.

Example with Tags

// Record API latency with tags
meter.RecordHistogram("app.api.response_time_ms", 45.2, map[string]string{
    "endpoint": "/api/users",
    "method":   "GET",
    "status":   "200",
})

This allows you to filter by endpoint, method, or status code in the Metrics Explorer.

Cardinality Warning: Avoid high-cardinality tags like user IDs or request IDs. Stick to bounded values like HTTP methods, status codes, or region names.