@devopsplaybook.io/otel-utils 1.6.0 → 1.7.0-beta.38.e32e141

package/README.md

@@ -119,12 +119,55 @@ const cpuGauge = meter.createObservableGauge(
 );
 ```
 
+**Instrument options**
+
+All four factories accept an optional options argument with the standard OpenTelemetry `MetricOptions` — `description`, `unit`, `valueType` and `advice` — forwarded to the underlying `Meter`. `createObservableGauge` also keeps accepting a description string as its third argument.
+
+These options matter most for histograms: the SDK default bucket boundaries (`[0, 5, 10, 25, 50, 75, 100, 250, 500, 750, 1000, 2500, 5000, 7500, 10000]`) are millisecond-oriented. A consumer that records seconds with the defaults puts every value below 5 s into the first bucket, which makes percentiles meaningless. The OpenTelemetry semantic conventions for `http.server.request.duration` therefore expect seconds and these boundaries:
+
+```typescript
+const httpDuration = meter.createHistogram("http.server.request.duration", {
+  description: "Duration of HTTP server requests",
+  unit: "s",
+  advice: {
+    explicitBucketBoundaries: [
+      0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10,
+    ],
+  },
+});
+
+httpDuration.record(Number(process.hrtime.bigint() - startTime) / 1e9);
+```
+
+The other factories accept the same options:
+
+```typescript
+meter.createCounter("requests.total", {
+  description: "Total requests",
+  unit: "1",
+});
+
+meter.createObservableGauge(
+  "cpu.usage",
+  (result) => result.observe(cpuPercent),
+  { description: "Current CPU usage", unit: "1" },
+);
+```
+
+**Metric naming**
+
+- Counters, up-down counters and histograms are exported as `${serviceName}.${key}`.
+- A histogram created with `{ unprefixed: true }` is exported exactly as `key`; only histograms have this opt-out.
+- Observable gauges are always exported exactly as `key` (never prefixed), including when an options object is passed.
+
+These defaults are unchanged: existing metric names keep working.
+
 **Methods:**
 
-- `createCounter(key)` — Creates a `Counter` with name `${serviceName}.${key}`.
-- `createUpDownCounter(key)` — Creates an `UpDownCounter`.
-- `createHistogram(key, options?)` — Creates a `Histogram` named `${serviceName}.${key}`; with `{ unprefixed: true }` the histogram is created exactly as `key`, without the service-name prefix.
-- `createObservableGauge(key, callback, description?)` — Creates an `ObservableGauge` with a callback. Description is optional.
+- `createCounter(key, options?)` — Creates a `Counter` named `${serviceName}.${key}`.
+- `createUpDownCounter(key, options?)` — Creates an `UpDownCounter` named `${serviceName}.${key}`.
+- `createHistogram(key, options?)` — Creates a `Histogram` named `${serviceName}.${key}`; with `{ unprefixed: true }` the histogram is created exactly as `key`, without the service-name prefix. Options also accept the OTel instrument options (`description`, `unit`, `valueType`, `advice`).
+- `createObservableGauge(key, callback, descriptionOrOptions?)` — Creates an `ObservableGauge` named `key` with a callback. The third argument is an optional description string or an options object (`description`, `unit`, `valueType`, `advice`).
 - `shutdown()` — Flushes buffered metrics and shuts the meter provider down. Idempotent.
 
 ## Provider lifecycle

package/dist/src/StandardMeter.d.ts

@@ -1,9 +1,12 @@
-import { Counter, Histogram, ObservableGauge, UpDownCounter } from "@opentelemetry/api";
+import { Counter, Histogram, type MetricOptions, ObservableGauge, UpDownCounter } from "@opentelemetry/api";
 import { ConfigOTelInterface } from "./models/ConfigOTelInterface";
 /**
  * Options accepted by {@link StandardMeter.createHistogram}.
+ * `description`, `unit`, `valueType` and `advice` are forwarded to the
+ * OpenTelemetry Meter; `advice.explicitBucketBoundaries` sets the histogram
+ * bucket boundaries.
  */
-export interface StandardMeterCreateHistogramOptions {
+export interface StandardMeterCreateHistogramOptions extends MetricOptions {
     /**
      * Create the histogram without the `${serviceName}.` prefix:
      * exported exactly as `key`.
@@ -19,10 +22,10 @@ export declare class StandardMeter {
     private shutdownPromise?;
     constructor(config: ConfigOTelInterface);
     shutdown(): Promise<void>;
-    createCounter(key: string): Counter;
-    createUpDownCounter(key: string): UpDownCounter;
+    createCounter(key: string, options?: MetricOptions): Counter;
+    createUpDownCounter(key: string, options?: MetricOptions): UpDownCounter;
     createHistogram(key: string, options?: StandardMeterCreateHistogramOptions): Histogram;
-    createObservableGauge(key: string, callback: (observableResult: any) => void, description?: string): ObservableGauge;
+    createObservableGauge(key: string, callback: (observableResult: any) => void, descriptionOrOptions?: string | MetricOptions): ObservableGauge;
     private registerGlobalProvider;
     private doShutdown;
 }

package/dist/src/StandardMeter.js

@@ -52,19 +52,22 @@ class StandardMeter {
         }
         return this.shutdownPromise;
     }
-    createCounter(key) {
-        return this.meter.createCounter(`${this.serviceName}.${key}`);
+    createCounter(key, options) {
+        return this.meter.createCounter(`${this.serviceName}.${key}`, options);
     }
-    createUpDownCounter(key) {
-        return this.meter.createUpDownCounter(`${this.serviceName}.${key}`);
+    createUpDownCounter(key, options) {
+        return this.meter.createUpDownCounter(`${this.serviceName}.${key}`, options);
     }
     createHistogram(key, options) {
-        return this.meter.createHistogram((options === null || options === void 0 ? void 0 : options.unprefixed) ? key : `${this.serviceName}.${key}`);
+        const { unprefixed, ...instrumentOptions } = options !== null && options !== void 0 ? options : {};
+        return this.meter.createHistogram(unprefixed ? key : `${this.serviceName}.${key}`, instrumentOptions);
     }
     createObservableGauge(key, 
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    callback, description) {
-        const observableGauge = this.meter.createObservableGauge(key, description ? { description } : undefined);
+    callback, descriptionOrOptions) {
+        const observableGauge = this.meter.createObservableGauge(key, typeof descriptionOrOptions === "string"
+            ? { description: descriptionOrOptions }
+            : descriptionOrOptions);
         observableGauge.addCallback(callback);
         return observableGauge;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devopsplaybook.io/otel-utils",
-  "version": "1.6.0",
+  "version": "1.7.0-beta.38.e32e141",
   "description": "Utility to simplify integration with Open Telemetry",
   "keywords": [
     "Open",

package/src/StandardMeter.spec.ts

@@ -1,8 +1,10 @@
 import { metrics } from "@opentelemetry/api";
 import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
 import {
+  DataPointType,
   type InMemoryMetricExporter,
   MeterProvider,
+  type MetricData,
 } from "@opentelemetry/sdk-metrics";
 import { ConfigOTelInterface } from "./models/ConfigOTelInterface";
 import { StandardMeter } from "./StandardMeter";
@@ -40,6 +42,21 @@ function metricNames(exporter: InMemoryMetricExporter): string[] {
     .map((metric) => metric.descriptor.name);
 }
 
+function metricData(
+  exporter: InMemoryMetricExporter,
+  name: string,
+): MetricData | undefined {
+  return exporter
+    .getMetrics()
+    .flatMap((resourceMetrics) => resourceMetrics.scopeMetrics)
+    .flatMap((scopeMetrics) => scopeMetrics.metrics)
+    .find((metric) => metric.descriptor.name === name);
+}
+
+const SEMCONV_HTTP_DURATION_BOUNDARIES = [
+  0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10,
+];
+
 function meterConfig(
   serviceId: string,
   url?: string,
@@ -124,7 +141,8 @@ describe("StandardMeter", () => {
 
     await meter.shutdown();
 
-    expect(metricNames(lastExporter())).toEqual(
+    const exporter = lastExporter();
+    expect(metricNames(exporter)).toEqual(
       expect.arrayContaining([
         "metric-service.requests.total",
         "metric-service.users.active",
@@ -132,6 +150,101 @@ describe("StandardMeter", () => {
         "cpu.usage",
       ]),
     );
+    expect(metricData(exporter, "cpu.usage")?.descriptor.description).toBe(
+      "Current CPU usage",
+    );
+    const counter = metricData(exporter, "metric-service.requests.total");
+    expect(counter?.descriptor.unit).toBe("");
+    expect(counter?.descriptor.description).toBe("");
+  });
+
+  it("records histogram values into the configured semconv seconds buckets", async () => {
+    const meter = makeMeter(
+      meterConfig("metric-service", "http://collector:4318/v1/metrics"),
+    );
+
+    const histogram = meter.createHistogram("http.server.request.duration", {
+      description: "Duration of HTTP server requests",
+      unit: "s",
+      advice: { explicitBucketBoundaries: SEMCONV_HTTP_DURATION_BOUNDARIES },
+    });
+    for (const seconds of [0.005, 0.042, 0.08, 0.3, 1.2, 4.5]) {
+      histogram.record(seconds);
+    }
+
+    await meter.shutdown();
+
+    const metric = metricData(
+      lastExporter(),
+      "metric-service.http.server.request.duration",
+    );
+    expect(metric).toBeDefined();
+    expect(metric?.descriptor.description).toBe(
+      "Duration of HTTP server requests",
+    );
+    expect(metric?.descriptor.unit).toBe("s");
+    if (!metric || metric.dataPointType !== DataPointType.HISTOGRAM) {
+      throw new Error("expected a histogram metric");
+    }
+    const [dataPoint] = metric.dataPoints;
+    expect(dataPoint.value.count).toBe(6);
+    expect(dataPoint.value.buckets.boundaries).toEqual(
+      SEMCONV_HTTP_DURATION_BOUNDARIES,
+    );
+    expect(dataPoint.value.buckets.counts).toEqual([
+      1, 0, 0, 1, 0, 1, 0, 1, 0, 0, 1, 1, 0, 0, 0,
+    ]);
+  });
+
+  it("forwards description and unit options for counters and up-down counters", async () => {
+    const meter = makeMeter(
+      meterConfig("metric-service", "http://collector:4318/v1/metrics"),
+    );
+
+    meter
+      .createCounter("requests.total", {
+        description: "Total requests",
+        unit: "1",
+      })
+      .add(1);
+    meter
+      .createUpDownCounter("users.active", {
+        description: "Active users",
+        unit: "{user}",
+      })
+      .add(1);
+
+    await meter.shutdown();
+
+    const exporter = lastExporter();
+    const counter = metricData(exporter, "metric-service.requests.total");
+    expect(counter?.descriptor.description).toBe("Total requests");
+    expect(counter?.descriptor.unit).toBe("1");
+    const upDownCounter = metricData(exporter, "metric-service.users.active");
+    expect(upDownCounter?.descriptor.description).toBe("Active users");
+    expect(upDownCounter?.descriptor.unit).toBe("{user}");
+  });
+
+  it("accepts an options object for observable gauges and keeps them unprefixed", async () => {
+    const meter = makeMeter(
+      meterConfig("metric-service", "http://collector:4318/v1/metrics"),
+    );
+
+    meter.createObservableGauge(
+      "cpu.usage",
+      (observableResult) => observableResult.observe(0.5),
+      { description: "Current CPU usage", unit: "1" },
+    );
+
+    await meter.shutdown();
+
+    const exporter = lastExporter();
+    const names = metricNames(exporter);
+    expect(names).toContain("cpu.usage");
+    expect(names).not.toContain("metric-service.cpu.usage");
+    const gauge = metricData(exporter, "cpu.usage");
+    expect(gauge?.descriptor.description).toBe("Current CPU usage");
+    expect(gauge?.descriptor.unit).toBe("1");
   });
 
   it("creates a histogram without the service-name prefix when the unprefixed option is set", async () => {

package/src/StandardMeter.ts

@@ -3,6 +3,7 @@ import {
   Histogram,
   Meter,
   metrics,
+  type MetricOptions,
   ObservableGauge,
   UpDownCounter,
 } from "@opentelemetry/api";
@@ -21,8 +22,11 @@ const ALREADY_REGISTERED_WARNING =
 
 /**
  * Options accepted by {@link StandardMeter.createHistogram}.
+ * `description`, `unit`, `valueType` and `advice` are forwarded to the
+ * OpenTelemetry Meter; `advice.explicitBucketBoundaries` sets the histogram
+ * bucket boundaries.
  */
-export interface StandardMeterCreateHistogramOptions {
+export interface StandardMeterCreateHistogramOptions extends MetricOptions {
   /**
    * Create the histogram without the `${serviceName}.` prefix:
    * exported exactly as `key`.
@@ -85,20 +89,25 @@ export class StandardMeter {
     return this.shutdownPromise;
   }
 
-  public createCounter(key: string): Counter {
-    return this.meter.createCounter(`${this.serviceName}.${key}`);
+  public createCounter(key: string, options?: MetricOptions): Counter {
+    return this.meter.createCounter(`${this.serviceName}.${key}`, options);
   }
 
-  public createUpDownCounter(key: string): UpDownCounter {
-    return this.meter.createUpDownCounter(`${this.serviceName}.${key}`);
+  public createUpDownCounter(
+    key: string,
+    options?: MetricOptions,
+  ): UpDownCounter {
+    return this.meter.createUpDownCounter(`${this.serviceName}.${key}`, options);
   }
 
   public createHistogram(
     key: string,
     options?: StandardMeterCreateHistogramOptions,
   ): Histogram {
+    const { unprefixed, ...instrumentOptions } = options ?? {};
     return this.meter.createHistogram(
-      options?.unprefixed ? key : `${this.serviceName}.${key}`,
+      unprefixed ? key : `${this.serviceName}.${key}`,
+      instrumentOptions,
     );
   }
 
@@ -106,11 +115,13 @@ export class StandardMeter {
     key: string,
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     callback: (observableResult: any) => void,
-    description?: string,
+    descriptionOrOptions?: string | MetricOptions,
   ): ObservableGauge {
     const observableGauge = this.meter.createObservableGauge(
       key,
-      description ? { description } : undefined,
+      typeof descriptionOrOptions === "string"
+        ? { description: descriptionOrOptions }
+        : descriptionOrOptions,
     );
     observableGauge.addCallback(callback);
     return observableGauge;