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

package/README.md

@@ -0,0 +1,21 @@
+# TWIN Telemetry Connector OpenTelemetry
+
+OpenTelemetry connector for pushing telemetry metrics to OTEL-compatible backends such as Prometheus and Grafana.
+
+## Installation
+
+```shell
+npm install @twin.org/telemetry-connector-opentelemetry
+```
+
+## Examples
+
+Usage of the APIs is shown in the examples [docs/examples.md](docs/examples.md)
+
+## Reference
+
+Detailed reference documentation for the API can be found in [docs/reference/index.md](docs/reference/index.md)
+
+## Changelog
+
+The changes between each version can be found in [docs/changelog.md](docs/changelog.md)

package/dist/es/index.js

@@ -0,0 +1,9 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+export * from "./models/IOpenTelemetryPrometheusReaderConfig.js";
+export * from "./models/IOpenTelemetryReaderConfig.js";
+export * from "./models/IOpenTelemetryTelemetryConnectorConfig.js";
+export * from "./models/IOpenTelemetryTelemetryConnectorConstructorOptions.js";
+export * from "./models/openTelemetryReaderTypes.js";
+export * from "./openTelemetryTelemetryConnector.js";
+//# sourceMappingURL=index.js.map

package/dist/es/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,cAAc,kDAAkD,CAAC;AACjE,cAAc,wCAAwC,CAAC;AACvD,cAAc,oDAAoD,CAAC;AACnE,cAAc,gEAAgE,CAAC;AAC/E,cAAc,sCAAsC,CAAC;AACrD,cAAc,sCAAsC,CAAC","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nexport * from \"./models/IOpenTelemetryPrometheusReaderConfig.js\";\nexport * from \"./models/IOpenTelemetryReaderConfig.js\";\nexport * from \"./models/IOpenTelemetryTelemetryConnectorConfig.js\";\nexport * from \"./models/IOpenTelemetryTelemetryConnectorConstructorOptions.js\";\nexport * from \"./models/openTelemetryReaderTypes.js\";\nexport * from \"./openTelemetryTelemetryConnector.js\";\n"]}

package/dist/es/models/IOpenTelemetryPrometheusReaderConfig.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=IOpenTelemetryPrometheusReaderConfig.js.map

package/dist/es/models/IOpenTelemetryPrometheusReaderConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IOpenTelemetryPrometheusReaderConfig.js","sourceRoot":"","sources":["../../../src/models/IOpenTelemetryPrometheusReaderConfig.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { OpenTelemetryReaderTypes } from \"./openTelemetryReaderTypes.js\";\n\n/**\n * Configuration for a Prometheus scrape-endpoint reader.\n * The connector instantiates a PrometheusExporter from these options in start().\n */\nexport interface IOpenTelemetryPrometheusReaderConfig {\n\t/**\n\t * Type.\n\t */\n\ttype: typeof OpenTelemetryReaderTypes.Prometheus;\n\n\t/**\n\t * TCP port the Prometheus HTTP server listens on.\n\t * @default 9464\n\t */\n\tport?: number;\n\n\t/**\n\t * HTTP path that Prometheus scrapes.\n\t * @default /metrics\n\t */\n\tendpoint?: string;\n\n\t/**\n\t * Whether to start the built-in HTTP server automatically.\n\t * Set to false if you manage the server externally.\n\t * @default true\n\t */\n\tstartServer?: boolean;\n\n\t/**\n\t * Optional string prepended to every exported metric name.\n\t */\n\tprefix?: string;\n}\n"]}

package/dist/es/models/IOpenTelemetryReaderConfig.js

@@ -0,0 +1,3 @@
+export {};
+// Future: | IOpenTelemetryOtlpReaderConfig | IOpenTelemetryConsoleReaderConfig
+//# sourceMappingURL=IOpenTelemetryReaderConfig.js.map

package/dist/es/models/IOpenTelemetryReaderConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IOpenTelemetryReaderConfig.js","sourceRoot":"","sources":["../../../src/models/IOpenTelemetryReaderConfig.ts"],"names":[],"mappings":";AASA,+EAA+E","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IOpenTelemetryPrometheusReaderConfig } from \"./IOpenTelemetryPrometheusReaderConfig.js\";\n\n/**\n * Discriminated union of all supported metric-reader configurations.\n * Add new members here when additional exporter types are implemented.\n */\nexport type IOpenTelemetryReaderConfig = IOpenTelemetryPrometheusReaderConfig;\n// Future: | IOpenTelemetryOtlpReaderConfig | IOpenTelemetryConsoleReaderConfig\n"]}

package/dist/es/models/IOpenTelemetryTelemetryConnectorConfig.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=IOpenTelemetryTelemetryConnectorConfig.js.map

package/dist/es/models/IOpenTelemetryTelemetryConnectorConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IOpenTelemetryTelemetryConnectorConfig.js","sourceRoot":"","sources":["../../../src/models/IOpenTelemetryTelemetryConnectorConfig.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IOpenTelemetryReaderConfig } from \"./IOpenTelemetryReaderConfig.js\";\n\n/**\n * The options for the OpenTelemetry telemetry connector constructor.\n */\nexport interface IOpenTelemetryTelemetryConnectorConfig {\n\t/**\n\t * The name of the OpenTelemetry meter used to create instruments.\n\t * @default twin-telemetry\n\t */\n\tmeterName?: string;\n\n\t/**\n\t * The version reported by the OpenTelemetry meter.\n\t * @default 1.0.0\n\t */\n\tmeterVersion?: string;\n\n\t/**\n\t * Named metric-reader configurations keyed by an arbitrary id.\n\t * Each entry's `type` field determines which exporter the connector instantiates\n\t * in start(). Omit or pass an empty object for a no-op provider (useful for tests).\n\t */\n\treaders?: { [id: string]: IOpenTelemetryReaderConfig };\n}\n"]}

package/dist/es/models/IOpenTelemetryTelemetryConnectorConstructorOptions.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=IOpenTelemetryTelemetryConnectorConstructorOptions.js.map

package/dist/es/models/IOpenTelemetryTelemetryConnectorConstructorOptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IOpenTelemetryTelemetryConnectorConstructorOptions.js","sourceRoot":"","sources":["../../../src/models/IOpenTelemetryTelemetryConnectorConstructorOptions.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IOpenTelemetryTelemetryConnectorConfig } from \"./IOpenTelemetryTelemetryConnectorConfig.js\";\n\n/**\n * The options for the OpenTelemetry telemetry connector constructor.\n */\nexport interface IOpenTelemetryTelemetryConnectorConstructorOptions {\n\t/**\n\t * The component type to use for logging inside the connector and the inner\n\t * entity-storage connector. When omitted logging is disabled.\n\t */\n\tloggingComponentType?: string;\n\n\t/**\n\t * The entity storage connector type to use for storing metric definitions.\n\t * Must be registered in `EntityStorageConnectorFactory` before calling `start()`.\n\t * @default telemetry-metric\n\t */\n\ttelemetryMetricStorageConnectorType?: string;\n\n\t/**\n\t * The entity storage connector type to use for storing metric values.\n\t * Must be registered in `EntityStorageConnectorFactory` before calling `start()`.\n\t * @default telemetry-metric-value\n\t */\n\ttelemetryMetricValueStorageConnectorType?: string;\n\n\t/**\n\t * The config for the telemetry connector.\n\t */\n\tconfig?: IOpenTelemetryTelemetryConnectorConfig;\n}\n"]}

package/dist/es/models/openTelemetryReaderTypes.js

@@ -0,0 +1,13 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+/**
+ * The types of readers.
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export const OpenTelemetryReaderTypes = {
+    /**
+     * Prometheus.
+     */
+    Prometheus: "prometheus"
+};
+//# sourceMappingURL=openTelemetryReaderTypes.js.map

package/dist/es/models/openTelemetryReaderTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openTelemetryReaderTypes.js","sourceRoot":"","sources":["../../../src/models/openTelemetryReaderTypes.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AAEvC;;GAEG;AACH,gEAAgE;AAChE,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACvC;;OAEG;IACH,UAAU,EAAE,YAAY;CACf,CAAC","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * The types of readers.\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention\nexport const OpenTelemetryReaderTypes = {\n\t/**\n\t * Prometheus.\n\t */\n\tPrometheus: \"prometheus\"\n} as const;\n\n/**\n * The types of readers.\n */\nexport type OpenTelemetryReaderTypes =\n\t(typeof OpenTelemetryReaderTypes)[keyof typeof OpenTelemetryReaderTypes];\n"]}

package/dist/es/openTelemetryTelemetryConnector.js

@@ -0,0 +1,307 @@
+import { MeterProvider } from "@opentelemetry/sdk-metrics";
+import { AlreadyExistsError, BaseError, ComponentFactory, GeneralError, Is } from "@twin.org/core";
+import { EntityStorageTelemetryConnector } from "@twin.org/telemetry-connector-entity-storage";
+import { MetricCounterOperation, MetricType } from "@twin.org/telemetry-models";
+/**
+ * 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 class OpenTelemetryTelemetryConnector {
+    /**
+     * The namespace supported by the telemetry connector.
+     */
+    static NAMESPACE = "opentelemetry";
+    /**
+     * Runtime name for the class.
+     */
+    static CLASS_NAME = "OpenTelemetryTelemetryConnector";
+    /**
+     * Config options, stored so start() can initialise the MeterProvider.
+     * @internal
+     */
+    _config;
+    /**
+     * Internal entity-storage connector that owns all metric metadata and value history.
+     * Created at construction time — fails fast if entity storage is not set up.
+     * @internal
+     */
+    _inner;
+    /**
+     * Live OTEL instrument handles keyed by metric id, paired with the metric type
+     * so addMetricValue can dispatch without querying storage.
+     * These are runtime objects and cannot be persisted.
+     * @internal
+     */
+    _instruments;
+    /**
+     * The MeterProvider that owns all instruments. Set by start(), cleared by stop().
+     * @internal
+     */
+    _meterProvider;
+    /**
+     * The Meter used to create instruments. Set by start(), cleared by stop().
+     * @internal
+     */
+    _meter;
+    /**
+     * 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) {
+        this._config = options?.config ?? {};
+        this._inner = new EntityStorageTelemetryConnector({
+            loggingComponentType: options?.loggingComponentType,
+            telemetryMetricStorageConnectorType: options?.telemetryMetricStorageConnectorType,
+            telemetryMetricValueStorageConnectorType: options?.telemetryMetricValueStorageConnectorType
+        });
+        this._instruments = new Map();
+    }
+    /**
+     * Returns the class name of the component.
+     * @returns The class name of the component.
+     */
+    className() {
+        return OpenTelemetryTelemetryConnector.CLASS_NAME;
+    }
+    /**
+     * Initialise the MeterProvider and configured exporters.
+     * @param nodeLoggingComponentType The node logging component type.
+     * @returns Nothing.
+     */
+    async start(nodeLoggingComponentType) {
+        if (!Is.undefined(this._meterProvider)) {
+            return;
+        }
+        const readers = [];
+        for (const [, config] of Object.entries(this._config.readers ?? {})) {
+            if (config.type === "prometheus") {
+                // Dynamic import so @opentelemetry/exporter-prometheus is an optional peer dep;
+                // consumers only need to install it if they actually configure a Prometheus reader.
+                const { PrometheusExporter: prometheusExporterClass } = await import("@opentelemetry/exporter-prometheus");
+                readers.push(new prometheusExporterClass({
+                    port: config.port,
+                    endpoint: config.endpoint,
+                    // PrometheusExporter uses preventServerStart (inverted); our config
+                    // exposes the more intuitive startServer (defaults to true).
+                    preventServerStart: !(config.startServer ?? true),
+                    prefix: config.prefix
+                }));
+            }
+            else {
+                throw new GeneralError(OpenTelemetryTelemetryConnector.CLASS_NAME, "unknownReaderType", {
+                    type: config.type
+                });
+            }
+        }
+        this._meterProvider = new MeterProvider({ readers });
+        this._meter = this._meterProvider.getMeter(this._config.meterName ?? "twin-telemetry", this._config.meterVersion ?? "1.0.0");
+        const nodeLogging = ComponentFactory.getIfExists(nodeLoggingComponentType);
+        await nodeLogging?.log({
+            source: OpenTelemetryTelemetryConnector.CLASS_NAME,
+            message: "connectorStarted",
+            level: "info",
+            data: { readerCount: Object.keys(this._config.readers ?? {}).length }
+        });
+    }
+    /**
+     * 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.
+     */
+    async stop(nodeLoggingComponentType) {
+        if (!Is.undefined(this._meterProvider)) {
+            await this._meterProvider.shutdown();
+            this._meterProvider = undefined;
+            this._meter = undefined;
+            this._instruments.clear();
+            const nodeLogging = ComponentFactory.getIfExists(nodeLoggingComponentType);
+            await nodeLogging?.log({
+                source: OpenTelemetryTelemetryConnector.CLASS_NAME,
+                message: "connectorStopped",
+                level: "info",
+                data: {}
+            });
+        }
+    }
+    /**
+     * 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.
+     */
+    async createMetric(metric) {
+        try {
+            await this._inner.createMetric(metric);
+        }
+        catch (err) {
+            // Entity storage performs all validation and throws AlreadyExistsError on duplicates.
+            // OTP doesn't care about duplicates and will create a new instrument instance on each call
+            // so we catch this error and ignore it to allow the OTEL instruments to be registered.
+            if (!BaseError.isErrorName(err, AlreadyExistsError.CLASS_NAME)) {
+                throw err;
+            }
+        }
+        // Register an OTEL instrument when the MeterProvider is running.
+        // This runs even when the metric already exists in storage so instruments
+        // survive process restarts (AlreadyExistsError path).
+        const meter = this._meter;
+        if (meter !== undefined && !this._instruments.has(metric.id)) {
+            const instrumentOptions = {
+                description: metric.description,
+                unit: metric.unit
+            };
+            let instrument;
+            if (metric.type === MetricType.Counter) {
+                instrument = meter.createCounter(metric.id, instrumentOptions);
+            }
+            else if (metric.type === MetricType.IncDecCounter) {
+                instrument = meter.createUpDownCounter(metric.id, instrumentOptions);
+            }
+            else {
+                instrument = meter.createGauge(metric.id, instrumentOptions);
+            }
+            this._instruments.set(metric.id, { metricType: metric.type, instrument });
+        }
+    }
+    /**
+     * Get the metric details and its most recent value.
+     * @param id The metric id.
+     * @returns The metric details and its most recent value.
+     */
+    async getMetric(id) {
+        const result = await this._inner.getMetric(id);
+        // When the metric has no recorded values yet the inner connector returns
+        // entities[0] = undefined via queryValues. Return a placeholder so callers
+        // are not surprised by a null value field — treat id="" as "no measurements yet".
+        const value = result.value ?? { id: "", ts: 0, value: 0 };
+        return { metric: result.metric, value };
+    }
+    /**
+     * 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.
+     */
+    async updateMetric(metric) {
+        return this._inner.updateMetric(metric);
+    }
+    /**
+     * 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.
+     */
+    async addMetricValue(id, value, customData) {
+        // Entity storage validates and persists first; throws NotFoundError if metric not found.
+        const valueId = await this._inner.addMetricValue(id, value, customData);
+        // Forward to the OTEL instrument only when the MeterProvider is running.
+        if (this._meter !== undefined) {
+            const entry = this._instruments.get(id);
+            if (entry !== undefined) {
+                const attributes = this.toAttributes(customData);
+                const { metricType, instrument } = entry;
+                // Value already validated by inner connector — dispatch unconditionally.
+                if (metricType === MetricType.Counter) {
+                    instrument.add(value === MetricCounterOperation.Increment ? 1 : value, attributes);
+                }
+                else if (metricType === MetricType.IncDecCounter) {
+                    let delta;
+                    if (value === MetricCounterOperation.Increment) {
+                        delta = 1;
+                    }
+                    else if (value === MetricCounterOperation.Decrement) {
+                        delta = -1;
+                    }
+                    else {
+                        delta = value;
+                    }
+                    instrument.add(delta, attributes);
+                }
+                else {
+                    instrument.record(value, attributes);
+                }
+            }
+        }
+        return valueId;
+    }
+    /**
+     * 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.
+     */
+    async removeMetric(id) {
+        this._instruments.delete(id);
+        // The inner connector cascades and removes all associated metric values.
+        return this._inner.removeMetric(id);
+    }
+    /**
+     * 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.
+     */
+    async query(type, cursor, limit) {
+        return this._inner.query(type, cursor, limit);
+    }
+    /**
+     * 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.
+     */
+    async queryValues(id, timeStart, timeEnd, cursor, limit) {
+        return this._inner.queryValues(id, timeStart, timeEnd, cursor, limit);
+    }
+    /**
+     * Convert customData to OTEL-compatible Attributes.
+     * Scalar values (string, number, boolean) and uniform primitive arrays
+     * (string[], number[], boolean[]) are forwarded; other values are silently dropped.
+     * @param customData The raw custom data map.
+     * @returns An OTEL Attributes object.
+     * @internal
+     */
+    toAttributes(customData) {
+        if (Is.empty(customData)) {
+            return {};
+        }
+        const attrs = {};
+        for (const [key, val] of Object.entries(customData)) {
+            if (Is.string(val) || Is.number(val) || Is.boolean(val)) {
+                attrs[key] = val;
+            }
+            else if (Is.arrayValue(val)) {
+                if ((Is.string(val[0]) || Is.number(val[0]) || Is.boolean(val[0])) &&
+                    val.every(el => typeof el === typeof val[0])) {
+                    attrs[key] = val;
+                }
+            }
+        }
+        return attrs;
+    }
+}
+//# sourceMappingURL=openTelemetryTelemetryConnector.js.map

package/dist/es/openTelemetryTelemetryConnector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openTelemetryTelemetryConnector.js","sourceRoot":"","sources":["../../src/openTelemetryTelemetryConnector.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { Attributes, Counter, Gauge, Meter, UpDownCounter } from \"@opentelemetry/api\";\nimport { MeterProvider, type MetricReader } from \"@opentelemetry/sdk-metrics\";\nimport { AlreadyExistsError, BaseError, ComponentFactory, GeneralError, Is } from \"@twin.org/core\";\nimport type { ILoggingComponent } from \"@twin.org/logging-models\";\nimport { nameof } from \"@twin.org/nameof\";\nimport { EntityStorageTelemetryConnector } from \"@twin.org/telemetry-connector-entity-storage\";\nimport {\n\ttype ITelemetryConnector,\n\ttype ITelemetryMetric,\n\ttype ITelemetryMetricValue,\n\tMetricCounterOperation,\n\tMetricType\n} from \"@twin.org/telemetry-models\";\nimport type { IOpenTelemetryTelemetryConnectorConfig } from \"./models/IOpenTelemetryTelemetryConnectorConfig.js\";\nimport type { IOpenTelemetryTelemetryConnectorConstructorOptions } from \"./models/IOpenTelemetryTelemetryConnectorConstructorOptions.js\";\n\n/**\n * Class for performing telemetry operations using OpenTelemetry instruments.\n * Metric definitions and value history are persisted via an internal\n * EntityStorageTelemetryConnector instance created at construction time.\n * Call `start()` to initialise the MeterProvider and exporters; metrics can be\n * created and queried before start() — OTEL forwarding is simply skipped until\n * the MeterProvider is running.\n */\nexport class OpenTelemetryTelemetryConnector implements ITelemetryConnector {\n\t/**\n\t * The namespace supported by the telemetry connector.\n\t */\n\tpublic static readonly NAMESPACE: string = \"opentelemetry\";\n\n\t/**\n\t * Runtime name for the class.\n\t */\n\tpublic static readonly CLASS_NAME: string = nameof<OpenTelemetryTelemetryConnector>();\n\n\t/**\n\t * Config options, stored so start() can initialise the MeterProvider.\n\t * @internal\n\t */\n\tprivate readonly _config: IOpenTelemetryTelemetryConnectorConfig;\n\n\t/**\n\t * Internal entity-storage connector that owns all metric metadata and value history.\n\t * Created at construction time — fails fast if entity storage is not set up.\n\t * @internal\n\t */\n\tprivate readonly _inner: EntityStorageTelemetryConnector;\n\n\t/**\n\t * Live OTEL instrument handles keyed by metric id, paired with the metric type\n\t * so addMetricValue can dispatch without querying storage.\n\t * These are runtime objects and cannot be persisted.\n\t * @internal\n\t */\n\tprivate readonly _instruments: Map<\n\t\tstring,\n\t\t{ metricType: MetricType; instrument: Counter | UpDownCounter | Gauge }\n\t>;\n\n\t/**\n\t * The MeterProvider that owns all instruments. Set by start(), cleared by stop().\n\t * @internal\n\t */\n\tprivate _meterProvider?: MeterProvider;\n\n\t/**\n\t * The Meter used to create instruments. Set by start(), cleared by stop().\n\t * @internal\n\t */\n\tprivate _meter?: Meter;\n\n\t/**\n\t * Create a new instance of OpenTelemetryTelemetryConnector.\n\t * Eagerly constructs the inner EntityStorageTelemetryConnector — if the required\n\t * entity storage types are not registered this constructor will throw (fail fast).\n\t * @param options The options for the connector.\n\t */\n\tconstructor(options?: IOpenTelemetryTelemetryConnectorConstructorOptions) {\n\t\tthis._config = options?.config ?? {};\n\t\tthis._inner = new EntityStorageTelemetryConnector({\n\t\t\tloggingComponentType: options?.loggingComponentType,\n\t\t\ttelemetryMetricStorageConnectorType: options?.telemetryMetricStorageConnectorType,\n\t\t\ttelemetryMetricValueStorageConnectorType: options?.telemetryMetricValueStorageConnectorType\n\t\t});\n\t\tthis._instruments = new Map();\n\t}\n\n\t/**\n\t * Returns the class name of the component.\n\t * @returns The class name of the component.\n\t */\n\tpublic className(): string {\n\t\treturn OpenTelemetryTelemetryConnector.CLASS_NAME;\n\t}\n\n\t/**\n\t * Initialise the MeterProvider and configured exporters.\n\t * @param nodeLoggingComponentType The node logging component type.\n\t * @returns Nothing.\n\t */\n\tpublic async start(nodeLoggingComponentType?: string): Promise<void> {\n\t\tif (!Is.undefined(this._meterProvider)) {\n\t\t\treturn;\n\t\t}\n\n\t\tconst readers: MetricReader[] = [];\n\t\tfor (const [, config] of Object.entries(this._config.readers ?? {})) {\n\t\t\tif (config.type === \"prometheus\") {\n\t\t\t\t// Dynamic import so @opentelemetry/exporter-prometheus is an optional peer dep;\n\t\t\t\t// consumers only need to install it if they actually configure a Prometheus reader.\n\t\t\t\tconst { PrometheusExporter: prometheusExporterClass } =\n\t\t\t\t\tawait import(\"@opentelemetry/exporter-prometheus\");\n\t\t\t\treaders.push(\n\t\t\t\t\tnew prometheusExporterClass({\n\t\t\t\t\t\tport: config.port,\n\t\t\t\t\t\tendpoint: config.endpoint,\n\t\t\t\t\t\t// PrometheusExporter uses preventServerStart (inverted); our config\n\t\t\t\t\t\t// exposes the more intuitive startServer (defaults to true).\n\t\t\t\t\t\tpreventServerStart: !(config.startServer ?? true),\n\t\t\t\t\t\tprefix: config.prefix\n\t\t\t\t\t})\n\t\t\t\t);\n\t\t\t} else {\n\t\t\t\tthrow new GeneralError(OpenTelemetryTelemetryConnector.CLASS_NAME, \"unknownReaderType\", {\n\t\t\t\t\ttype: config.type\n\t\t\t\t});\n\t\t\t}\n\t\t}\n\n\t\tthis._meterProvider = new MeterProvider({ readers });\n\t\tthis._meter = this._meterProvider.getMeter(\n\t\t\tthis._config.meterName ?? \"twin-telemetry\",\n\t\t\tthis._config.meterVersion ?? \"1.0.0\"\n\t\t);\n\n\t\tconst nodeLogging = ComponentFactory.getIfExists<ILoggingComponent>(nodeLoggingComponentType);\n\t\tawait nodeLogging?.log({\n\t\t\tsource: OpenTelemetryTelemetryConnector.CLASS_NAME,\n\t\t\tmessage: \"connectorStarted\",\n\t\t\tlevel: \"info\",\n\t\t\tdata: { readerCount: Object.keys(this._config.readers ?? {}).length }\n\t\t});\n\t}\n\n\t/**\n\t * Shut down the MeterProvider and release resources.\n\t * Calling stop() on a connector that has not been started is a no-op.\n\t * @param nodeLoggingComponentType The node logging component type.\n\t * @returns Nothing.\n\t */\n\tpublic async stop(nodeLoggingComponentType?: string): Promise<void> {\n\t\tif (!Is.undefined(this._meterProvider)) {\n\t\t\tawait this._meterProvider.shutdown();\n\t\t\tthis._meterProvider = undefined;\n\t\t\tthis._meter = undefined;\n\t\t\tthis._instruments.clear();\n\n\t\t\tconst nodeLogging = ComponentFactory.getIfExists<ILoggingComponent>(nodeLoggingComponentType);\n\t\t\tawait nodeLogging?.log({\n\t\t\t\tsource: OpenTelemetryTelemetryConnector.CLASS_NAME,\n\t\t\t\tmessage: \"connectorStopped\",\n\t\t\t\tlevel: \"info\",\n\t\t\t\tdata: {}\n\t\t\t});\n\t\t}\n\t}\n\n\t/**\n\t * Create a new metric.\n\t * The definition is always persisted via the inner entity-storage connector.\n\t * If the MeterProvider is running the corresponding OTEL instrument is also registered.\n\t * @param metric The metric details.\n\t * @returns Nothing.\n\t */\n\tpublic async createMetric(metric: ITelemetryMetric): Promise<void> {\n\t\ttry {\n\t\t\tawait this._inner.createMetric(metric);\n\t\t} catch (err) {\n\t\t\t// Entity storage performs all validation and throws AlreadyExistsError on duplicates.\n\t\t\t// OTP doesn't care about duplicates and will create a new instrument instance on each call\n\t\t\t// so we catch this error and ignore it to allow the OTEL instruments to be registered.\n\t\t\tif (!BaseError.isErrorName(err, AlreadyExistsError.CLASS_NAME)) {\n\t\t\t\tthrow err;\n\t\t\t}\n\t\t}\n\n\t\t// Register an OTEL instrument when the MeterProvider is running.\n\t\t// This runs even when the metric already exists in storage so instruments\n\t\t// survive process restarts (AlreadyExistsError path).\n\t\tconst meter = this._meter;\n\t\tif (meter !== undefined && !this._instruments.has(metric.id)) {\n\t\t\tconst instrumentOptions = {\n\t\t\t\tdescription: metric.description,\n\t\t\t\tunit: metric.unit\n\t\t\t};\n\t\t\tlet instrument: Counter | UpDownCounter | Gauge;\n\t\t\tif (metric.type === MetricType.Counter) {\n\t\t\t\tinstrument = meter.createCounter(metric.id, instrumentOptions);\n\t\t\t} else if (metric.type === MetricType.IncDecCounter) {\n\t\t\t\tinstrument = meter.createUpDownCounter(metric.id, instrumentOptions);\n\t\t\t} else {\n\t\t\t\tinstrument = meter.createGauge(metric.id, instrumentOptions);\n\t\t\t}\n\t\t\tthis._instruments.set(metric.id, { metricType: metric.type, instrument });\n\t\t}\n\t}\n\n\t/**\n\t * Get the metric details and its most recent value.\n\t * @param id The metric id.\n\t * @returns The metric details and its most recent value.\n\t */\n\tpublic async getMetric(id: string): Promise<{\n\t\tmetric: ITelemetryMetric;\n\t\tvalue: ITelemetryMetricValue;\n\t}> {\n\t\tconst result = await this._inner.getMetric(id);\n\n\t\t// When the metric has no recorded values yet the inner connector returns\n\t\t// entities[0] = undefined via queryValues. Return a placeholder so callers\n\t\t// are not surprised by a null value field — treat id=\"\" as \"no measurements yet\".\n\t\tconst value = result.value ?? { id: \"\", ts: 0, value: 0 };\n\t\treturn { metric: result.metric, value };\n\t}\n\n\t/**\n\t * Update the metric metadata.\n\t * Note: OpenTelemetry instrument descriptors are immutable once created.\n\t * This method updates the persisted metadata mirror; the description/unit changes\n\t * are NOT propagated to the registered MeterProvider and will not appear at the\n\t * OTEL backend (Prometheus, OTLP, etc.).\n\t * @param metric The metric details (type cannot be changed).\n\t * @returns Nothing.\n\t */\n\tpublic async updateMetric(metric: Omit<ITelemetryMetric, \"type\">): Promise<void> {\n\t\treturn this._inner.updateMetric(metric);\n\t}\n\n\t/**\n\t * Record a metric value.\n\t * Entity storage always receives the value first and performs all validation.\n\t * If the MeterProvider is running the measurement is also forwarded to the OTEL instrument.\n\t * Counter accepts positive integers or \"inc\".\n\t * UpDownCounter accepts integers (positive or negative) or \"inc\"/\"dec\".\n\t * Gauge accepts any number.\n\t * @param id The id of the metric.\n\t * @param value The value for the operation.\n\t * @param customData Optional custom data forwarded as OTEL attributes.\n\t * @returns The id of the new metric value entry.\n\t */\n\tpublic async addMetricValue(\n\t\tid: string,\n\t\tvalue: MetricCounterOperation | number,\n\t\tcustomData?: { [key: string]: unknown }\n\t): Promise<string> {\n\t\t// Entity storage validates and persists first; throws NotFoundError if metric not found.\n\t\tconst valueId = await this._inner.addMetricValue(id, value, customData);\n\n\t\t// Forward to the OTEL instrument only when the MeterProvider is running.\n\t\tif (this._meter !== undefined) {\n\t\t\tconst entry = this._instruments.get(id);\n\t\t\tif (entry !== undefined) {\n\t\t\t\tconst attributes = this.toAttributes(customData);\n\t\t\t\tconst { metricType, instrument } = entry;\n\n\t\t\t\t// Value already validated by inner connector — dispatch unconditionally.\n\t\t\t\tif (metricType === MetricType.Counter) {\n\t\t\t\t\t(instrument as Counter).add(\n\t\t\t\t\t\tvalue === MetricCounterOperation.Increment ? 1 : (value as number),\n\t\t\t\t\t\tattributes\n\t\t\t\t\t);\n\t\t\t\t} else if (metricType === MetricType.IncDecCounter) {\n\t\t\t\t\tlet delta: number;\n\t\t\t\t\tif (value === MetricCounterOperation.Increment) {\n\t\t\t\t\t\tdelta = 1;\n\t\t\t\t\t} else if (value === MetricCounterOperation.Decrement) {\n\t\t\t\t\t\tdelta = -1;\n\t\t\t\t\t} else {\n\t\t\t\t\t\tdelta = value;\n\t\t\t\t\t}\n\t\t\t\t\t(instrument as UpDownCounter).add(delta, attributes);\n\t\t\t\t} else {\n\t\t\t\t\t(instrument as Gauge).record(value as number, attributes);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\treturn valueId;\n\t}\n\n\t/**\n\t * Remove a metric and its persisted value history.\n\t * Note: OpenTelemetry exposes no API to deregister an instrument from a Meter,\n\t * so the underlying Counter/UpDownCounter/Gauge remains resident for the lifetime\n\t * of the process. Re-creating a metric with the same id but a different MetricType\n\t * is therefore not safe.\n\t * @param id The id of the metric.\n\t * @returns Nothing.\n\t */\n\tpublic async removeMetric(id: string): Promise<void> {\n\t\tthis._instruments.delete(id);\n\t\t// The inner connector cascades and removes all associated metric values.\n\t\treturn this._inner.removeMetric(id);\n\t}\n\n\t/**\n\t * Query the registered metrics, optionally filtered by type.\n\t * @param type The type of the metric.\n\t * @param cursor The cursor to request the next page.\n\t * @param limit Limit the number of entities to return.\n\t * @returns The matching metrics and an optional cursor for the next page.\n\t */\n\tpublic async query(\n\t\ttype?: MetricType,\n\t\tcursor?: string,\n\t\tlimit?: number\n\t): Promise<{\n\t\tentities: ITelemetryMetric[];\n\t\tcursor?: string;\n\t}> {\n\t\treturn this._inner.query(type, cursor, limit);\n\t}\n\n\t/**\n\t * Query the recorded values for a metric, ordered by most recent first.\n\t * @param id The id of the metric.\n\t * @param timeStart The inclusive start time (epoch ms).\n\t * @param timeEnd The inclusive end time (epoch ms).\n\t * @param cursor The cursor returned by the previous call.\n\t * @param limit Limit the number of values to return.\n\t * @returns The metric details, matching values, and an optional cursor for the next page.\n\t */\n\tpublic async queryValues(\n\t\tid: string,\n\t\ttimeStart?: number,\n\t\ttimeEnd?: number,\n\t\tcursor?: string,\n\t\tlimit?: number\n\t): Promise<{\n\t\tmetric: ITelemetryMetric;\n\t\tentities: ITelemetryMetricValue[];\n\t\tcursor?: string;\n\t}> {\n\t\treturn this._inner.queryValues(id, timeStart, timeEnd, cursor, limit);\n\t}\n\n\t/**\n\t * Convert customData to OTEL-compatible Attributes.\n\t * Scalar values (string, number, boolean) and uniform primitive arrays\n\t * (string[], number[], boolean[]) are forwarded; other values are silently dropped.\n\t * @param customData The raw custom data map.\n\t * @returns An OTEL Attributes object.\n\t * @internal\n\t */\n\tprivate toAttributes(customData?: { [key: string]: unknown }): Attributes {\n\t\tif (Is.empty(customData)) {\n\t\t\treturn {};\n\t\t}\n\t\tconst attrs: Attributes = {};\n\t\tfor (const [key, val] of Object.entries(customData)) {\n\t\t\tif (Is.string(val) || Is.number(val) || Is.boolean(val)) {\n\t\t\t\tattrs[key] = val;\n\t\t\t} else if (Is.arrayValue(val)) {\n\t\t\t\tif (\n\t\t\t\t\t(Is.string(val[0]) || Is.number(val[0]) || Is.boolean(val[0])) &&\n\t\t\t\t\tval.every(el => typeof el === typeof val[0])\n\t\t\t\t) {\n\t\t\t\t\tattrs[key] = val as string[] | number[] | boolean[];\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\treturn attrs;\n\t}\n}\n"]}

package/dist/types/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./models/IOpenTelemetryPrometheusReaderConfig.js";
+export * from "./models/IOpenTelemetryReaderConfig.js";
+export * from "./models/IOpenTelemetryTelemetryConnectorConfig.js";
+export * from "./models/IOpenTelemetryTelemetryConnectorConstructorOptions.js";
+export * from "./models/openTelemetryReaderTypes.js";
+export * from "./openTelemetryTelemetryConnector.js";

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

@@ -0,0 +1,31 @@
+import type { OpenTelemetryReaderTypes } from "./openTelemetryReaderTypes.js";
+/**
+ * Configuration for a Prometheus scrape-endpoint reader.
+ * The connector instantiates a PrometheusExporter from these options in start().
+ */
+export interface IOpenTelemetryPrometheusReaderConfig {
+    /**
+     * Type.
+     */
+    type: typeof OpenTelemetryReaderTypes.Prometheus;
+    /**
+     * TCP port the Prometheus HTTP server listens on.
+     * @default 9464
+     */
+    port?: number;
+    /**
+     * HTTP path that Prometheus scrapes.
+     * @default /metrics
+     */
+    endpoint?: string;
+    /**
+     * Whether to start the built-in HTTP server automatically.
+     * Set to false if you manage the server externally.
+     * @default true
+     */
+    startServer?: boolean;
+    /**
+     * Optional string prepended to every exported metric name.
+     */
+    prefix?: string;
+}

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

@@ -0,0 +1,6 @@
+import type { IOpenTelemetryPrometheusReaderConfig } from "./IOpenTelemetryPrometheusReaderConfig.js";
+/**
+ * Discriminated union of all supported metric-reader configurations.
+ * Add new members here when additional exporter types are implemented.
+ */
+export type IOpenTelemetryReaderConfig = IOpenTelemetryPrometheusReaderConfig;

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,27 @@
+import type { IOpenTelemetryTelemetryConnectorConfig } from "./IOpenTelemetryTelemetryConnectorConfig.js";
+/**
+ * The options for the OpenTelemetry telemetry connector constructor.
+ */
+export interface IOpenTelemetryTelemetryConnectorConstructorOptions {
+    /**
+     * The component type to use for logging inside the connector and the inner
+     * entity-storage connector. When omitted logging is disabled.
+     */
+    loggingComponentType?: string;
+    /**
+     * The entity storage connector type to use for storing metric definitions.
+     * Must be registered in `EntityStorageConnectorFactory` before calling `start()`.
+     * @default telemetry-metric
+     */
+    telemetryMetricStorageConnectorType?: string;
+    /**
+     * The entity storage connector type to use for storing metric values.
+     * Must be registered in `EntityStorageConnectorFactory` before calling `start()`.
+     * @default telemetry-metric-value
+     */
+    telemetryMetricValueStorageConnectorType?: string;
+    /**
+     * The config for the telemetry connector.
+     */
+    config?: IOpenTelemetryTelemetryConnectorConfig;
+}

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

@@ -0,0 +1,13 @@
+/**
+ * The types of readers.
+ */
+export declare const OpenTelemetryReaderTypes: {
+    /**
+     * Prometheus.
+     */
+    readonly Prometheus: "prometheus";
+};
+/**
+ * The types of readers.
+ */
+export type OpenTelemetryReaderTypes = (typeof OpenTelemetryReaderTypes)[keyof typeof OpenTelemetryReaderTypes];