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

package/docs/reference/classes/OpenTelemetryTelemetryConnector.md

@@ -0,0 +1,364 @@
+# 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.
+
+#### 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` \| `MetricCounterOperation`
+
+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,20 @@
+# @twin.org/telemetry-connector-opentelemetry
+
+## Classes
+
+- [OpenTelemetryTelemetryConnector](classes/OpenTelemetryTelemetryConnector.md)
+
+## Interfaces
+
+- [IOpenTelemetryPrometheusReaderConfig](interfaces/IOpenTelemetryPrometheusReaderConfig.md)
+- [IOpenTelemetryTelemetryConnectorConfig](interfaces/IOpenTelemetryTelemetryConnectorConfig.md)
+- [IOpenTelemetryTelemetryConnectorConstructorOptions](interfaces/IOpenTelemetryTelemetryConnectorConstructorOptions.md)
+
+## Type Aliases
+
+- [IOpenTelemetryReaderConfig](type-aliases/IOpenTelemetryReaderConfig.md)
+- [OpenTelemetryReaderTypes](type-aliases/OpenTelemetryReaderTypes.md)
+
+## Variables
+
+- [OpenTelemetryReaderTypes](variables/OpenTelemetryReaderTypes.md)

package/docs/reference/interfaces/IOpenTelemetryPrometheusReaderConfig.md

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

package/docs/reference/interfaces/IOpenTelemetryTelemetryConnectorConfig.md

@@ -0,0 +1,45 @@
+# Interface: IOpenTelemetryTelemetryConnectorConfig
+
+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
+1.0.0
+```
+
+***
+
+### 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).
+
+#### Index Signature
+
+\[`id`: `string`\]: [`IOpenTelemetryPrometheusReaderConfig`](IOpenTelemetryPrometheusReaderConfig.md)

package/docs/reference/interfaces/IOpenTelemetryTelemetryConnectorConstructorOptions.md

@@ -0,0 +1,50 @@
+# Interface: IOpenTelemetryTelemetryConnectorConstructorOptions
+
+The options for the OpenTelemetry telemetry connector constructor.
+
+## Properties
+
+### 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
+```
+
+***
+
+### config? {#config}
+
+> `optional` **config?**: [`IOpenTelemetryTelemetryConnectorConfig`](IOpenTelemetryTelemetryConnectorConfig.md)
+
+The config for the telemetry connector.

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/docs/reference/type-aliases/OpenTelemetryReaderTypes.md

@@ -0,0 +1,5 @@
+# Type Alias: OpenTelemetryReaderTypes
+
+> **OpenTelemetryReaderTypes** = *typeof* [`OpenTelemetryReaderTypes`](../variables/OpenTelemetryReaderTypes.md)\[keyof *typeof* [`OpenTelemetryReaderTypes`](../variables/OpenTelemetryReaderTypes.md)\]
+
+The types of readers.

package/docs/reference/variables/OpenTelemetryReaderTypes.md

@@ -0,0 +1,13 @@
+# Variable: OpenTelemetryReaderTypes
+
+> `const` **OpenTelemetryReaderTypes**: `object`
+
+The types of readers.
+
+## Type Declaration
+
+### Prometheus {#prometheus}
+
+> `readonly` **Prometheus**: `"prometheus"` = `"prometheus"`
+
+Prometheus.

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"
+		}
+	}
+}

package/package.json

@@ -0,0 +1,70 @@
+{
+	"name": "@twin.org/telemetry-connector-opentelemetry",
+	"version": "0.0.3-next.10",
+	"description": "OpenTelemetry connector for pushing telemetry metrics to OTEL-compatible backends.",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/iotaledger/telemetry.git",
+		"directory": "packages/telemetry-connector-opentelemetry"
+	},
+	"author": "adrian.sanchez.sequeira@iota.org",
+	"license": "Apache-2.0",
+	"type": "module",
+	"engines": {
+		"node": ">=20.0.0"
+	},
+	"dependencies": {
+		"@opentelemetry/api": "1.9.1",
+		"@opentelemetry/sdk-metrics": "2.7.1",
+		"@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.0.3-next.10",
+		"@twin.org/telemetry-models": "0.0.3-next.10"
+	},
+	"peerDependencies": {
+		"@opentelemetry/exporter-prometheus": ">=0.200.0"
+	},
+	"peerDependenciesMeta": {
+		"@opentelemetry/exporter-prometheus": {
+			"optional": true
+		}
+	},
+	"main": "./dist/es/index.js",
+	"types": "./dist/types/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/types/index.d.ts",
+			"import": "./dist/es/index.js",
+			"default": "./dist/es/index.js"
+		},
+		"./locales/*.json": "./locales/*.json"
+	},
+	"files": [
+		"dist/es",
+		"dist/types",
+		"locales",
+		"docs"
+	],
+	"keywords": [
+		"twin",
+		"trade",
+		"iota",
+		"framework",
+		"blockchain",
+		"telemetry",
+		"opentelemetry",
+		"otel",
+		"metrics",
+		"grafana",
+		"prometheus",
+		"connector",
+		"adapter",
+		"integration"
+	],
+	"bugs": {
+		"url": "git+https://github.com/iotaledger/telemetry/issues"
+	},
+	"homepage": "https://twindev.org"
+}