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

package/docs/examples.md

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

package/docs/reference/classes/OpenTelemetryTelemetryConnector.md

@@ -0,0 +1,365 @@
+# Class: OpenTelemetryTelemetryConnector
+
+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
+
+- `ITelemetryConnector`
+
+## Constructors
+
+### Constructor
+
+> **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
+
+##### options?
+
+[`IOpenTelemetryTelemetryConnectorConstructorOptions`](../interfaces/IOpenTelemetryTelemetryConnectorConstructorOptions.md)
+
+The options for the connector.
+
+#### Returns
+
+`OpenTelemetryTelemetryConnector`
+
+## Properties
+
+### NAMESPACE {#namespace}
+
+> `readonly` `static` **NAMESPACE**: `string` = `"opentelemetry"`
+
+The namespace supported by the telemetry connector.
+
+***
+
+### CLASS\_NAME {#class_name}
+
+> `readonly` `static` **CLASS\_NAME**: `string`
+
+Runtime name for the class.
+
+## Methods
+
+### className() {#classname}
+
+> **className**(): `string`
+
+Returns the class name of the component.
+
+#### Returns
+
+`string`
+
+The class name of the component.
+
+#### Implementation of
+
+`ITelemetryConnector.className`
+
+***
+
+### start() {#start}
+
+> **start**(`nodeLoggingComponentType?`): `Promise`\<`void`\>
+
+Initialise the MeterProvider and configured exporters.
+Calling start() on an already-started connector is a no-op.
+
+#### Parameters
+
+##### nodeLoggingComponentType?
+
+`string`
+
+The node logging component type.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing.
+
+#### Implementation of
+
+`ITelemetryConnector.start`
+
+***
+
+### stop() {#stop}
+
+> **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.
+
+#### Parameters
+
+##### nodeLoggingComponentType?
+
+`string`
+
+The node logging component type.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing.
+
+#### Implementation of
+
+`ITelemetryConnector.stop`
+
+***
+
+### createMetric() {#createmetric}
+
+> **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
+
+##### metric
+
+`ITelemetryMetric`
+
+The metric details.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing.
+
+#### Implementation of
+
+`ITelemetryConnector.createMetric`
+
+***
+
+### getMetric() {#getmetric}
+
+> **getMetric**(`id`): `Promise`\<\{ `metric`: `ITelemetryMetric`; `value`: `ITelemetryMetricValue`; \}\>
+
+Get the metric details and its most recent value.
+
+#### Parameters
+
+##### id
+
+`string`
+
+The metric id.
+
+#### Returns
+
+`Promise`\<\{ `metric`: `ITelemetryMetric`; `value`: `ITelemetryMetricValue`; \}\>
+
+The metric details and its most recent value.
+
+#### Implementation of
+
+`ITelemetryConnector.getMetric`
+
+***
+
+### updateMetric() {#updatemetric}
+
+> **updateMetric**(`metric`): `Promise`\<`void`\>
+
+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.).
+
+#### Parameters
+
+##### metric
+
+`Omit`\<`ITelemetryMetric`, `"type"`\>
+
+The metric details (type cannot be changed).
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing.
+
+#### Implementation of
+
+`ITelemetryConnector.updateMetric`
+
+***
+
+### addMetricValue() {#addmetricvalue}
+
+> **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.
+
+#### Parameters
+
+##### id
+
+`string`
+
+The id of the metric.
+
+##### value
+
+`number` \| `"inc"` \| `"dec"`
+
+The value for the operation.
+
+##### customData?
+
+Optional custom data forwarded as OTEL attributes.
+
+#### Returns
+
+`Promise`\<`string`\>
+
+The id of the new metric value entry.
+
+#### Implementation of
+
+`ITelemetryConnector.addMetricValue`
+
+***
+
+### removeMetric() {#removemetric}
+
+> **removeMetric**(`id`): `Promise`\<`void`\>
+
+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.
+
+#### Parameters
+
+##### id
+
+`string`
+
+The id of the metric.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing.
+
+#### Implementation of
+
+`ITelemetryConnector.removeMetric`
+
+***
+
+### query() {#query}
+
+> **query**(`type?`, `cursor?`, `limit?`): `Promise`\<\{ `entities`: `ITelemetryMetric`[]; `cursor?`: `string`; \}\>
+
+Query the registered metrics, optionally filtered by type.
+
+#### Parameters
+
+##### type?
+
+`MetricType`
+
+The type of the metric.
+
+##### cursor?
+
+`string`
+
+The cursor to request the next page.
+
+##### limit?
+
+`number`
+
+Limit the number of entities to return.
+
+#### Returns
+
+`Promise`\<\{ `entities`: `ITelemetryMetric`[]; `cursor?`: `string`; \}\>
+
+The matching metrics and an optional cursor for the next page.
+
+#### Implementation of
+
+`ITelemetryConnector.query`
+
+***
+
+### queryValues() {#queryvalues}
+
+> **queryValues**(`id`, `timeStart?`, `timeEnd?`, `cursor?`, `limit?`): `Promise`\<\{ `metric`: `ITelemetryMetric`; `entities`: `ITelemetryMetricValue`[]; `cursor?`: `string`; \}\>
+
+Query the recorded values for a metric, ordered by most recent first.
+
+#### Parameters
+
+##### id
+
+`string`
+
+The id of the metric.
+
+##### timeStart?
+
+`number`
+
+The inclusive start time (epoch ms).
+
+##### timeEnd?
+
+`number`
+
+The inclusive end time (epoch ms).
+
+##### cursor?
+
+`string`
+
+The cursor returned by the previous call.
+
+##### limit?
+
+`number`
+
+Limit the number of values to return.
+
+#### Returns
+
+`Promise`\<\{ `metric`: `ITelemetryMetric`; `entities`: `ITelemetryMetricValue`[]; `cursor?`: `string`; \}\>
+
+The metric details, matching values, and an optional cursor for the next page.
+
+#### Implementation of
+
+`ITelemetryConnector.queryValues`

package/docs/reference/index.md

@@ -0,0 +1,14 @@
+# @twin.org/telemetry-connector-opentelemetry
+
+## Classes
+
+- [OpenTelemetryTelemetryConnector](classes/OpenTelemetryTelemetryConnector.md)
+
+## Interfaces
+
+- [IOpenTelemetryPrometheusReaderConfig](interfaces/IOpenTelemetryPrometheusReaderConfig.md)
+- [IOpenTelemetryTelemetryConnectorConstructorOptions](interfaces/IOpenTelemetryTelemetryConnectorConstructorOptions.md)
+
+## Type Aliases
+
+- [IOpenTelemetryReaderConfig](type-aliases/IOpenTelemetryReaderConfig.md)

package/docs/reference/interfaces/IOpenTelemetryPrometheusReaderConfig.md

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

package/docs/reference/interfaces/IOpenTelemetryTelemetryConnectorConstructorOptions.md

@@ -0,0 +1,85 @@
+# Interface: IOpenTelemetryTelemetryConnectorConstructorOptions
+
+The options for the OpenTelemetry telemetry connector constructor.
+
+## Properties
+
+### meterName? {#metername}
+
+> `optional` **meterName?**: `string`
+
+The name of the OpenTelemetry meter used to create instruments.
+
+#### Default
+
+```ts
+twin-telemetry
+```
+
+***
+
+### meterVersion? {#meterversion}
+
+> `optional` **meterVersion?**: `string`
+
+The version reported by the OpenTelemetry meter.
+
+#### Default
+
+```ts
+0.0.1
+```
+
+***
+
+### readers? {#readers}
+
+> `optional` **readers?**: `object`
+
+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).
+Example: { "main": { type: "prometheus", port: 9464 } }
+
+#### Index Signature
+
+\[`id`: `string`\]: [`IOpenTelemetryPrometheusReaderConfig`](IOpenTelemetryPrometheusReaderConfig.md)
+
+***
+
+### loggingComponentType? {#loggingcomponenttype}
+
+> `optional` **loggingComponentType?**: `string`
+
+The component type to use for logging inside the connector and the inner
+entity-storage connector. When omitted logging is disabled.
+
+***
+
+### telemetryMetricStorageConnectorType? {#telemetrymetricstorageconnectortype}
+
+> `optional` **telemetryMetricStorageConnectorType?**: `string`
+
+The entity storage connector type to use for storing metric definitions.
+Must be registered in `EntityStorageConnectorFactory` before calling `start()`.
+
+#### Default
+
+```ts
+telemetry-metric
+```
+
+***
+
+### telemetryMetricValueStorageConnectorType? {#telemetrymetricvaluestorageconnectortype}
+
+> `optional` **telemetryMetricValueStorageConnectorType?**: `string`
+
+The entity storage connector type to use for storing metric values.
+Must be registered in `EntityStorageConnectorFactory` before calling `start()`.
+
+#### Default
+
+```ts
+telemetry-metric-value
+```

package/docs/reference/type-aliases/IOpenTelemetryReaderConfig.md

@@ -0,0 +1,6 @@
+# Type Alias: IOpenTelemetryReaderConfig
+
+> **IOpenTelemetryReaderConfig** = [`IOpenTelemetryPrometheusReaderConfig`](../interfaces/IOpenTelemetryPrometheusReaderConfig.md)
+
+Discriminated union of all supported metric-reader configurations.
+Add new members here when additional exporter types are implemented.

package/locales/en.json

@@ -0,0 +1,13 @@
+{
+	"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)",
+			"connectorStopped": "The connector was stopped"
+		}
+	}
+}