@3sixty/telemetry-connector-opentelemetry 0.0.0-stage → 0.20.0-next.0

package/dist/types/models/IOpenTelemetryTelemetryConnectorConfig.d.ts

@@ -0,0 +1,24 @@
+import type { IOpenTelemetryReaderConfig } from "./IOpenTelemetryReaderConfig.js";
+/**
+ * The options for the OpenTelemetry telemetry connector constructor.
+ */
+export interface IOpenTelemetryTelemetryConnectorConfig {
+    /**
+     * The name of the OpenTelemetry meter used to create instruments.
+     * @default twin-telemetry
+     */
+    meterName?: string;
+    /**
+     * The version reported by the OpenTelemetry meter.
+     * @default 1.0.0
+     */
+    meterVersion?: string;
+    /**
+     * Named metric-reader configurations keyed by an arbitrary id.
+     * Each entry's `type` field determines which exporter the connector instantiates
+     * in start(). Omit or pass an empty object for a no-op provider (useful for tests).
+     */
+    readers?: {
+        [id: string]: IOpenTelemetryReaderConfig;
+    };
+}

package/dist/types/models/IOpenTelemetryTelemetryConnectorConstructorOptions.d.ts

@@ -0,0 +1,10 @@
+import type { IOpenTelemetryTelemetryConnectorConfig } from "./IOpenTelemetryTelemetryConnectorConfig.js";
+/**
+ * The options for the OpenTelemetry telemetry connector constructor.
+ */
+export interface IOpenTelemetryTelemetryConnectorConstructorOptions {
+    /**
+     * The config for the telemetry connector.
+     */
+    config?: IOpenTelemetryTelemetryConnectorConfig;
+}

package/dist/types/models/openTelemetryReaderTypes.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The types of readers.
+ */
+export declare const OpenTelemetryReaderTypes: {
+    /**
+     * Prometheus.
+     */
+    readonly Prometheus: "prometheus";
+    /**
+     * OTLP HTTP push exporter.
+     */
+    readonly OtlpHttp: "otlp-http";
+};
+/**
+ * The types of readers.
+ */
+export type OpenTelemetryReaderTypes = (typeof OpenTelemetryReaderTypes)[keyof typeof OpenTelemetryReaderTypes];

package/dist/types/openTelemetryTelemetryConnector.d.ts

@@ -0,0 +1,80 @@
+import { type ITelemetryConnector, type ITelemetryMetric, type ITelemetryMetricValueEntry, MetricCounterOperation } from "@3sixty/telemetry-models";
+import type { IOpenTelemetryTelemetryConnectorConstructorOptions } from "./models/IOpenTelemetryTelemetryConnectorConstructorOptions.js";
+/**
+ * Class for performing telemetry operations using OpenTelemetry instruments.
+ * Metric definitions are held in memory. Persistence and querying are not supported;
+ * use a multi-connector with an EntityStorageTelemetryConnector for those capabilities.
+ */
+export declare class OpenTelemetryTelemetryConnector implements ITelemetryConnector {
+    /**
+     * The namespace supported by the telemetry connector.
+     */
+    static readonly NAMESPACE: string;
+    /**
+     * Runtime name for the class.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * Create a new instance of OpenTelemetryTelemetryConnector.
+     * @param options The options for the connector.
+     * @throws GuardError When a reader config specifies an unsupported type.
+     */
+    constructor(options?: IOpenTelemetryTelemetryConnectorConstructorOptions);
+    /**
+     * Returns the class name of the component.
+     * @returns The class name of the component.
+     */
+    className(): string;
+    /**
+     * Enable OTEL forwarding. Subsequent calls to addMetricValue will create
+     * per-tenant/node MeterProviders on demand.
+     * @param nodeLoggingComponentType The node logging component type.
+     * @returns A promise that resolves when OTEL forwarding is enabled.
+     */
+    start(nodeLoggingComponentType?: string): Promise<void>;
+    /**
+     * Shut down all cached MeterProviders and disable OTEL forwarding.
+     * @param nodeLoggingComponentType The node logging component type.
+     * @returns A promise that resolves when all MeterProviders have shut down.
+     */
+    stop(nodeLoggingComponentType?: string): Promise<void>;
+    /**
+     * Register one or more metric definitions. If the connector is already started,
+     * the OTEL instrument is registered immediately for the current context.
+     * @param metric The metric details, or the details of several metrics.
+     * @returns A promise that resolves when the metrics have been registered.
+     */
+    createMetric(metric: ITelemetryMetric | ITelemetryMetric[]): Promise<void>;
+    /**
+     * Update the in-memory metadata for a registered metric.
+     * OpenTelemetry instrument descriptors are immutable once created; only the
+     * cached label, description and unit are updated.
+     * @param metric The metric details (type cannot be changed).
+     * @returns A promise that resolves when the metadata has been updated.
+     */
+    updateMetric(metric: Omit<ITelemetryMetric, "type">): Promise<void>;
+    /**
+     * Record a metric value and forward it to the appropriate OTEL instrument.
+     * The current tenant and node IDs are read from `ContextIdStore` and used to
+     * select (or create) the matching per-tenant/node `MeterProvider`.
+     * @param id The id of the metric.
+     * @param value The value for the operation.
+     * @param customData Optional custom data forwarded as OTEL attributes.
+     * @returns A generated 32-character hex id for the recorded value.
+     */
+    addMetricValue(id: string, value: MetricCounterOperation | number, customData?: {
+        [key: string]: unknown;
+    }): Promise<string>;
+    /**
+     * Add multiple metric values.
+     * @param values The metric values to add.
+     * @returns The created metric value ids, in the order the values were supplied.
+     */
+    addMetricValues(values: ITelemetryMetricValueEntry[]): Promise<string[]>;
+    /**
+     * Remove a metric from the in-memory registry and from all cached provider instrument maps.
+     * @param id The id of the metric.
+     * @returns A promise that resolves when the metric has been removed.
+     */
+    removeMetric(id: string): Promise<void>;
+}

package/docs/examples.md

@@ -0,0 +1,172 @@
+# Telemetry Connector OpenTelemetry Examples
+
+These examples show how to wire the connector to an OpenTelemetry SDK provider, record metrics, and connect to a Grafana/Prometheus stack.
+
+## Prometheus Metric Naming
+
+When using the Prometheus exporter, the OTEL SDK appends the `unit` field to the metric
+name following the OpenMetrics convention. If you set `unit: "requests"` on a counter
+named `api_requests`, Prometheus will expose it as `api_requests_requests_total` — which
+may not be what you want. Omit the `unit` field (or leave it empty) to get clean names:
+
+- `api_requests` (Counter, no unit) → `api_requests_total`
+- `active_connections` (UpDownCounter, no unit) → `active_connections`
+- `cpu_temperature` (Gauge, no unit) → `cpu_temperature`
+
+> This only applies to the Prometheus exporter. OTLP exporters (e.g. Grafana Agent,
+> Tempo, OTEL Collector) preserve the unit as metadata and are not affected.
+
+## Basic Setup with Prometheus Exporter
+
+Install the optional Prometheus exporter peer dependency alongside the connector:
+
+```shell
+npm install @opentelemetry/exporter-prometheus
+```
+
+Pass a `readers` config map to the connector constructor. The connector instantiates the
+exporter internally when `start()` is called — no manual `MeterProvider` wiring is needed.
+
+```typescript
+import { EntityStorageConnectorFactory } from '@3sixty/entity-storage-models';
+import { MemoryEntityStorageConnector } from '@3sixty/entity-storage-connector-memory';
+import { TelemetryConnectorFactory } from '@3sixty/telemetry-models';
+import {
+  OpenTelemetryTelemetryConnector,
+  initSchema,
+  type TelemetryMetric,
+  type TelemetryMetricValue
+} from '@3sixty/telemetry-connector-opentelemetry';
+
+// Register entity storage so the connector can persist metric definitions and history.
+initSchema();
+EntityStorageConnectorFactory.register(
+  'telemetry-metric',
+  () => new MemoryEntityStorageConnector<TelemetryMetric>({ entitySchema: 'TelemetryMetric' })
+);
+EntityStorageConnectorFactory.register(
+  'telemetry-metric-value',
+  () =>
+    new MemoryEntityStorageConnector<TelemetryMetricValue>({ entitySchema: 'TelemetryMetricValue' })
+);
+
+const connector = new OpenTelemetryTelemetryConnector({
+  config: {
+    meterName: 'my-service',
+    meterVersion: '1.0.0',
+    readers: {
+      prometheus: { type: 'prometheus', port: 9464 }
+    }
+  }
+});
+
+await connector.start();
+
+TelemetryConnectorFactory.register('telemetry', () => connector);
+```
+
+## Creating and Recording Metrics
+
+```typescript
+import { MetricType } from '@3sixty/telemetry-models';
+import { OpenTelemetryTelemetryConnector } from '@3sixty/telemetry-connector-opentelemetry';
+
+const connector = new OpenTelemetryTelemetryConnector();
+
+console.log(connector.className()); // OpenTelemetryTelemetryConnector
+
+await connector.createMetric({
+  id: 'api-requests',
+  label: 'API Requests',
+  description: 'Total number of API requests received',
+  unit: 'requests',
+  type: MetricType.Counter
+});
+
+await connector.createMetric({
+  id: 'active-connections',
+  label: 'Active Connections',
+  description: 'Number of currently active WebSocket connections',
+  unit: 'connections',
+  type: MetricType.IncDecCounter
+});
+
+await connector.createMetric({
+  id: 'cpu-temperature',
+  label: 'CPU Temperature',
+  description: 'Current CPU temperature reading',
+  unit: 'celsius',
+  type: MetricType.Gauge
+});
+
+// Counter: increment only
+await connector.addMetricValue('api-requests', 'inc');
+await connector.addMetricValue('api-requests', 10, { route: '/api/health', statusCode: 200 });
+
+// IncDecCounter: increment and decrement
+await connector.addMetricValue('active-connections', 'inc');
+await connector.addMetricValue('active-connections', 'dec');
+
+// Gauge: absolute value
+await connector.addMetricValue('cpu-temperature', 72.4);
+await connector.addMetricValue('cpu-temperature', 68.1, { node: 'edge-1' });
+
+const latest = await connector.getMetric('cpu-temperature');
+console.log(latest.value.value); // 68.1
+```
+
+## Querying the Local Registry
+
+The connector keeps an in-memory mirror of all recorded values so you can read back metrics without a separate query backend.
+
+```typescript
+import { MetricType } from '@3sixty/telemetry-models';
+import { OpenTelemetryTelemetryConnector } from '@3sixty/telemetry-connector-opentelemetry';
+
+const connector = new OpenTelemetryTelemetryConnector();
+
+// List all metrics of a given type
+const counters = await connector.query(MetricType.Counter, undefined, 25);
+console.log(counters.entities.length);
+
+// Paginate through value history
+const page1 = await connector.queryValues(
+  'api-requests',
+  Date.now() - 3_600_000,
+  Date.now(),
+  undefined,
+  20
+);
+console.log(page1.entities.length);
+
+if (page1.cursor) {
+  const page2 = await connector.queryValues('api-requests', undefined, undefined, page1.cursor, 20);
+  console.log(page2.entities.length);
+}
+```
+
+## Updating and Removing Metrics
+
+```typescript
+import { OpenTelemetryTelemetryConnector } from '@3sixty/telemetry-connector-opentelemetry';
+
+const connector = new OpenTelemetryTelemetryConnector();
+
+await connector.updateMetric({
+  id: 'api-requests',
+  label: 'API Requests Total',
+  description: 'Cumulative count of all API requests',
+  unit: 'requests'
+});
+
+await connector.removeMetric('api-requests');
+
+const result = await connector.query(undefined, undefined, 10);
+console.log(result.entities.length); // 0
+```
+
+## Connecting to Grafana via OTLP
+
+> OTLP exporter support is planned for a future release. The `readers` config map currently
+> supports `type: "prometheus"` only. Additional reader types (OTLP HTTP, OTLP gRPC, etc.)
+> will be added as further discriminated-union members of `IOpenTelemetryReaderConfig`.

package/docs/reference/classes/OpenTelemetryTelemetryConnector.md

@@ -0,0 +1,265 @@
+# Class: OpenTelemetryTelemetryConnector
+
+Class for performing telemetry operations using OpenTelemetry instruments.
+Metric definitions are held in memory. Persistence and querying are not supported;
+use a multi-connector with an EntityStorageTelemetryConnector for those capabilities.
+
+## Implements
+
+- `ITelemetryConnector`
+
+## Constructors
+
+### Constructor
+
+> **new OpenTelemetryTelemetryConnector**(`options?`): `OpenTelemetryTelemetryConnector`
+
+Create a new instance of OpenTelemetryTelemetryConnector.
+
+#### Parameters
+
+##### options?
+
+[`IOpenTelemetryTelemetryConnectorConstructorOptions`](../interfaces/IOpenTelemetryTelemetryConnectorConstructorOptions.md)
+
+The options for the connector.
+
+#### Returns
+
+`OpenTelemetryTelemetryConnector`
+
+#### Throws
+
+GuardError When a reader config specifies an unsupported type.
+
+## Properties
+
+### NAMESPACE {#namespace}
+
+> `readonly` `static` **NAMESPACE**: `string` = `"open-telemetry"`
+
+The namespace supported by the telemetry connector.
+
+***
+
+### CLASS\_NAME {#class_name}
+
+> `readonly` `static` **CLASS\_NAME**: `string`
+
+Runtime name for the class.
+
+## Methods
+
+### className() {#classname}
+
+> **className**(): `string`
+
+Returns the class name of the component.
+
+#### Returns
+
+`string`
+
+The class name of the component.
+
+#### Implementation of
+
+`ITelemetryConnector.className`
+
+***
+
+### start() {#start}
+
+> **start**(`nodeLoggingComponentType?`): `Promise`\<`void`\>
+
+Enable OTEL forwarding. Subsequent calls to addMetricValue will create
+per-tenant/node MeterProviders on demand.
+
+#### Parameters
+
+##### nodeLoggingComponentType?
+
+`string`
+
+The node logging component type.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when OTEL forwarding is enabled.
+
+#### Implementation of
+
+`ITelemetryConnector.start`
+
+***
+
+### stop() {#stop}
+
+> **stop**(`nodeLoggingComponentType?`): `Promise`\<`void`\>
+
+Shut down all cached MeterProviders and disable OTEL forwarding.
+
+#### Parameters
+
+##### nodeLoggingComponentType?
+
+`string`
+
+The node logging component type.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when all MeterProviders have shut down.
+
+#### Implementation of
+
+`ITelemetryConnector.stop`
+
+***
+
+### createMetric() {#createmetric}
+
+> **createMetric**(`metric`): `Promise`\<`void`\>
+
+Register one or more metric definitions. If the connector is already started,
+the OTEL instrument is registered immediately for the current context.
+
+#### Parameters
+
+##### metric
+
+`ITelemetryMetric` \| `ITelemetryMetric`[]
+
+The metric details, or the details of several metrics.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the metrics have been registered.
+
+#### Implementation of
+
+`ITelemetryConnector.createMetric`
+
+***
+
+### updateMetric() {#updatemetric}
+
+> **updateMetric**(`metric`): `Promise`\<`void`\>
+
+Update the in-memory metadata for a registered metric.
+OpenTelemetry instrument descriptors are immutable once created; only the
+cached label, description and unit are updated.
+
+#### Parameters
+
+##### metric
+
+`Omit`\<`ITelemetryMetric`, `"type"`\>
+
+The metric details (type cannot be changed).
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the metadata has been updated.
+
+#### Implementation of
+
+`ITelemetryConnector.updateMetric`
+
+***
+
+### addMetricValue() {#addmetricvalue}
+
+> **addMetricValue**(`id`, `value`, `customData?`): `Promise`\<`string`\>
+
+Record a metric value and forward it to the appropriate OTEL instrument.
+The current tenant and node IDs are read from `ContextIdStore` and used to
+select (or create) the matching per-tenant/node `MeterProvider`.
+
+#### Parameters
+
+##### id
+
+`string`
+
+The id of the metric.
+
+##### value
+
+`number` \| `MetricCounterOperation`
+
+The value for the operation.
+
+##### customData?
+
+Optional custom data forwarded as OTEL attributes.
+
+#### Returns
+
+`Promise`\<`string`\>
+
+A generated 32-character hex id for the recorded value.
+
+#### Implementation of
+
+`ITelemetryConnector.addMetricValue`
+
+***
+
+### addMetricValues() {#addmetricvalues}
+
+> **addMetricValues**(`values`): `Promise`\<`string`[]\>
+
+Add multiple metric values.
+
+#### Parameters
+
+##### values
+
+`ITelemetryMetricValueEntry`[]
+
+The metric values to add.
+
+#### Returns
+
+`Promise`\<`string`[]\>
+
+The created metric value ids, in the order the values were supplied.
+
+#### Implementation of
+
+`ITelemetryConnector.addMetricValues`
+
+***
+
+### removeMetric() {#removemetric}
+
+> **removeMetric**(`id`): `Promise`\<`void`\>
+
+Remove a metric from the in-memory registry and from all cached provider instrument maps.
+
+#### Parameters
+
+##### id
+
+`string`
+
+The id of the metric.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the metric has been removed.
+
+#### Implementation of
+
+`ITelemetryConnector.removeMetric`

package/docs/reference/index.md

@@ -0,0 +1,21 @@
+# @3sixty/telemetry-connector-opentelemetry
+
+## Classes
+
+- [OpenTelemetryTelemetryConnector](classes/OpenTelemetryTelemetryConnector.md)
+
+## Interfaces
+
+- [IOpenTelemetryOtlpHttpReaderConfig](interfaces/IOpenTelemetryOtlpHttpReaderConfig.md)
+- [IOpenTelemetryPrometheusReaderConfig](interfaces/IOpenTelemetryPrometheusReaderConfig.md)
+- [IOpenTelemetryTelemetryConnectorConfig](interfaces/IOpenTelemetryTelemetryConnectorConfig.md)
+- [IOpenTelemetryTelemetryConnectorConstructorOptions](interfaces/IOpenTelemetryTelemetryConnectorConstructorOptions.md)
+
+## Type Aliases
+
+- [IOpenTelemetryReaderConfig](type-aliases/IOpenTelemetryReaderConfig.md)
+- [OpenTelemetryReaderTypes](type-aliases/OpenTelemetryReaderTypes.md)
+
+## Variables
+
+- [OpenTelemetryReaderTypes](variables/OpenTelemetryReaderTypes.md)

package/docs/reference/interfaces/IOpenTelemetryOtlpHttpReaderConfig.md

@@ -0,0 +1,52 @@
+# Interface: IOpenTelemetryOtlpHttpReaderConfig
+
+Configuration for an OTLP HTTP push exporter reader.
+The connector instantiates an OTLPMetricExporter wrapped in a PeriodicExportingMetricReader.
+
+## Properties
+
+### type {#type}
+
+> **type**: `"otlp-http"`
+
+Type.
+
+***
+
+### url? {#url}
+
+> `optional` **url?**: `string`
+
+The OTLP HTTP endpoint URL to push metrics to.
+
+#### Default
+
+```ts
+http://localhost:4318/v1/metrics
+```
+
+***
+
+### exportIntervalMs? {#exportintervalms}
+
+> `optional` **exportIntervalMs?**: `number`
+
+How often metrics are exported, in milliseconds.
+
+#### Default
+
+```ts
+60000
+```
+
+***
+
+### headers? {#headers}
+
+> `optional` **headers?**: `object`
+
+Optional HTTP headers included in every export request.
+
+#### Index Signature
+
+\[`key`: `string`\]: `string`

package/docs/reference/interfaces/IOpenTelemetryPrometheusReaderConfig.md

@@ -0,0 +1,63 @@
+# Interface: IOpenTelemetryPrometheusReaderConfig
+
+Configuration for a Prometheus scrape-endpoint reader.
+The connector instantiates a PrometheusExporter from these options in start().
+
+## Properties
+
+### type {#type}
+
+> **type**: `"prometheus"`
+
+Type.
+
+***
+
+### port? {#port}
+
+> `optional` **port?**: `number`
+
+TCP port the Prometheus HTTP server listens on.
+
+#### Default
+
+```ts
+9464
+```
+
+***
+
+### endpoint? {#endpoint}
+
+> `optional` **endpoint?**: `string`
+
+HTTP path that Prometheus scrapes.
+
+#### Default
+
+```ts
+/metrics
+```
+
+***
+
+### startServer? {#startserver}
+
+> `optional` **startServer?**: `boolean`
+
+Whether to start the built-in HTTP server automatically.
+Set to false if you manage the server externally.
+
+#### Default
+
+```ts
+true
+```
+
+***
+
+### prefix? {#prefix}
+
+> `optional` **prefix?**: `string`
+
+Optional string prepended to every exported metric name.