@peerkit/metrics 0.1.0-alpha.1

package/README.md

@@ -0,0 +1,52 @@
+# @peerkit/metrics
+
+App-side OpenTelemetry SDK bootstrap for peerkit. Configures a global OTel
+`MeterProvider` that exports metrics over OTLP/HTTP, and bridges OTel
+diagnostics into the `peerkit.metrics` logtape logger.
+
+This package is consumed **only by applications**. Library packages (e.g.
+`@peerkit/transport-libp2p-core`) depend on `@opentelemetry/api` directly
+and call `metrics.getMeter(...)` to obtain their meter, per the
+[OpenTelemetry library guidelines][otel-lib]. They do not depend on the
+SDK, and do not depend on this package.
+
+[otel-lib]: https://opentelemetry.io/docs/specs/otel/library-guidelines/#api-and-minimal-implementation
+
+## Install
+
+```bash
+npm install @peerkit/metrics
+```
+
+## Usage
+
+```ts
+import { initMetrics, shutdownMetrics } from "@peerkit/metrics";
+
+await initMetrics({
+  serviceName: "my-peerkit-app",
+  serviceVersion: "1.0.0",
+  otlpEndpoint: "http://localhost:4318/v1/metrics",
+});
+
+// On shutdown:
+await shutdownMetrics();
+```
+
+If `initMetrics` is never called, library instruments bind to OpenTelemetry's
+no-op meter — they still work but record nothing, at zero cost.
+
+## Configuration
+
+| Option                 | Default                                   | Description                               |
+| ---------------------- | ----------------------------------------- | ----------------------------------------- |
+| `serviceName`          | _required_                                | `service.name` resource attribute         |
+| `serviceVersion`       | _unset_                                   | `service.version` resource attribute      |
+| `otlpEndpoint`         | `http://localhost:4318/v1/metrics`        | OTLP/HTTP metrics endpoint                |
+| `exportIntervalMillis` | `60000`                                   | Periodic export interval                  |
+| `exportTimeoutMillis`  | `30000`                                   | Per-export timeout                        |
+| `headers`              | `{}`                                      | Extra OTLP request headers (auth, tenant) |
+| `resourceAttributes`   | `{}`                                      | Additional OTel resource attributes       |
+| `reader`               | OTLP/HTTP `PeriodicExportingMetricReader` | Override reader (mainly for tests)        |
+
+Exporter diagnostics are routed to the `peerkit.metrics` logtape logger.

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@peerkit/metrics",
+  "version": "0.1.0-alpha.1",
+  "description": "OpenTelemetry-based metric collection for peerkit",
+  "keywords": [
+    "peerkit",
+    "metrics",
+    "opentelemetry",
+    "otlp"
+  ],
+  "author": "Holochain Dev Team <devcore@holochain.org>",
+  "license": "CAL-1.0",
+  "bugs": {
+    "url": "https://github.com/holochain/peerkit/issues"
+  },
+  "homepage": "https://github.com/holochain/peerkit#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/holochain/peerkit.git"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "test": "vitest --run"
+  },
+  "dependencies": {
+    "@logtape/logtape": "^2.0.5",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.217.0",
+    "@opentelemetry/resources": "^2.7.0",
+    "@opentelemetry/sdk-metrics": "^2.7.0",
+    "@opentelemetry/semantic-conventions": "^1.40.0"
+  },
+  "devDependencies": {}
+}

package/src/config.ts

@@ -0,0 +1,110 @@
+import { DiagLogLevel, metrics } from "@opentelemetry/api";
+import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import {
+  MeterProvider,
+  PeriodicExportingMetricReader,
+  type MetricReader,
+} from "@opentelemetry/sdk-metrics";
+import {
+  ATTR_SERVICE_NAME,
+  ATTR_SERVICE_VERSION,
+} from "@opentelemetry/semantic-conventions";
+import { installDiagLogger, uninstallDiagLogger } from "./diag.js";
+
+export interface MetricsConfig {
+  /** `service.name` resource attribute. Required. */
+  serviceName: string;
+  /** Optional `service.version` resource attribute. */
+  serviceVersion?: string;
+  /** OTLP/HTTP metrics endpoint. Default: `http://localhost:4318/v1/metrics`. */
+  otlpEndpoint?: string;
+  /** Export interval. Default: 60 000 ms. */
+  exportIntervalMillis?: number;
+  /** Export timeout. Default: 30 000 ms. */
+  exportTimeoutMillis?: number;
+  /** Extra OTLP request headers (auth, tenant, …). */
+  headers?: Record<string, string>;
+  /** Additional resource attributes. */
+  resourceAttributes?: Record<string, string>;
+  /**
+   * Optional metric reader to use instead of the default OTLP/HTTP reader.
+   * Primarily for tests with `InMemoryMetricExporter`.
+   */
+  reader?: MetricReader;
+  /**
+   * Minimum level of OpenTelemetry SDK diagnostic messages forwarded to the
+   * `peerkit.metrics` logtape logger. Default: {@link DiagLogLevel.WARN}.
+   * Lower (e.g. {@link DiagLogLevel.DEBUG}) is helpful when investigating
+   * why metrics are not being exported.
+   */
+  diagLogLevel?: DiagLogLevel;
+}
+
+let activeProvider: MeterProvider | undefined;
+
+/**
+ * Initialise the global metrics pipeline.
+ *
+ * Builds a {@link MeterProvider} that exports to the configured OTLP endpoint
+ * (or to a caller-supplied {@link MetricReader}) and registers it as the
+ * global meter provider for `@opentelemetry/api`.
+ *
+ * Must be called at most once between {@link shutdownMetrics} calls; a second
+ * call without prior shutdown rejects.
+ */
+export async function initMetrics(cfg: MetricsConfig): Promise<void> {
+  if (activeProvider) {
+    throw new Error(
+      "Metrics already initialised. Call shutdownMetrics() before re-initialising.",
+    );
+  }
+
+  installDiagLogger(cfg.diagLogLevel);
+
+  const resourceAttrs: Record<string, string> = {
+    [ATTR_SERVICE_NAME]: cfg.serviceName,
+    ...(cfg.serviceVersion && { [ATTR_SERVICE_VERSION]: cfg.serviceVersion }),
+    ...(cfg.resourceAttributes ?? {}),
+  };
+  const resource = resourceFromAttributes(resourceAttrs);
+
+  const reader =
+    cfg.reader ??
+    new PeriodicExportingMetricReader({
+      exporter: new OTLPMetricExporter({
+        url: cfg.otlpEndpoint ?? "http://localhost:4318/v1/metrics",
+        headers: cfg.headers,
+        timeoutMillis: cfg.exportTimeoutMillis ?? 30_000,
+      }),
+      exportIntervalMillis: cfg.exportIntervalMillis ?? 60_000,
+    });
+
+  const provider = new MeterProvider({ resource, readers: [reader] });
+  metrics.setGlobalMeterProvider(provider);
+  activeProvider = provider;
+}
+
+/**
+ * Flush pending metrics, shut the provider down, and restore the OpenTelemetry
+ * default no-op meter provider.
+ *
+ * Safe to call when metrics have not been initialised.
+ */
+export async function shutdownMetrics(): Promise<void> {
+  if (!activeProvider) {
+    return;
+  }
+  const provider = activeProvider;
+  activeProvider = undefined;
+  try {
+    await provider.forceFlush();
+  } finally {
+    try {
+      await provider.shutdown();
+    } finally {
+      metrics.disable();
+      uninstallDiagLogger();
+    }
+  }
+}

package/src/diag.ts

@@ -0,0 +1,35 @@
+import { getLogger } from "@logtape/logtape";
+import { diag, DiagLogLevel, type DiagLogger } from "@opentelemetry/api";
+
+const logger = getLogger(["peerkit", "metrics"]);
+
+/**
+ * Bridge OpenTelemetry's `diag` channel to the peerkit logtape logger,
+ * so exporter errors and SDK diagnostics surface through the standard
+ * peerkit logging pipeline.
+ *
+ * `level` filters messages on the OTel side before they reach logtape:
+ * - `ERROR` — only outright failures.
+ * - `WARN` (default) — failures + retries / dropped data.
+ * - `INFO` / `DEBUG` / `VERBOSE` — increasingly chatty; useful when
+ *   diagnosing why metrics are not exporting.
+ */
+export function installDiagLogger(
+  level: DiagLogLevel = DiagLogLevel.WARN,
+): void {
+  const diagLogger: DiagLogger = {
+    error: (message, ...args) => logger.error(message, { args }),
+    warn: (message, ...args) => logger.warn(message, { args }),
+    info: (message, ...args) => logger.info(message, { args }),
+    debug: (message, ...args) => logger.debug(message, { args }),
+    verbose: (message, ...args) => logger.debug(message, { args }),
+  };
+  diag.setLogger(diagLogger, level);
+}
+
+/**
+ * Restore the OpenTelemetry default diag logger.
+ */
+export function uninstallDiagLogger(): void {
+  diag.disable();
+}

package/src/index.ts

@@ -0,0 +1 @@
+export * from "./config.js";

package/tests/config.test.ts

@@ -0,0 +1,64 @@
+import {
+  AggregationTemporality,
+  InMemoryMetricExporter,
+  PeriodicExportingMetricReader,
+} from "@opentelemetry/sdk-metrics";
+import { metrics } from "@opentelemetry/api";
+import { afterEach, describe, expect, test } from "vitest";
+import { initMetrics, shutdownMetrics } from "../src/index.js";
+
+const makeReader = () => {
+  const exporter = new InMemoryMetricExporter(
+    AggregationTemporality.CUMULATIVE,
+  );
+  const reader = new PeriodicExportingMetricReader({
+    exporter,
+    exportIntervalMillis: 60_000,
+  });
+  return { exporter, reader };
+};
+
+describe("initMetrics", () => {
+  afterEach(async () => {
+    await shutdownMetrics();
+  });
+
+  test("records a counter that the configured reader observes", async () => {
+    const { exporter, reader } = makeReader();
+    await initMetrics({ serviceName: "test-service", reader });
+
+    const counter = metrics.getMeter("test").createCounter("test.counter");
+    counter.add(7, { kind: "unit" });
+
+    await reader.forceFlush();
+    const collected = exporter.getMetrics();
+    const found = collected
+      .flatMap((rm) => rm.scopeMetrics)
+      .flatMap((sm) => sm.metrics)
+      .find((m) => m.descriptor.name === "test.counter");
+    expect(found).toBeDefined();
+    expect(found?.dataPoints[0]?.value).toBe(7);
+  });
+
+  test("calling initMetrics twice without shutdown rejects", async () => {
+    const { reader: r1 } = makeReader();
+    const { reader: r2 } = makeReader();
+    await initMetrics({ serviceName: "svc", reader: r1 });
+    await expect(
+      initMetrics({ serviceName: "svc", reader: r2 }),
+    ).rejects.toThrow(/already initialised/i);
+  });
+
+  test("shutdownMetrics reverts the global provider to the OTel no-op", async () => {
+    const { reader } = makeReader();
+    await initMetrics({ serviceName: "svc", reader });
+    const beforeProvider = metrics.getMeterProvider();
+    await shutdownMetrics();
+    const afterProvider = metrics.getMeterProvider();
+    expect(afterProvider).not.toBe(beforeProvider);
+  });
+
+  test("shutdownMetrics is safe to call when not initialised", async () => {
+    await expect(shutdownMetrics()).resolves.toBeUndefined();
+  });
+});

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "composite": true,
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"],
+  "references": []
+}