TraceKit Custom Metrics

When To Use

Use this skill when the user asks to:

Track custom metrics, KPIs, or business data
Set up counters, gauges, or histograms
Monitor application performance with custom measurements
Record operational metrics alongside traces

Non-Negotiable Rules

Never hardcode API keys in code snippets. Always use environment variables.
Follow the naming convention <namespace>.<subsystem>.<metric_name>_<unit> (e.g., app.orders.revenue_usd, app.users.signups_total).
Limit tag cardinality — avoid high-cardinality tags (like user IDs or request IDs) to prevent performance degradation.
Always include a verification step confirming metrics appear in https://app.tracekit.dev/metrics.

Prerequisites

The base TraceKit SDK must already be initialized in your application. If not, use the appropriate SDK skill first:

tracekit-go-sdk, tracekit-node-sdk, tracekit-python-sdk, tracekit-java-sdk, tracekit-ruby-sdk, tracekit-php-sdk, tracekit-laravel-sdk, tracekit-dotnet-sdk

Metrics are automatically buffered and exported via OTLP — no additional configuration is needed beyond the base SDK setup.

Metric Types

Counter

A value that only increases. Use for counting events over time (requests, signups, errors).

Methods: inc() (increment by 1), add(value) (add specific amount)

Gauge

A value that can go up or down. Use for measuring current state (queue length, active connections, memory usage).

Methods: set(value), inc(), dec()

Histogram

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

Methods: record(value)

Naming Convention

Follow this pattern: <namespace>.<subsystem>.<metric_name>_<unit>

Examples:

app.users.signups_total — counter for user signups
app.orders.revenue_usd — counter for revenue in USD
app.http.request_duration_ms — histogram for request latency
app.queue.pending_jobs — gauge for queue depth
app.cache.hit_ratio — gauge for cache effectiveness

Implementation by Language

Go

// Counter
counter := sdk.Counter("http.requests.total", map[string]string{
    "service": "api",
    "method":  "GET",
})
counter.Inc()
counter.Add(5)

// Gauge
gauge := sdk.Gauge("http.connections.active", nil)
gauge.Set(42)
gauge.Inc()
gauge.Dec()

// Histogram
histogram := sdk.Histogram("http.request.duration", map[string]string{
    "unit": "ms",
})
histogram.Record(45.2)
histogram.Record(123.5)

Node.js

// Counter
const counter = client.counter('http.requests.total', { service: 'api' });
counter.inc();
counter.add(5);

// Gauge
const gauge = client.gauge('http.connections.active');
gauge.set(42);
gauge.inc();
gauge.dec();

// Histogram
const histogram = client.histogram('http.request.duration', { unit: 'ms' });
histogram.record(45.2);
histogram.record(123.5);

Python

# Counter
counter = client.counter("http.requests.total", tags={"service": "api"})
counter.inc()
counter.add(5)

# Gauge
gauge = client.gauge("http.connections.active")
gauge.set(42)
gauge.inc()
gauge.dec()

# Histogram
histogram = client.histogram("http.request.duration", tags={"unit": "ms"})
histogram.record(45.2)
histogram.record(123.5)

Java

// Counter
Counter counter = sdk.counter("http.requests.total",
    Map.of("service", "api"));
counter.inc();
counter.add(5.0);

// Gauge
Gauge gauge = sdk.gauge("http.connections.active", Map.of());
gauge.set(42.0);
gauge.inc();
gauge.dec();

// Histogram
Histogram histogram = sdk.histogram("http.request.duration",
    Map.of("unit", "ms"));
histogram.record(45.2);
histogram.record(123.5);

Ruby

sdk = Tracekit.sdk

# Counter
counter = sdk.counter("http.requests.total", {
  service: "api",
  endpoint: "/users"
})
counter.add(1)
counter.add(5)

# Gauge
gauge = sdk.gauge("memory.usage.bytes")
gauge.set(1024 * 1024 * 512)
gauge.inc
gauge.dec

# Histogram
histogram = sdk.histogram("http.request.duration", {
  unit: "ms"
})
histogram.record(123.45)
histogram.record(67.89)

PHP

use TraceKit\PHP\MetricsRegistry;

$metrics = new MetricsRegistry($endpoint, $apiKey, 'my-service');

// Counter
$counter = $metrics->counter('http.requests.total', [
    'service' => 'api',
    'method' => 'GET',
]);
$counter->inc();
$counter->add(5);

// Gauge
$gauge = $metrics->gauge('http.connections.active');
$gauge->set(42);
$gauge->inc();
$gauge->dec();

// Histogram
$histogram = $metrics->histogram('http.request.duration', [
    'unit' => 'ms',
]);
$histogram->record(45.2);
$histogram->record(123.5);

.NET

var sdk = TracekitSDK.Create(config);

// Counter
var counter = sdk.Counter("http.requests.total",
    new() { ["service"] = "api" });
counter.Inc();
counter.Add(5);

// Gauge
var gauge = sdk.Gauge("http.connections.active");
gauge.Set(42);
gauge.Inc();
gauge.Dec();

// Histogram
var histogram = sdk.Histogram("http.request.duration",
    new() { ["unit"] = "ms" });
histogram.Record(45.2);
histogram.Record(123.5);

Tags Best Practices

Tags let you slice and filter metrics in the dashboard. Use them for dimensions you want to group by.

Good tags (low cardinality):

service, environment, region, method, status_code, endpoint

Bad tags (high cardinality — avoid):

user_id, request_id, session_id, timestamp, trace_id

Example with tags:

const counter = client.counter('app.orders.completed_total', {
  payment_method: 'stripe',
  plan: 'premium',
  region: 'us-east-1'
});
counter.inc();

Verification

After adding custom metrics:

Deploy or restart your application.
Trigger the code paths that record metrics (e.g., process some orders, handle some requests).
Open https://app.tracekit.dev/metrics (Metrics Explorer).
Search for your metric name (e.g., http.requests.total).
Confirm data points appear within 60 seconds.

Troubleshooting

Metrics not appearing in dashboard

Check SDK is initialized: Metrics require the base TraceKit SDK to be initialized with a valid API key.
Check metric names: Names must follow the dot-separated convention. Avoid spaces or special characters.
Check tag cardinality: If you have too many unique tag combinations, metrics may be dropped.

Unexpected metric values

Counters only go up: If you need a value that decreases, use a gauge instead.
Histograms record distributions: Individual values are not stored — only aggregated percentiles (p50, p90, p99).
Check units: Ensure you are recording in consistent units (e.g., always milliseconds, not sometimes seconds).

Next Steps

Alerts — Set up alerts on metric thresholds using the tracekit-alerts skill
Dashboards — Create custom dashboards combining metrics and traces at https://app.tracekit.dev/dashboards
Distributed Tracing — Correlate metrics with traces for full observability

References

Custom Metrics docs: https://app.tracekit.dev/docs/metrics
TraceKit docs root: https://app.tracekit.dev/docs
Dashboard: https://app.tracekit.dev

tracekit-custom-metrics