OpenTelemetry metrics: counter vs histogram vs gauge — choosing the right instrument

Developers use counters where histograms are needed (or vice versa), resulting in metrics that cannot answer the questions being asked. Using a gauge for request counts loses the ability to compute rates; using a counter for latency is meaningless.

Choose the instrument based on what you need to compute:

• Counter: monotonically increasing value — use for request counts, error counts, bytes sent. Compute rate() in queries.
• Histogram: distribution of values over time — use for latency, payload size, queue depth at processing time. Provides p50/p95/p99.
• Gauge: current value that can go up and down — use for active connections, memory usage, queue length.
• UpDownCounter: like a counter but can decrease — use for concurrent requests in flight.

const { metrics } = require('@opentelemetry/api');
const meter = metrics.getMeter('my-service');

const requestCounter = meter.createCounter('http.requests.total', {
  description: 'Total HTTP requests received',
});

const latencyHistogram = meter.createHistogram('http.request.duration', {
  description: 'HTTP request duration in milliseconds',
  unit: 'ms',
});

const activeConnections = meter.createObservableGauge('http.connections.active', {
  description: 'Currently active HTTP connections',
});

Metrics instruments map to different mathematical operations in query languages like PromQL. Using the wrong instrument means your queries will be incorrect or impossible.

Designing metrics for a new service or adding metrics to existing code