npm - @twin.org/telemetry-connector-opentelemetry - Versions diffs - 0.9.2-next.1 → 0.9.2-next.2 - Mend

@twin.org/telemetry-connector-opentelemetry 0.9.2-next.1 → 0.9.2-next.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/dist/es/openTelemetryTelemetryConnector.js +150 -93
package/dist/es/openTelemetryTelemetryConnector.js.map +1 -1
package/dist/types/openTelemetryTelemetryConnector.d.ts +12 -23
package/docs/changelog.md +15 -0
package/docs/reference/classes/OpenTelemetryTelemetryConnector.md +15 -23
package/locales/en.json +0 -5
package/package.json +5 -3

package/dist/es/openTelemetryTelemetryConnector.js CHANGED Viewed

@@ -1,15 +1,15 @@
 import { PrometheusExporter } from "@opentelemetry/exporter-prometheus";
+import { resourceFromAttributes } from "@opentelemetry/resources";
 import { MeterProvider } from "@opentelemetry/sdk-metrics";
-import { AlreadyExistsError, BaseError, ComponentFactory, GeneralError, Is } from "@twin.org/core";
+import { ContextIdKeys, ContextIdStore } from "@twin.org/context";
+import { AlreadyExistsError, BaseError, ComponentFactory, Guards, Is } from "@twin.org/core";
 import { EntityStorageTelemetryConnector } from "@twin.org/telemetry-connector-entity-storage";
 import { MetricCounterOperation, MetricType } from "@twin.org/telemetry-models";
+import { OpenTelemetryReaderTypes } from "./models/openTelemetryReaderTypes.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 class OpenTelemetryTelemetryConnector {
     /**
@@ -21,41 +21,44 @@ export class OpenTelemetryTelemetryConnector {
      */
     static CLASS_NAME = "OpenTelemetryTelemetryConnector";
     /**
-     * Config options, stored so start() can initialise the MeterProvider.
+     * Config options stored so provider creation can initialise readers and meter identity.
      * @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.
+     * Whether start() has been called. Drives OTEL forwarding on/off.
      * @internal
      */
-    _instruments;
+    _started;
     /**
-     * The MeterProvider that owns all instruments. Set by start(), cleared by stop().
+     * Cache of MeterProvider+Meter+instruments keyed by "nodeId/tenantId".
+     * Providers are created on demand when the first metric measurement arrives
+     * for a given tenant/node pair.
      * @internal
      */
-    _meterProvider;
+    _providers;
     /**
-     * The Meter used to create instruments. Set by start(), cleared by stop().
+     * Metric definition cache keyed by metric id, populated in createMetric and on first
+     * addMetricValue after a process restart. Used to register instruments on new providers
+     * without re-querying entity storage on every call.
      * @internal
      */
-    _meter;
+    _metricDefs;
     /**
      * 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.
+     * @throws GuardError When a reader config specifies an unsupported type.
      */
     constructor(options) {
         this._config = options?.config ?? {};
+        for (const [, readerConfig] of Object.entries(this._config.readers ?? {})) {
+            Guards.arrayOneOf(OpenTelemetryTelemetryConnector.CLASS_NAME, "readerConfig.type", readerConfig.type, Object.values(OpenTelemetryReaderTypes));
+        }
         this._inner = new EntityStorageTelemetryConnector({
             loggingComponentType: options?.loggingComponentType,
             telemetryMetricStorageConnectorType: options?.telemetryMetricStorageConnectorType,
@@ -64,7 +67,9 @@ export class OpenTelemetryTelemetryConnector {
                 mutexTimeoutMs: this._config.mutexTimeoutMs
             }
         });
-        this._instruments = new Map();
+        this._started = false;
+        this._providers = {};
+        this._metricDefs = {};
     }
     /**
      * Returns the class name of the component.
@@ -74,34 +79,16 @@ export class OpenTelemetryTelemetryConnector {
         return OpenTelemetryTelemetryConnector.CLASS_NAME;
     }
     /**
-     * Initialise the MeterProvider and configured exporters.
+     * Enable OTEL forwarding. Subsequent calls to createMetric and addMetricValue will
+     * create per-tenant/node MeterProviders on demand.
      * @param nodeLoggingComponentType The node logging component type.
-     * @returns A promise that resolves when the MeterProvider is running.
+     * @returns A promise that resolves when OTEL forwarding is enabled.
      */
     async start(nodeLoggingComponentType) {
-        if (!Is.undefined(this._meterProvider)) {
+        if (this._started) {
             return;
         }
-        const readers = [];
-        for (const [, config] of Object.entries(this._config.readers ?? {})) {
-            if (config.type === "prometheus") {
-                readers.push(new PrometheusExporter({
-                    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");
+        this._started = true;
         const nodeLogging = ComponentFactory.getIfExists(nodeLoggingComponentType);
         await nodeLogging?.log({
             source: OpenTelemetryTelemetryConnector.CLASS_NAME,
@@ -111,17 +98,19 @@ export class OpenTelemetryTelemetryConnector {
         });
     }
     /**
-     * Shut down the MeterProvider and release resources.
-     * Calling stop() on a connector that has not been started is a no-op.
+     * Shut down all cached MeterProviders and disable OTEL forwarding.
      * @param nodeLoggingComponentType The node logging component type.
-     * @returns A promise that resolves when the MeterProvider has shut down.
+     * @returns A promise that resolves when all MeterProviders have shut down.
      */
     async stop(nodeLoggingComponentType) {
-        if (!Is.undefined(this._meterProvider)) {
-            await this._meterProvider.shutdown();
-            this._meterProvider = undefined;
-            this._meter = undefined;
-            this._instruments.clear();
+        if (this._started) {
+            for (const { meterProvider } of Object.values(this._providers)) {
+                await meterProvider.shutdown();
+            }
+            for (const key of Object.keys(this._providers)) {
+                delete this._providers[key];
+            }
+            this._started = false;
             const nodeLogging = ComponentFactory.getIfExists(nodeLoggingComponentType);
             await nodeLogging?.log({
                 source: OpenTelemetryTelemetryConnector.CLASS_NAME,
@@ -133,10 +122,8 @@ export class OpenTelemetryTelemetryConnector {
     }
     /**
      * 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 A promise that resolves when the metric has been persisted and the OTEL instrument registered.
+     * @returns A promise that resolves when the metric has been persisted.
      */
     async createMetric(metric) {
         try {
@@ -150,26 +137,15 @@ export class OpenTelemetryTelemetryConnector {
                 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 });
+        this._metricDefs[metric.id] = {
+            type: metric.type,
+            description: metric.description,
+            unit: metric.unit
+        };
+        if (this._started) {
+            const contextIds = (await ContextIdStore.getContextIds()) ?? {};
+            const { meter, instruments } = this.getOrCreateProvider(contextIds);
+            this.registerInstrument(metric.id, metric.type, metric.description, metric.unit, meter, instruments);
         }
     }
     /**
@@ -179,9 +155,6 @@ export class OpenTelemetryTelemetryConnector {
      */
     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 };
     }
@@ -197,9 +170,7 @@ export class OpenTelemetryTelemetryConnector {
     /**
      * 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.).
+     * This method updates the persisted metadata mirror only.
      * @param metric The metric details (type cannot be changed).
      * @returns A promise that resolves when the persisted metadata has been updated.
      */
@@ -208,26 +179,32 @@ export class OpenTelemetryTelemetryConnector {
     }
     /**
      * 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.
+     * 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 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 (this._started) {
+            const contextIds = (await ContextIdStore.getContextIds()) ?? {};
+            const { meter, instruments } = this.getOrCreateProvider(contextIds);
+            if (!(id in instruments)) {
+                let def = this._metricDefs[id];
+                if (def === undefined) {
+                    // Process restart path: definition not yet cached, fetch from storage.
+                    const { metric } = await this._inner.getMetric(id);
+                    def = { type: metric.type, description: metric.description, unit: metric.unit };
+                    this._metricDefs[id] = def;
+                }
+                this.registerInstrument(id, def.type, def.description, def.unit, meter, instruments);
+            }
+            const entry = instruments[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);
                 }
@@ -255,14 +232,16 @@ export class OpenTelemetryTelemetryConnector {
      * 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.
+     * of the MeterProvider. Re-creating a metric with the same id but a different
+     * MetricType is therefore not safe.
      * @param id The id of the metric.
      * @returns A promise that resolves when the metric and its value history have been removed.
      */
     async removeMetric(id) {
-        this._instruments.delete(id);
-        // The inner connector cascades and removes all associated metric values.
+        for (const { instruments } of Object.values(this._providers)) {
+            delete instruments[id];
+        }
+        delete this._metricDefs[id];
         return this._inner.removeMetric(id);
     }
     /**
@@ -287,10 +266,88 @@ export class OpenTelemetryTelemetryConnector {
     async queryValues(id, timeStart, timeEnd, cursor, limit) {
         return this._inner.queryValues(id, timeStart, timeEnd, cursor, limit);
     }
+    /**
+     * Return or create the MeterProvider for the given tenant/node pair.
+     * Providers are keyed by "nodeId/tenantId" and carry OTEL resource attributes
+     * service.namespace=tenantId and service.instance.id=nodeId when those values
+     * are present.
+     * @param contextIds The current execution context IDs.
+     * @returns The cached or newly created provider entry.
+     * @internal
+     */
+    getOrCreateProvider(contextIds) {
+        const node = contextIds[ContextIdKeys.Node];
+        const tenantId = contextIds[ContextIdKeys.Tenant];
+        const key = `${node ?? ""}/${tenantId ?? ""}`;
+        let cached = this._providers[key];
+        if (!Is.undefined(cached)) {
+            return cached;
+        }
+        const readers = this.createReaders();
+        const resourcePrefix = "service";
+        const resourceAttrs = {};
+        if (Is.stringValue(node)) {
+            resourceAttrs[`${resourcePrefix}.instance.id`] = node;
+        }
+        if (Is.stringValue(tenantId)) {
+            resourceAttrs[`${resourcePrefix}.namespace`] = tenantId;
+        }
+        const resource = Object.keys(resourceAttrs).length > 0 ? resourceFromAttributes(resourceAttrs) : undefined;
+        const meterProvider = new MeterProvider({ readers, resource });
+        const meter = meterProvider.getMeter(this._config.meterName ?? "twin-telemetry", this._config.meterVersion ?? "1.0.0");
+        cached = { meterProvider, meter, instruments: {} };
+        this._providers[key] = cached;
+        return cached;
+    }
+    /**
+     * Instantiate fresh MetricReader instances from the connector config.
+     * Called each time a new MeterProvider is created for a tenant/node pair.
+     * @returns The list of reader instances.
+     * @internal
+     */
+    createReaders() {
+        const readers = [];
+        for (const [, config] of Object.entries(this._config.readers ?? {})) {
+            if (config.type === OpenTelemetryReaderTypes.Prometheus) {
+                readers.push(new PrometheusExporter({
+                    port: config.port,
+                    endpoint: config.endpoint,
+                    preventServerStart: !(config.startServer ?? true),
+                    prefix: config.prefix
+                }));
+            }
+        }
+        return readers;
+    }
+    /**
+     * Register an OTEL instrument on a provider's instruments map if not already present.
+     * @param id The metric id.
+     * @param type The metric type.
+     * @param description The metric description.
+     * @param unit The metric unit.
+     * @param meter The meter to create instruments on.
+     * @param instruments The per-provider instruments map to update.
+     * @internal
+     */
+    registerInstrument(id, type, description, unit, meter, instruments) {
+        if (id in instruments) {
+            return;
+        }
+        const instrumentOptions = { description, unit };
+        let instrument;
+        if (type === MetricType.Counter) {
+            instrument = meter.createCounter(id, instrumentOptions);
+        }
+        else if (type === MetricType.IncDecCounter) {
+            instrument = meter.createUpDownCounter(id, instrumentOptions);
+        }
+        else {
+            instrument = meter.createGauge(id, instrumentOptions);
+        }
+        instruments[id] = { metricType: type, instrument };
+    }
     /**
      * 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

package/dist/es/openTelemetryTelemetryConnector.js.map CHANGED Viewed

	@@ -1 +1 @@
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 { PrometheusExporter } from \"@opentelemetry/exporter-prometheus\";\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\tconfig: {\n\t\t\t\tmutexTimeoutMs: this._config.mutexTimeoutMs\n\t\t\t}\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 A promise that resolves when the MeterProvider is running.\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\treaders.push(\n\t\t\t\t\tnew PrometheusExporter({\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 A promise that resolves when the MeterProvider has shut down.\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 A promise that resolves when the metric has been persisted and the OTEL instrument registered.\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 Get a specific metric value by its id.\n\t * @param id The id of the metric.\n\t * @param valueId The id of the metric value.\n\t * @returns The metric value.\n\t /\n\tpublic async getMetricValue(id: string, valueId: string): Promise<ITelemetryMetricValue> {\n\t\treturn this._inner.getMetricValue(id, valueId);\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 A promise that resolves when the persisted metadata has been updated.\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 A promise that resolves when the metric and its value history have been removed.\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"]}
1	+ {"version":3,"file":"openTelemetryTelemetryConnector.js","sourceRoot":"","sources":["../../src/openTelemetryTelemetryConnector.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AACxE,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,aAAa,EAAqB,MAAM,4BAA4B,CAAC;AAC9E,OAAO,EAAE,aAAa,EAAE,cAAc,EAAoB,MAAM,mBAAmB,CAAC;AACpF,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,gBAAgB,CAAC;AAG7F,OAAO,EAAE,+BAA+B,EAAE,MAAM,8CAA8C,CAAC;AAC/F,OAAO,EAIN,sBAAsB,EACtB,UAAU,EACV,MAAM,4BAA4B,CAAC;AAGpC,OAAO,EAAE,wBAAwB,EAAE,MAAM,sCAAsC,CAAC;AAEhF;;;;GAIG;AACH,MAAM,OAAO,+BAA+B;IAC3C;;OAEG;IACI,MAAM,CAAU,SAAS,GAAW,eAAe,CAAC;IAE3D;;OAEG;IACI,MAAM,CAAU,UAAU,qCAAqD;IAEtF;;;OAGG;IACc,OAAO,CAAyC;IAEjE;;;OAGG;IACc,MAAM,CAAkC;IAEzD;;;OAGG;IACK,QAAQ,CAAU;IAE1B;;;;;OAKG;IACc,UAAU,CAQzB;IAEF;;;;;OAKG;IACc,WAAW,CAE1B;IAEF;;;;OAIG;IACH,YAAY,OAA4D;QACvE,IAAI,CAAC,OAAO,GAAG,OAAO,EAAE,MAAM,IAAI,EAAE,CAAC;QAErC,KAAK,MAAM,CAAC,EAAE,YAAY,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC,EAAE,CAAC;YAC3E,MAAM,CAAC,UAAU,CAChB,+BAA+B,CAAC,UAAU,uBAE1C,YAAY,CAAC,IAAI,EACjB,MAAM,CAAC,MAAM,CAAC,wBAAwB,CAAC,CACvC,CAAC;QACH,CAAC;QAED,IAAI,CAAC,MAAM,GAAG,IAAI,+BAA+B,CAAC;YACjD,oBAAoB,EAAE,OAAO,EAAE,oBAAoB;YACnD,mCAAmC,EAAE,OAAO,EAAE,mCAAmC;YACjF,wCAAwC,EAAE,OAAO,EAAE,wCAAwC;YAC3F,MAAM,EAAE;gBACP,cAAc,EAAE,IAAI,CAAC,OAAO,CAAC,cAAc;aAC3C;SACD,CAAC,CAAC;QACH,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;QACtB,IAAI,CAAC,UAAU,GAAG,EAAE,CAAC;QACrB,IAAI,CAAC,WAAW,GAAG,EAAE,CAAC;IACvB,CAAC;IAED;;;OAGG;IACI,SAAS;QACf,OAAO,+BAA+B,CAAC,UAAU,CAAC;IACnD,CAAC;IAED;;;;;OAKG;IACI,KAAK,CAAC,KAAK,CAAC,wBAAiC;QACnD,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnB,OAAO;QACR,CAAC;QACD,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QAErB,MAAM,WAAW,GAAG,gBAAgB,CAAC,WAAW,CAAoB,wBAAwB,CAAC,CAAC;QAC9F,MAAM,WAAW,EAAE,GAAG,CAAC;YACtB,MAAM,EAAE,+BAA+B,CAAC,UAAU;YAClD,OAAO,EAAE,kBAAkB;YAC3B,KAAK,EAAE,MAAM;YACb,IAAI,EAAE,EAAE,WAAW,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;SACrE,CAAC,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACI,KAAK,CAAC,IAAI,CAAC,wBAAiC;QAClD,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnB,KAAK,MAAM,EAAE,aAAa,EAAE,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;gBAChE,MAAM,aAAa,CAAC,QAAQ,EAAE,CAAC;YAChC,CAAC;YACD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;gBAChD,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;YAC7B,CAAC;YACD,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;YAEtB,MAAM,WAAW,GAAG,gBAAgB,CAAC,WAAW,CAAoB,wBAAwB,CAAC,CAAC;YAC9F,MAAM,WAAW,EAAE,GAAG,CAAC;gBACtB,MAAM,EAAE,+BAA+B,CAAC,UAAU;gBAClD,OAAO,EAAE,kBAAkB;gBAC3B,KAAK,EAAE,MAAM;gBACb,IAAI,EAAE,EAAE;aACR,CAAC,CAAC;QACJ,CAAC;IACF,CAAC;IAED;;;;OAIG;IACI,KAAK,CAAC,YAAY,CAAC,MAAwB;QACjD,IAAI,CAAC;YACJ,MAAM,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;QACxC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACd,sFAAsF;YACtF,2FAA2F;YAC3F,uFAAuF;YACvF,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,GAAG,EAAE,kBAAkB,CAAC,UAAU,CAAC,EAAE,CAAC;gBAChE,MAAM,GAAG,CAAC;YACX,CAAC;QACF,CAAC;QAED,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG;YAC7B,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,WAAW,EAAE,MAAM,CAAC,WAAW;YAC/B,IAAI,EAAE,MAAM,CAAC,IAAI;SACjB,CAAC;QAEF,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnB,MAAM,UAAU,GAAG,CAAC,MAAM,cAAc,CAAC,aAAa,EAAE,CAAC,IAAI,EAAE,CAAC;YAChE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC,mBAAmB,CAAC,UAAU,CAAC,CAAC;YACpE,IAAI,CAAC,kBAAkB,CACtB,MAAM,CAAC,EAAE,EACT,MAAM,CAAC,IAAI,EACX,MAAM,CAAC,WAAW,EAClB,MAAM,CAAC,IAAI,EACX,KAAK,EACL,WAAW,CACX,CAAC;QACH,CAAC;IACF,CAAC;IAED;;;;OAIG;IACI,KAAK,CAAC,SAAS,CAAC,EAAU;QAIhC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;QAC/C,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;QAC1D,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC;IACzC,CAAC;IAED;;;;;OAKG;IACI,KAAK,CAAC,cAAc,CAAC,EAAU,EAAE,OAAe;QACtD,OAAO,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;IAChD,CAAC;IAED;;;;;;OAMG;IACI,KAAK,CAAC,YAAY,CAAC,MAAsC;QAC/D,OAAO,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;IACzC,CAAC;IAED;;;;;;;;OAQG;IACI,KAAK,CAAC,cAAc,CAC1B,EAAU,EACV,KAAsC,EACtC,UAAuC;QAEvC,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,EAAE,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC;QAExE,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnB,MAAM,UAAU,GAAG,CAAC,MAAM,cAAc,CAAC,aAAa,EAAE,CAAC,IAAI,EAAE,CAAC;YAChE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC,mBAAmB,CAAC,UAAU,CAAC,CAAC;YAEpE,IAAI,CAAC,CAAC,EAAE,IAAI,WAAW,CAAC,EAAE,CAAC;gBAC1B,IAAI,GAAG,GAAG,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;gBAC/B,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;oBACvB,uEAAuE;oBACvE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;oBACnD,GAAG,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,WAAW,EAAE,MAAM,CAAC,WAAW,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC;oBAChF,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC;gBAC5B,CAAC;gBACD,IAAI,CAAC,kBAAkB,CAAC,EAAE,EAAE,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,WAAW,EAAE,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC;YACtF,CAAC;YAED,MAAM,KAAK,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC;YAC9B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACzB,MAAM,UAAU,GAAG,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC;gBACjD,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,GAAG,KAAK,CAAC;gBAEzC,IAAI,UAAU,KAAK,UAAU,CAAC,OAAO,EAAE,CAAC;oBACtC,UAAsB,CAAC,GAAG,CAC1B,KAAK,KAAK,sBAAsB,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAE,KAAgB,EAClE,UAAU,CACV,CAAC;gBACH,CAAC;qBAAM,IAAI,UAAU,KAAK,UAAU,CAAC,aAAa,EAAE,CAAC;oBACpD,IAAI,KAAa,CAAC;oBAClB,IAAI,KAAK,KAAK,sBAAsB,CAAC,SAAS,EAAE,CAAC;wBAChD,KAAK,GAAG,CAAC,CAAC;oBACX,CAAC;yBAAM,IAAI,KAAK,KAAK,sBAAsB,CAAC,SAAS,EAAE,CAAC;wBACvD,KAAK,GAAG,CAAC,CAAC,CAAC;oBACZ,CAAC;yBAAM,CAAC;wBACP,KAAK,GAAG,KAAK,CAAC;oBACf,CAAC;oBACA,UAA4B,CAAC,GAAG,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;gBACtD,CAAC;qBAAM,CAAC;oBACN,UAAoB,CAAC,MAAM,CAAC,KAAe,EAAE,UAAU,CAAC,CAAC;gBAC3D,CAAC;YACF,CAAC;QACF,CAAC;QAED,OAAO,OAAO,CAAC;IAChB,CAAC;IAED;;;;;;;;OAQG;IACI,KAAK,CAAC,YAAY,CAAC,EAAU;QACnC,KAAK,MAAM,EAAE,WAAW,EAAE,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;YAC9D,OAAO,WAAW,CAAC,EAAE,CAAC,CAAC;QACxB,CAAC;QACD,OAAO,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;QAC5B,OAAO,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC;IACrC,CAAC;IAED;;;;;;OAMG;IACI,KAAK,CAAC,KAAK,CACjB,IAAiB,EACjB,MAAe,EACf,KAAc;QAKd,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;IAC/C,CAAC;IAED;;;;;;;;OAQG;IACI,KAAK,CAAC,WAAW,CACvB,EAAU,EACV,SAAkB,EAClB,OAAgB,EAChB,MAAe,EACf,KAAc;QAMd,OAAO,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;IACvE,CAAC;IAED;;;;;;;;OAQG;IACK,mBAAmB,CAAC,UAAuB;QAOlD,MAAM,IAAI,GAAG,UAAU,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;QAC5C,MAAM,QAAQ,GAAG,UAAU,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;QAElD,MAAM,GAAG,GAAG,GAAG,IAAI,IAAI,EAAE,IAAI,QAAQ,IAAI,EAAE,EAAE,CAAC;QAE9C,IAAI,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,CAAC,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3B,OAAO,MAAM,CAAC;QACf,CAAC;QAED,MAAM,OAAO,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;QACrC,MAAM,cAAc,GAAG,SAAS,CAAC;QACjC,MAAM,aAAa,GAA6B,EAAE,CAAC;QACnD,IAAI,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC;YAC1B,aAAa,CAAC,GAAG,cAAc,cAAc,CAAC,GAAG,IAAI,CAAC;QACvD,CAAC;QACD,IAAI,EAAE,CAAC,WAAW,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC9B,aAAa,CAAC,GAAG,cAAc,YAAY,CAAC,GAAG,QAAQ,CAAC;QACzD,CAAC;QACD,MAAM,QAAQ,GACb,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,sBAAsB,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAC3F,MAAM,aAAa,GAAG,IAAI,aAAa,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAC;QAC/D,MAAM,KAAK,GAAG,aAAa,CAAC,QAAQ,CACnC,IAAI,CAAC,OAAO,CAAC,SAAS,IAAI,gBAAgB,EAC1C,IAAI,CAAC,OAAO,CAAC,YAAY,IAAI,OAAO,CACpC,CAAC;QACF,MAAM,GAAG,EAAE,aAAa,EAAE,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC;QACnD,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC;QAE9B,OAAO,MAAM,CAAC;IACf,CAAC;IAED;;;;;OAKG;IACK,aAAa;QACpB,MAAM,OAAO,GAAmB,EAAE,CAAC;QACnC,KAAK,MAAM,CAAC,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC,EAAE,CAAC;YACrE,IAAI,MAAM,CAAC,IAAI,KAAK,wBAAwB,CAAC,UAAU,EAAE,CAAC;gBACzD,OAAO,CAAC,IAAI,CACX,IAAI,kBAAkB,CAAC;oBACtB,IAAI,EAAE,MAAM,CAAC,IAAI;oBACjB,QAAQ,EAAE,MAAM,CAAC,QAAQ;oBACzB,kBAAkB,EAAE,CAAC,CAAC,MAAM,CAAC,WAAW,IAAI,IAAI,CAAC;oBACjD,MAAM,EAAE,MAAM,CAAC,MAAM;iBACrB,CAAC,CACF,CAAC;YACH,CAAC;QACF,CAAC;QACD,OAAO,OAAO,CAAC;IAChB,CAAC;IAED;;;;;;;;;OASG;IACK,kBAAkB,CACzB,EAAU,EACV,IAAgB,EAChB,WAA+B,EAC/B,IAAwB,EACxB,KAAY,EACZ,WAEC;QAED,IAAI,EAAE,IAAI,WAAW,EAAE,CAAC;YACvB,OAAO;QACR,CAAC;QACD,MAAM,iBAAiB,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;QAChD,IAAI,UAA2C,CAAC;QAChD,IAAI,IAAI,KAAK,UAAU,CAAC,OAAO,EAAE,CAAC;YACjC,UAAU,GAAG,KAAK,CAAC,aAAa,CAAC,EAAE,EAAE,iBAAiB,CAAC,CAAC;QACzD,CAAC;aAAM,IAAI,IAAI,KAAK,UAAU,CAAC,aAAa,EAAE,CAAC;YAC9C,UAAU,GAAG,KAAK,CAAC,mBAAmB,CAAC,EAAE,EAAE,iBAAiB,CAAC,CAAC;QAC/D,CAAC;aAAM,CAAC;YACP,UAAU,GAAG,KAAK,CAAC,WAAW,CAAC,EAAE,EAAE,iBAAiB,CAAC,CAAC;QACvD,CAAC;QACD,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;IACpD,CAAC;IAED;;;;;OAKG;IACK,YAAY,CAAC,UAAuC;QAC3D,IAAI,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC;YAC1B,OAAO,EAAE,CAAC;QACX,CAAC;QACD,MAAM,KAAK,GAAe,EAAE,CAAC;QAC7B,KAAK,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;YACrD,IAAI,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;gBACzD,KAAK,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;YAClB,CAAC;iBAAM,IAAI,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC/B,IACC,CAAC,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;oBAC9D,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,KAAK,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,EAC3C,CAAC;oBACF,KAAK,CAAC,GAAG,CAAC,GAAG,GAAsC,CAAC;gBACrD,CAAC;YACF,CAAC;QACF,CAAC;QACD,OAAO,KAAK,CAAC;IACd,CAAC","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { Attributes, Counter, Gauge, Meter, UpDownCounter } from \"@opentelemetry/api\";\nimport { PrometheusExporter } from \"@opentelemetry/exporter-prometheus\";\nimport { resourceFromAttributes } from \"@opentelemetry/resources\";\nimport { MeterProvider, type MetricReader } from \"@opentelemetry/sdk-metrics\";\nimport { ContextIdKeys, ContextIdStore, type IContextIds } from \"@twin.org/context\";\nimport { AlreadyExistsError, BaseError, ComponentFactory, Guards, 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\";\nimport { OpenTelemetryReaderTypes } from \"./models/openTelemetryReaderTypes.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 /\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 provider creation can initialise readers and meter identity.\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 * @internal\n\t /\n\tprivate readonly _inner: EntityStorageTelemetryConnector;\n\n\t/\n\t Whether start() has been called. Drives OTEL forwarding on/off.\n\t * @internal\n\t /\n\tprivate _started: boolean;\n\n\t/\n\t Cache of MeterProvider+Meter+instruments keyed by \"nodeId/tenantId\".\n\t * Providers are created on demand when the first metric measurement arrives\n\t * for a given tenant/node pair.\n\t * @internal\n\t /\n\tprivate readonly _providers: {\n\t\t[key: string]: {\n\t\t\tmeterProvider: MeterProvider;\n\t\t\tmeter: Meter;\n\t\t\tinstruments: {\n\t\t\t\t[id: string]: { metricType: MetricType; instrument: Counter \| UpDownCounter \| Gauge };\n\t\t\t};\n\t\t};\n\t};\n\n\t/\n\t Metric definition cache keyed by metric id, populated in createMetric and on first\n\t * addMetricValue after a process restart. Used to register instruments on new providers\n\t * without re-querying entity storage on every call.\n\t * @internal\n\t /\n\tprivate readonly _metricDefs: {\n\t\t[id: string]: { type: MetricType; description?: string; unit?: string };\n\t};\n\n\t/\n\t Create a new instance of OpenTelemetryTelemetryConnector.\n\t * @param options The options for the connector.\n\t * @throws GuardError When a reader config specifies an unsupported type.\n\t /\n\tconstructor(options?: IOpenTelemetryTelemetryConnectorConstructorOptions) {\n\t\tthis._config = options?.config ?? {};\n\n\t\tfor (const [, readerConfig] of Object.entries(this._config.readers ?? {})) {\n\t\t\tGuards.arrayOneOf(\n\t\t\t\tOpenTelemetryTelemetryConnector.CLASS_NAME,\n\t\t\t\tnameof(readerConfig.type),\n\t\t\t\treaderConfig.type,\n\t\t\t\tObject.values(OpenTelemetryReaderTypes)\n\t\t\t);\n\t\t}\n\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\tconfig: {\n\t\t\t\tmutexTimeoutMs: this._config.mutexTimeoutMs\n\t\t\t}\n\t\t});\n\t\tthis._started = false;\n\t\tthis._providers = {};\n\t\tthis._metricDefs = {};\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 Enable OTEL forwarding. Subsequent calls to createMetric and addMetricValue will\n\t * create per-tenant/node MeterProviders on demand.\n\t * @param nodeLoggingComponentType The node logging component type.\n\t * @returns A promise that resolves when OTEL forwarding is enabled.\n\t /\n\tpublic async start(nodeLoggingComponentType?: string): Promise<void> {\n\t\tif (this._started) {\n\t\t\treturn;\n\t\t}\n\t\tthis._started = true;\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 all cached MeterProviders and disable OTEL forwarding.\n\t * @param nodeLoggingComponentType The node logging component type.\n\t * @returns A promise that resolves when all MeterProviders have shut down.\n\t /\n\tpublic async stop(nodeLoggingComponentType?: string): Promise<void> {\n\t\tif (this._started) {\n\t\t\tfor (const { meterProvider } of Object.values(this._providers)) {\n\t\t\t\tawait meterProvider.shutdown();\n\t\t\t}\n\t\t\tfor (const key of Object.keys(this._providers)) {\n\t\t\t\tdelete this._providers[key];\n\t\t\t}\n\t\t\tthis._started = false;\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 * @param metric The metric details.\n\t * @returns A promise that resolves when the metric has been persisted.\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\tthis._metricDefs[metric.id] = {\n\t\t\ttype: metric.type,\n\t\t\tdescription: metric.description,\n\t\t\tunit: metric.unit\n\t\t};\n\n\t\tif (this._started) {\n\t\t\tconst contextIds = (await ContextIdStore.getContextIds()) ?? {};\n\t\t\tconst { meter, instruments } = this.getOrCreateProvider(contextIds);\n\t\t\tthis.registerInstrument(\n\t\t\t\tmetric.id,\n\t\t\t\tmetric.type,\n\t\t\t\tmetric.description,\n\t\t\t\tmetric.unit,\n\t\t\t\tmeter,\n\t\t\t\tinstruments\n\t\t\t);\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\t\tconst value = result.value ?? { id: \"\", ts: 0, value: 0 };\n\t\treturn { metric: result.metric, value };\n\t}\n\n\t/\n\t Get a specific metric value by its id.\n\t * @param id The id of the metric.\n\t * @param valueId The id of the metric value.\n\t * @returns The metric value.\n\t /\n\tpublic async getMetricValue(id: string, valueId: string): Promise<ITelemetryMetricValue> {\n\t\treturn this._inner.getMetricValue(id, valueId);\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 only.\n\t * @param metric The metric details (type cannot be changed).\n\t * @returns A promise that resolves when the persisted metadata has been updated.\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 * The current tenant and node IDs are read from `ContextIdStore` and used to\n\t * select (or create) the matching per-tenant/node `MeterProvider`.\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\tconst valueId = await this._inner.addMetricValue(id, value, customData);\n\n\t\tif (this._started) {\n\t\t\tconst contextIds = (await ContextIdStore.getContextIds()) ?? {};\n\t\t\tconst { meter, instruments } = this.getOrCreateProvider(contextIds);\n\n\t\t\tif (!(id in instruments)) {\n\t\t\t\tlet def = this._metricDefs[id];\n\t\t\t\tif (def === undefined) {\n\t\t\t\t\t// Process restart path: definition not yet cached, fetch from storage.\n\t\t\t\t\tconst { metric } = await this._inner.getMetric(id);\n\t\t\t\t\tdef = { type: metric.type, description: metric.description, unit: metric.unit };\n\t\t\t\t\tthis._metricDefs[id] = def;\n\t\t\t\t}\n\t\t\t\tthis.registerInstrument(id, def.type, def.description, def.unit, meter, instruments);\n\t\t\t}\n\n\t\t\tconst entry = instruments[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\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 MeterProvider. Re-creating a metric with the same id but a different\n\t * MetricType is therefore not safe.\n\t * @param id The id of the metric.\n\t * @returns A promise that resolves when the metric and its value history have been removed.\n\t /\n\tpublic async removeMetric(id: string): Promise<void> {\n\t\tfor (const { instruments } of Object.values(this._providers)) {\n\t\t\tdelete instruments[id];\n\t\t}\n\t\tdelete this._metricDefs[id];\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 Return or create the MeterProvider for the given tenant/node pair.\n\t * Providers are keyed by \"nodeId/tenantId\" and carry OTEL resource attributes\n\t * service.namespace=tenantId and service.instance.id=nodeId when those values\n\t * are present.\n\t * @param contextIds The current execution context IDs.\n\t * @returns The cached or newly created provider entry.\n\t * @internal\n\t /\n\tprivate getOrCreateProvider(contextIds: IContextIds): {\n\t\tmeterProvider: MeterProvider;\n\t\tmeter: Meter;\n\t\tinstruments: {\n\t\t\t[id: string]: { metricType: MetricType; instrument: Counter \| UpDownCounter \| Gauge };\n\t\t};\n\t} {\n\t\tconst node = contextIds[ContextIdKeys.Node];\n\t\tconst tenantId = contextIds[ContextIdKeys.Tenant];\n\n\t\tconst key = `${node ?? \"\"}/${tenantId ?? \"\"}`;\n\n\t\tlet cached = this._providers[key];\n\t\tif (!Is.undefined(cached)) {\n\t\t\treturn cached;\n\t\t}\n\n\t\tconst readers = this.createReaders();\n\t\tconst resourcePrefix = \"service\";\n\t\tconst resourceAttrs: { [id: string]: string } = {};\n\t\tif (Is.stringValue(node)) {\n\t\t\tresourceAttrs[`${resourcePrefix}.instance.id`] = node;\n\t\t}\n\t\tif (Is.stringValue(tenantId)) {\n\t\t\tresourceAttrs[`${resourcePrefix}.namespace`] = tenantId;\n\t\t}\n\t\tconst resource =\n\t\t\tObject.keys(resourceAttrs).length > 0 ? resourceFromAttributes(resourceAttrs) : undefined;\n\t\tconst meterProvider = new MeterProvider({ readers, resource });\n\t\tconst meter = meterProvider.getMeter(\n\t\t\tthis._config.meterName ?? \"twin-telemetry\",\n\t\t\tthis._config.meterVersion ?? \"1.0.0\"\n\t\t);\n\t\tcached = { meterProvider, meter, instruments: {} };\n\t\tthis._providers[key] = cached;\n\n\t\treturn cached;\n\t}\n\n\t/\n\t Instantiate fresh MetricReader instances from the connector config.\n\t * Called each time a new MeterProvider is created for a tenant/node pair.\n\t * @returns The list of reader instances.\n\t * @internal\n\t /\n\tprivate createReaders(): MetricReader[] {\n\t\tconst readers: MetricReader[] = [];\n\t\tfor (const [, config] of Object.entries(this._config.readers ?? {})) {\n\t\t\tif (config.type === OpenTelemetryReaderTypes.Prometheus) {\n\t\t\t\treaders.push(\n\t\t\t\t\tnew PrometheusExporter({\n\t\t\t\t\t\tport: config.port,\n\t\t\t\t\t\tendpoint: config.endpoint,\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}\n\t\t}\n\t\treturn readers;\n\t}\n\n\t/\n\t Register an OTEL instrument on a provider's instruments map if not already present.\n\t * @param id The metric id.\n\t * @param type The metric type.\n\t * @param description The metric description.\n\t * @param unit The metric unit.\n\t * @param meter The meter to create instruments on.\n\t * @param instruments The per-provider instruments map to update.\n\t * @internal\n\t /\n\tprivate registerInstrument(\n\t\tid: string,\n\t\ttype: MetricType,\n\t\tdescription: string \| undefined,\n\t\tunit: string \| undefined,\n\t\tmeter: Meter,\n\t\tinstruments: {\n\t\t\t[id: string]: { metricType: MetricType; instrument: Counter \| UpDownCounter \| Gauge };\n\t\t}\n\t): void {\n\t\tif (id in instruments) {\n\t\t\treturn;\n\t\t}\n\t\tconst instrumentOptions = { description, unit };\n\t\tlet instrument: Counter \| UpDownCounter \| Gauge;\n\t\tif (type === MetricType.Counter) {\n\t\t\tinstrument = meter.createCounter(id, instrumentOptions);\n\t\t} else if (type === MetricType.IncDecCounter) {\n\t\t\tinstrument = meter.createUpDownCounter(id, instrumentOptions);\n\t\t} else {\n\t\t\tinstrument = meter.createGauge(id, instrumentOptions);\n\t\t}\n\t\tinstruments[id] = { metricType: type, instrument };\n\t}\n\n\t/\n\t Convert customData to OTEL-compatible Attributes.\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/openTelemetryTelemetryConnector.d.ts CHANGED Viewed

@@ -4,9 +4,6 @@ import type { IOpenTelemetryTelemetryConnectorConstructorOptions } from "./model
  * 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 {
     /**
@@ -19,9 +16,8 @@ export declare class OpenTelemetryTelemetryConnector implements ITelemetryConnec
     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.
+     * @throws GuardError When a reader config specifies an unsupported type.
      */
     constructor(options?: IOpenTelemetryTelemetryConnectorConstructorOptions);
     /**
@@ -30,24 +26,22 @@ export declare class OpenTelemetryTelemetryConnector implements ITelemetryConnec
      */
     className(): string;
     /**
-     * Initialise the MeterProvider and configured exporters.
+     * Enable OTEL forwarding. Subsequent calls to createMetric and addMetricValue will
+     * create per-tenant/node MeterProviders on demand.
      * @param nodeLoggingComponentType The node logging component type.
-     * @returns A promise that resolves when the MeterProvider is running.
+     * @returns A promise that resolves when OTEL forwarding is enabled.
      */
     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.
+     * Shut down all cached MeterProviders and disable OTEL forwarding.
      * @param nodeLoggingComponentType The node logging component type.
-     * @returns A promise that resolves when the MeterProvider has shut down.
+     * @returns A promise that resolves when all MeterProviders have shut down.
      */
     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 A promise that resolves when the metric has been persisted and the OTEL instrument registered.
+     * @returns A promise that resolves when the metric has been persisted.
      */
     createMetric(metric: ITelemetryMetric): Promise<void>;
     /**
@@ -69,20 +63,15 @@ export declare class OpenTelemetryTelemetryConnector implements ITelemetryConnec
     /**
      * 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.).
+     * This method updates the persisted metadata mirror only.
      * @param metric The metric details (type cannot be changed).
      * @returns A promise that resolves when the persisted metadata has been updated.
      */
     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.
+     * 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.
@@ -95,8 +84,8 @@ export declare class OpenTelemetryTelemetryConnector implements ITelemetryConnec
      * 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.
+     * of the MeterProvider. Re-creating a metric with the same id but a different
+     * MetricType is therefore not safe.
      * @param id The id of the metric.
      * @returns A promise that resolves when the metric and its value history have been removed.
      */

package/docs/changelog.md CHANGED Viewed

@@ -1,5 +1,20 @@
 # Changelog
+## [0.9.2-next.2](https://github.com/iotaledger/twin-telemetry/compare/telemetry-connector-opentelemetry-v0.9.2-next.1...telemetry-connector-opentelemetry-v0.9.2-next.2) (2026-08-03)
+### Bug Fixes
+* resource partitioning ([#77](https://github.com/iotaledger/twin-telemetry/issues/77)) ([bae3093](https://github.com/iotaledger/twin-telemetry/commit/bae3093d285b379f96dd95c9bbed59bb0895a2cd))
+### Dependencies
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/telemetry-connector-entity-storage bumped from 0.9.2-next.1 to 0.9.2-next.2
+    * @twin.org/telemetry-models bumped from 0.9.2-next.1 to 0.9.2-next.2
 ## [0.9.2-next.1](https://github.com/iotaledger/twin-telemetry/compare/telemetry-connector-opentelemetry-v0.9.2-next.0...telemetry-connector-opentelemetry-v0.9.2-next.1) (2026-07-30)

package/docs/reference/classes/OpenTelemetryTelemetryConnector.md CHANGED Viewed

@@ -3,9 +3,6 @@
 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.
 ## Implements
@@ -18,8 +15,6 @@ the MeterProvider is running.
 > **new OpenTelemetryTelemetryConnector**(`options?`): `OpenTelemetryTelemetryConnector`
 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).
 #### Parameters
@@ -33,6 +28,10 @@ The options for the connector.
 `OpenTelemetryTelemetryConnector`
+#### Throws
+GuardError When a reader config specifies an unsupported type.
 ## Properties
 ### NAMESPACE {#namespace}
@@ -73,7 +72,8 @@ The class name of the component.
 > **start**(`nodeLoggingComponentType?`): `Promise`\<`void`\>
-Initialise the MeterProvider and configured exporters.
+Enable OTEL forwarding. Subsequent calls to createMetric and addMetricValue will
+create per-tenant/node MeterProviders on demand.
 #### Parameters
@@ -87,7 +87,7 @@ The node logging component type.
 `Promise`\<`void`\>
-A promise that resolves when the MeterProvider is running.
+A promise that resolves when OTEL forwarding is enabled.
 #### Implementation of
@@ -99,8 +99,7 @@ A promise that resolves when the MeterProvider is running.
 > **stop**(`nodeLoggingComponentType?`): `Promise`\<`void`\>
-Shut down the MeterProvider and release resources.
-Calling stop() on a connector that has not been started is a no-op.
+Shut down all cached MeterProviders and disable OTEL forwarding.
 #### Parameters
@@ -114,7 +113,7 @@ The node logging component type.
 `Promise`\<`void`\>
-A promise that resolves when the MeterProvider has shut down.
+A promise that resolves when all MeterProviders have shut down.
 #### Implementation of
@@ -127,8 +126,6 @@ A promise that resolves when the MeterProvider has shut down.
 > **createMetric**(`metric`): `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.
 #### Parameters
@@ -142,7 +139,7 @@ The metric details.
 `Promise`\<`void`\>
-A promise that resolves when the metric has been persisted and the OTEL instrument registered.
+A promise that resolves when the metric has been persisted.
 #### Implementation of
@@ -214,9 +211,7 @@ The 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.).
+This method updates the persisted metadata mirror only.
 #### Parameters
@@ -243,11 +238,8 @@ A promise that resolves when the persisted metadata has been updated.
 > **addMetricValue**(`id`, `value`, `customData?`): `Promise`\<`string`\>
 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.
+The current tenant and node IDs are read from `ContextIdStore` and used to
+select (or create) the matching per-tenant/node `MeterProvider`.
 #### Parameters
@@ -286,8 +278,8 @@ The id of the new metric value entry.
 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.
+of the MeterProvider. Re-creating a metric with the same id but a different
+MetricType is therefore not safe.
 #### Parameters

package/locales/en.json CHANGED Viewed

@@ -1,9 +1,4 @@
 {
-	"error": {
-		"openTelemetryTelemetryConnector": {
-			"unknownReaderType": "The reader type \"{type}\" is not supported, valid values are: prometheus"
-		}
-	},
 	"info": {
 		"openTelemetryTelemetryConnector": {
 			"connectorStarted": "The connector was started with \"{readerCount}\" metric reader(s)",

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
 	"name": "@twin.org/telemetry-connector-opentelemetry",
-	"version": "0.9.2-next.1",
+	"version": "0.9.2-next.2",
 	"description": "OpenTelemetry connector for pushing telemetry metrics to OTEL-compatible backends.",
 	"repository": {
 		"type": "git",
@@ -16,13 +16,15 @@
 	"dependencies": {
 		"@opentelemetry/api": "1.9.1",
 		"@opentelemetry/exporter-prometheus": "0.221.0",
+		"@opentelemetry/resources": "2.10.0",
 		"@opentelemetry/sdk-metrics": "2.10.0",
+		"@twin.org/context": "next",
 		"@twin.org/core": "next",
 		"@twin.org/entity-storage-models": "next",
 		"@twin.org/logging-models": "next",
 		"@twin.org/nameof": "next",
-		"@twin.org/telemetry-connector-entity-storage": "0.9.2-next.1",
-		"@twin.org/telemetry-models": "0.9.2-next.1"
+		"@twin.org/telemetry-connector-entity-storage": "0.9.2-next.2",
+		"@twin.org/telemetry-models": "0.9.2-next.2"
 	},
 	"main": "./dist/es/index.js",
 	"types": "./dist/types/index.d.ts",