# Custom Metrics

> Learn how to emit custom metrics from your applications using TraceKit SDKs. Monitor counters, gauges, and histograms with the Metrics Explorer.

- Canonical: https://tracekit.dev/docs/metrics

# 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

**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 and Labels

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

### Example with Tags

```go
// 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.

## 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](https://app.tracekit.dev/metrics)

## 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](/docs/languages/go#custom-metrics) -- tracekit-go-sdk
- [Python](/docs/languages/python#custom-metrics) -- tracekit-apm
- [Node.js](/docs/languages/nodejs#custom-metrics) -- @tracekit/node-apm
- [PHP](/docs/languages/php#custom-metrics) -- tracekit/php-apm
- [Laravel](/docs/frameworks/laravel#custom-metrics) -- tracekit/laravel-apm
- [Java](/docs/languages/java#custom-metrics) -- tracekit-java-sdk
- [.NET](/docs/languages/dotnet#custom-metrics) -- TraceKit.AspNetCore
- [Ruby](/docs/languages/ruby#custom-metrics) -- 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](https://app.tracekit.dev/metrics)
- [View Dashboards](https://app.tracekit.dev/dashboards)