123 lines
3.7 KiB
TypeScript
123 lines
3.7 KiB
TypeScript
import type {
|
|
Attributes,
|
|
Counter,
|
|
Histogram,
|
|
Meter,
|
|
ObservableGauge,
|
|
} from "@opentelemetry/api";
|
|
|
|
/**
|
|
* Create a monotonically increasing counter instrument on the given meter.
|
|
*
|
|
* Counters track cumulative totals that never decrease (e.g. total requests,
|
|
* total errors). Use a histogram instead when you need distribution data.
|
|
*
|
|
* @param meter - OTel `Meter` instance to create the counter on.
|
|
* @param name - Instrument name following the OTel naming convention (`<domain>.<metric>`).
|
|
* @param description - Optional human-readable description shown in metric explorers.
|
|
* @returns An OTel `Counter` instrument.
|
|
*
|
|
* @example
|
|
* ```ts
|
|
* const requestCounter = createCounter(meter, "http.server.request_count", "Total HTTP requests");
|
|
* requestCounter.add(1, { "http.method": "GET" });
|
|
* ```
|
|
*/
|
|
export function createCounter(
|
|
meter: Meter,
|
|
name: string,
|
|
description?: string
|
|
): Counter {
|
|
return meter.createCounter(
|
|
name,
|
|
description !== undefined ? { description } : {}
|
|
);
|
|
}
|
|
|
|
/**
|
|
* Create a histogram instrument on the given meter.
|
|
*
|
|
* Histograms record the distribution of values (e.g. request durations,
|
|
* payload sizes). Use this over a counter when percentile data matters.
|
|
*
|
|
* @param meter - OTel `Meter` instance.
|
|
* @param name - Instrument name.
|
|
* @param description - Optional description.
|
|
* @param unit - Optional unit string (e.g. `"ms"`, `"By"`).
|
|
* @returns An OTel `Histogram` instrument.
|
|
*
|
|
* @example
|
|
* ```ts
|
|
* const latency = createHistogram(meter, "http.server.duration", "Request duration", "ms");
|
|
* latency.record(42, { "http.route": "/api/users" });
|
|
* ```
|
|
*/
|
|
export function createHistogram(
|
|
meter: Meter,
|
|
name: string,
|
|
description?: string,
|
|
unit?: string
|
|
): Histogram {
|
|
const opts: { description?: string; unit?: string } = {};
|
|
if (description !== undefined) opts.description = description;
|
|
if (unit !== undefined) opts.unit = unit;
|
|
return meter.createHistogram(name, opts);
|
|
}
|
|
|
|
/**
|
|
* Create an observable (asynchronous) gauge instrument on the given meter.
|
|
*
|
|
* Observable gauges report the current value of a resource at collection time
|
|
* (e.g. current queue depth, active connections). The callback is registered
|
|
* separately via the `ObservableGauge.addCallback` API.
|
|
*
|
|
* @param meter - OTel `Meter` instance.
|
|
* @param name - Instrument name.
|
|
* @param description - Optional description.
|
|
* @returns An OTel `ObservableGauge` instrument.
|
|
*
|
|
* @example
|
|
* ```ts
|
|
* const gauge = createGauge(meter, "system.memory.usage", "Current memory usage in bytes");
|
|
* gauge.addCallback((result) => {
|
|
* result.observe(process.memoryUsage().heapUsed, { type: "heap" });
|
|
* });
|
|
* ```
|
|
*/
|
|
export function createGauge(
|
|
meter: Meter,
|
|
name: string,
|
|
description?: string
|
|
): ObservableGauge {
|
|
return meter.createObservableGauge(
|
|
name,
|
|
description !== undefined ? { description } : {}
|
|
);
|
|
}
|
|
|
|
/**
|
|
* Record the elapsed duration from a start timestamp to now.
|
|
*
|
|
* Computes `Date.now() - startMs` and records the result on `histogram`.
|
|
* This pattern avoids repeating the subtraction at every call site and
|
|
* centralises the choice of `Date.now()` as the wall-clock source.
|
|
*
|
|
* @param histogram - The histogram instrument to record on.
|
|
* @param startMs - Start timestamp in milliseconds (from `Date.now()`).
|
|
* @param attributes - Optional attributes to attach to the observation.
|
|
*
|
|
* @example
|
|
* ```ts
|
|
* const start = Date.now();
|
|
* await processOrder(order);
|
|
* recordDuration(latencyHistogram, start, { "order.type": order.type });
|
|
* ```
|
|
*/
|
|
export function recordDuration(
|
|
histogram: Histogram,
|
|
startMs: number,
|
|
attributes?: Attributes
|
|
): void {
|
|
histogram.record(Date.now() - startMs, attributes);
|
|
}
|