@twin.org/telemetry-connector-opentelemetry 0.0.3-next.10

package/dist/types/openTelemetryTelemetryConnector.d.ts

@@ -0,0 +1,122 @@
+import { type ITelemetryConnector, type ITelemetryMetric, type ITelemetryMetricValue, MetricCounterOperation, MetricType } from "@twin.org/telemetry-models";
+import type { IOpenTelemetryTelemetryConnectorConstructorOptions } from "./models/IOpenTelemetryTelemetryConnectorConstructorOptions.js";
+/**
+ * Class for performing telemetry operations using OpenTelemetry instruments.
+ * Metric definitions and value history are persisted via an internal
+ * EntityStorageTelemetryConnector instance created at construction time.
+ * Call `start()` to initialise the MeterProvider and exporters; metrics can be
+ * created and queried before start() — OTEL forwarding is simply skipped until
+ * the MeterProvider is running.
+ */
+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.
+     * Eagerly constructs the inner EntityStorageTelemetryConnector — if the required
+     * entity storage types are not registered this constructor will throw (fail fast).
+     * @param options The options for the connector.
+     */
+    constructor(options?: IOpenTelemetryTelemetryConnectorConstructorOptions);
+    /**
+     * Returns the class name of the component.
+     * @returns The class name of the component.
+     */
+    className(): string;
+    /**
+     * Initialise the MeterProvider and configured exporters.
+     * @param nodeLoggingComponentType The node logging component type.
+     * @returns Nothing.
+     */
+    start(nodeLoggingComponentType?: string): Promise<void>;
+    /**
+     * Shut down the MeterProvider and release resources.
+     * Calling stop() on a connector that has not been started is a no-op.
+     * @param nodeLoggingComponentType The node logging component type.
+     * @returns Nothing.
+     */
+    stop(nodeLoggingComponentType?: string): Promise<void>;
+    /**
+     * Create a new metric.
+     * The definition is always persisted via the inner entity-storage connector.
+     * If the MeterProvider is running the corresponding OTEL instrument is also registered.
+     * @param metric The metric details.
+     * @returns Nothing.
+     */
+    createMetric(metric: ITelemetryMetric): Promise<void>;
+    /**
+     * Get the metric details and its most recent value.
+     * @param id The metric id.
+     * @returns The metric details and its most recent value.
+     */
+    getMetric(id: string): Promise<{
+        metric: ITelemetryMetric;
+        value: ITelemetryMetricValue;
+    }>;
+    /**
+     * Update the metric metadata.
+     * Note: OpenTelemetry instrument descriptors are immutable once created.
+     * This method updates the persisted metadata mirror; the description/unit changes
+     * are NOT propagated to the registered MeterProvider and will not appear at the
+     * OTEL backend (Prometheus, OTLP, etc.).
+     * @param metric The metric details (type cannot be changed).
+     * @returns Nothing.
+     */
+    updateMetric(metric: Omit<ITelemetryMetric, "type">): Promise<void>;
+    /**
+     * Record a metric value.
+     * Entity storage always receives the value first and performs all validation.
+     * If the MeterProvider is running the measurement is also forwarded to the OTEL instrument.
+     * Counter accepts positive integers or "inc".
+     * UpDownCounter accepts integers (positive or negative) or "inc"/"dec".
+     * Gauge accepts any number.
+     * @param id The id of the metric.
+     * @param value The value for the operation.
+     * @param customData Optional custom data forwarded as OTEL attributes.
+     * @returns The id of the new metric value entry.
+     */
+    addMetricValue(id: string, value: MetricCounterOperation | number, customData?: {
+        [key: string]: unknown;
+    }): Promise<string>;
+    /**
+     * Remove a metric and its persisted value history.
+     * Note: OpenTelemetry exposes no API to deregister an instrument from a Meter,
+     * so the underlying Counter/UpDownCounter/Gauge remains resident for the lifetime
+     * of the process. Re-creating a metric with the same id but a different MetricType
+     * is therefore not safe.
+     * @param id The id of the metric.
+     * @returns Nothing.
+     */
+    removeMetric(id: string): Promise<void>;
+    /**
+     * Query the registered metrics, optionally filtered by type.
+     * @param type The type of the metric.
+     * @param cursor The cursor to request the next page.
+     * @param limit Limit the number of entities to return.
+     * @returns The matching metrics and an optional cursor for the next page.
+     */
+    query(type?: MetricType, cursor?: string, limit?: number): Promise<{
+        entities: ITelemetryMetric[];
+        cursor?: string;
+    }>;
+    /**
+     * Query the recorded values for a metric, ordered by most recent first.
+     * @param id The id of the metric.
+     * @param timeStart The inclusive start time (epoch ms).
+     * @param timeEnd The inclusive end time (epoch ms).
+     * @param cursor The cursor returned by the previous call.
+     * @param limit Limit the number of values to return.
+     * @returns The metric details, matching values, and an optional cursor for the next page.
+     */
+    queryValues(id: string, timeStart?: number, timeEnd?: number, cursor?: string, limit?: number): Promise<{
+        metric: ITelemetryMetric;
+        entities: ITelemetryMetricValue[];
+        cursor?: string;
+    }>;
+}

package/docs/changelog.md

@@ -0,0 +1,100 @@
+# Changelog
+
+## [0.0.3-next.10](https://github.com/iotaledger/twin-telemetry/compare/telemetry-connector-opentelemetry-v0.0.3-next.9...telemetry-connector-opentelemetry-v0.0.3-next.10) (2026-05-20)
+
+
+### Miscellaneous Chores
+
+* **telemetry-connector-opentelemetry:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/telemetry-connector-entity-storage bumped from 0.0.3-next.9 to 0.0.3-next.10
+    * @twin.org/telemetry-models bumped from 0.0.3-next.9 to 0.0.3-next.10
+
+## [0.0.3-next.9](https://github.com/iotaledger/twin-telemetry/compare/telemetry-connector-opentelemetry-v0.0.3-next.8...telemetry-connector-opentelemetry-v0.0.3-next.9) (2026-05-20)
+
+
+### Features
+
+* add helper and command types ([7166013](https://github.com/iotaledger/twin-telemetry/commit/7166013f8a0693a1d92101cb600c37a1aba66417))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/telemetry-connector-entity-storage bumped from 0.0.3-next.8 to 0.0.3-next.9
+    * @twin.org/telemetry-models bumped from 0.0.3-next.8 to 0.0.3-next.9
+
+## [0.0.3-next.8](https://github.com/iotaledger/twin-telemetry/compare/telemetry-connector-opentelemetry-v0.0.3-next.7...telemetry-connector-opentelemetry-v0.0.3-next.8) (2026-05-19)
+
+
+### Miscellaneous Chores
+
+* **telemetry-connector-opentelemetry:** Synchronize repo versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/telemetry-connector-entity-storage bumped from 0.0.3-next.7 to 0.0.3-next.8
+    * @twin.org/telemetry-models bumped from 0.0.3-next.7 to 0.0.3-next.8
+
+## [0.0.3-next.7](https://github.com/iotaledger/twin-telemetry/compare/telemetry-connector-opentelemetry-v0.0.3-next.6...telemetry-connector-opentelemetry-v0.0.3-next.7) (2026-05-19)
+
+
+### Features
+
+* add metrics producer infrastructure ([#30](https://github.com/iotaledger/twin-telemetry/issues/30)) ([8990b99](https://github.com/iotaledger/twin-telemetry/commit/8990b990d22f331d44562c2781c9b6ddf846db88))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/telemetry-connector-entity-storage bumped from 0.0.3-next.6 to 0.0.3-next.7
+    * @twin.org/telemetry-models bumped from 0.0.3-next.6 to 0.0.3-next.7
+
+## [0.0.3-next.6](https://github.com/iotaledger/twin-telemetry/compare/telemetry-connector-opentelemetry-v0.0.3-next.5...telemetry-connector-opentelemetry-v0.0.3-next.6) (2026-05-11)
+
+
+### Features
+
+* improve open telemetry config ([8803201](https://github.com/iotaledger/twin-telemetry/commit/8803201611b1799a00cd657e0675f85596c4edce))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/telemetry-connector-entity-storage bumped from 0.0.3-next.5 to 0.0.3-next.6
+    * @twin.org/telemetry-models bumped from 0.0.3-next.5 to 0.0.3-next.6
+
+## [0.0.3-next.5](https://github.com/iotaledger/twin-telemetry/compare/telemetry-connector-opentelemetry-v0.0.3-next.4...telemetry-connector-opentelemetry-v0.0.3-next.5) (2026-05-11)
+
+
+### Features
+
+* add OpenTelemetry connector, tests and a graphana example ([#22](https://github.com/iotaledger/twin-telemetry/issues/22)) ([ae3e08f](https://github.com/iotaledger/twin-telemetry/commit/ae3e08f459cb20ff5d2a149982676de8c2f90ae1))
+* typescript 6 update ([0acecc2](https://github.com/iotaledger/twin-telemetry/commit/0acecc2692b174fbaec6a8a89bd9277fa3530b5f))
+
+
+### Bug Fixes
+
+* docs ([acc23a6](https://github.com/iotaledger/twin-telemetry/commit/acc23a674e75752e3817e2717d6b029d0b1404ff))
+* open-telemetry config options ([c35ee76](https://github.com/iotaledger/twin-telemetry/commit/c35ee764ccad9168985fcac6efc3461422884ce4))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/telemetry-connector-entity-storage bumped from 0.0.3-next.2 to 0.0.3-next.5
+    * @twin.org/telemetry-models bumped from 0.0.3-next.2 to 0.0.3-next.5
+
+## Changelog

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 '@twin.org/entity-storage-models';
+import { MemoryEntityStorageConnector } from '@twin.org/entity-storage-connector-memory';
+import { TelemetryConnectorFactory } from '@twin.org/telemetry-models';
+import {
+  OpenTelemetryTelemetryConnector,
+  initSchema,
+  type TelemetryMetric,
+  type TelemetryMetricValue
+} from '@twin.org/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 '@twin.org/telemetry-models';
+import { OpenTelemetryTelemetryConnector } from '@twin.org/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 '@twin.org/telemetry-models';
+import { OpenTelemetryTelemetryConnector } from '@twin.org/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 '@twin.org/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`.