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

1. Instrument -- Add metric calls in your code using our SDK
2. Collect -- Metrics are batched and sent via OTLP protocol
3. Visualize -- Explore in Metrics Explorer or add to dashboards

Metric Types

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

Counter

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

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

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

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 and 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.

Metrics Explorer

The Metrics Explorer lets you browse, filter, and visualize all your custom metrics.

Features

• Search and Filter -- Find metrics by name, service, or type
• Time Series Charts -- Visualize metric values over time
• Statistics -- View avg, min, max, and percentiles
• Add to Dashboard -- Create widgets from any metric

Open Metrics Explorer

Dashboard Widgets

Add metric visualizations to your custom dashboards for real-time monitoring.

• Line Chart -- Time series visualization
• Gauge -- Single value display
• Table -- Multi-metric summary

SDK Implementation Guides

Choose your language to see specific code examples for emitting custom metrics:

• Go -- tracekit-go-sdk
• Python -- tracekit-apm
• Node.js -- @tracekit/node-apm
• PHP -- tracekit/php-apm
• Laravel -- tracekit/laravel-apm
• Java -- tracekit-java-sdk
• .NET -- TraceKit.AspNetCore
• Ruby -- tracekit

Best Practices

Use consistent naming across services

Agree on naming conventions across your team so metrics are discoverable and comparable.

Include units in metric names

Suffix with _ms, _bytes, _total, _ratio etc. to make the metric self-documenting.

Limit tag cardinality

Keep the number of unique tag value combinations reasonable (under 1000) to avoid performance issues.

Prefer counters for totals, gauges for current state

Counters aggregate well over time, gauges capture point-in-time snapshots.

Ready to Get Started?

Choose your SDK above to see implementation examples, or explore your existing metrics.

• Open Metrics Explorer
• View Dashboards