@3sixty/telemetry-models 0.0.0-stage → 0.20.0-next.0

package/dist/types/models/api/ITelemetryRemoveMetricRequest.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Remove a telemetry metric and it's values.
+ */
+export interface ITelemetryRemoveMetricRequest {
+    /**
+     * The path parameters.
+     */
+    pathParams: {
+        /**
+         * The id of the metric.
+         */
+        id: string;
+    };
+}

package/dist/types/models/api/ITelemetryUpdateMetricRequest.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Update a telemetry metric.
+ */
+export interface ITelemetryUpdateMetricRequest {
+    /**
+     * The path parameters.
+     */
+    pathParams: {
+        /**
+         * The id of the metric.
+         */
+        id: string;
+    };
+    /**
+     * The data to be used in the update.
+     */
+    body: {
+        /**
+         * The label of the metric.
+         */
+        label: string;
+        /**
+         * The description of the metric.
+         */
+        description?: string;
+        /**
+         * The unit of the metric.
+         */
+        unit?: string;
+    };
+}

package/dist/types/models/api/ITelemetryValuesListRequest.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Get the a list of the telemetry values.
+ */
+export interface ITelemetryValuesListRequest {
+    /**
+     * The path parameters.
+     */
+    pathParams: {
+        /**
+         * The id of the metric.
+         */
+        id: string;
+    };
+    /**
+     * The query parameters.
+     */
+    query?: {
+        /**
+         * The start time of the metrics to retrieve as a timestamp in ms.
+         */
+        timeStart?: string;
+        /**
+         * The end time of the metrics to retrieve as a timestamp in ms.
+         */
+        timeEnd?: string;
+        /**
+         * The optional cursor to get next chunk.
+         */
+        cursor?: string;
+        /**
+         * Limit the number of entities to return.
+         */
+        limit?: string;
+    };
+}

package/dist/types/models/api/ITelemetryValuesListResponse.d.ts

@@ -0,0 +1,24 @@
+import type { ITelemetryMetric } from "../ITelemetryMetric.js";
+import type { ITelemetryMetricValue } from "../ITelemetryMetricValue.js";
+/**
+ * Response for telemetry list request.
+ */
+export interface ITelemetryValuesListResponse {
+    /**
+     * The response payload.
+     */
+    body: {
+        /**
+         * The main metric details.
+         */
+        metric: ITelemetryMetric;
+        /**
+         * The metric values.
+         */
+        entities: ITelemetryMetricValue[];
+        /**
+         * An optional cursor, when defined can be used to call find to get more entities.
+         */
+        cursor?: string;
+    };
+}

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

@@ -0,0 +1,17 @@
+/**
+ * The types of metric value operations for increment decrement counter metrics.
+ */
+export declare const MetricCounterOperation: {
+    /**
+     * Increment Counter.
+     */
+    readonly Increment: "inc";
+    /**
+     * Decrement Counter.
+     */
+    readonly Decrement: "dec";
+};
+/**
+ * The types of metric counter operations.
+ */
+export type MetricCounterOperation = (typeof MetricCounterOperation)[keyof typeof MetricCounterOperation];

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

@@ -0,0 +1,21 @@
+/**
+ * The types of metrics.
+ */
+export declare const MetricType: {
+    /**
+     * Counter.
+     */
+    readonly Counter: 0;
+    /**
+     * Increment Decrement Counter.
+     */
+    readonly IncDecCounter: 1;
+    /**
+     * Gauge.
+     */
+    readonly Gauge: 2;
+};
+/**
+ * The types of metrics.
+ */
+export type MetricType = (typeof MetricType)[keyof typeof MetricType];

package/docs/examples.md

@@ -0,0 +1,142 @@
+# Telemetry Models Examples
+
+These examples demonstrate how to compose telemetry connectors and use the shared telemetry contracts when building integrations.
+
+## MultiTelemetryConnector
+
+```typescript
+import {
+  MetricType,
+  MultiTelemetryConnector,
+  SilentTelemetryConnector,
+  TelemetryConnectorFactory
+} from '@3sixty/telemetry-models';
+
+TelemetryConnectorFactory.register('silent-a', () => new SilentTelemetryConnector());
+TelemetryConnectorFactory.register('silent-b', () => new SilentTelemetryConnector());
+
+const multi = new MultiTelemetryConnector({
+  telemetryConnectorTypes: ['silent-a', 'silent-b']
+});
+
+console.log(multi.className()); // multiTelemetryConnector
+
+await multi.createMetric({
+  id: 'heartbeat-total',
+  label: 'Heartbeat Total',
+  description: 'Number of heartbeats sent',
+  unit: 'events',
+  type: MetricType.Counter
+});
+
+await multi.updateMetric({
+  id: 'heartbeat-total',
+  label: 'Heartbeat Events',
+  description: 'Total heartbeats sent by all nodes',
+  unit: 'events'
+});
+
+const metricValueId = await multi.addMetricValue('heartbeat-total', 'inc', {
+  nodeId: 'node-7'
+});
+
+console.log(metricValueId.length === 0); // true
+```
+
+```typescript
+import {
+  MetricType,
+  MultiTelemetryConnector,
+  SilentTelemetryConnector,
+  TelemetryConnectorFactory
+} from '@3sixty/telemetry-models';
+
+TelemetryConnectorFactory.register('silent-a', () => new SilentTelemetryConnector());
+TelemetryConnectorFactory.register('silent-b', () => new SilentTelemetryConnector());
+
+const multi = new MultiTelemetryConnector({
+  telemetryConnectorTypes: ['silent-a', 'silent-b']
+});
+
+await multi.removeMetric('heartbeat-total');
+
+const counters = await multi.query(MetricType.Counter, undefined, 50);
+console.log(counters.entities.length); // 0
+
+const values = await multi.queryValues(
+  'heartbeat-total',
+  Date.now() - 86_400_000,
+  Date.now(),
+  undefined,
+  100
+);
+console.log(values.entities.length); // 0
+
+const metric = await multi.getMetric('heartbeat-total');
+console.log(metric.metric.id); // heartbeat-total
+```
+
+## SilentTelemetryConnector
+
+```typescript
+import { MetricType, SilentTelemetryConnector } from '@3sixty/telemetry-models';
+
+const silent = new SilentTelemetryConnector();
+
+console.log(silent.className()); // silentTelemetryConnector
+
+await silent.createMetric({
+  id: 'dropped-messages',
+  label: 'Dropped Messages',
+  type: MetricType.Counter
+});
+
+await silent.updateMetric({
+  id: 'dropped-messages',
+  label: 'Dropped Messages Total'
+});
+
+await silent.addMetricValue('dropped-messages', 1);
+await silent.removeMetric('dropped-messages');
+```
+
+```typescript
+import { SilentTelemetryConnector } from '@3sixty/telemetry-models';
+
+const silent = new SilentTelemetryConnector();
+
+try {
+  await silent.getMetric('dropped-messages');
+} catch (error) {
+  if (error instanceof Error) {
+    console.log(error.name); // NotSupportedError
+  }
+}
+
+try {
+  await silent.query();
+} catch (error) {
+  if (error instanceof Error) {
+    console.log(error.name); // NotSupportedError
+  }
+}
+
+try {
+  await silent.queryValues('dropped-messages');
+} catch (error) {
+  if (error instanceof Error) {
+    console.log(error.name); // NotSupportedError
+  }
+}
+```
+
+## TelemetryConnectorFactory
+
+```typescript
+import { SilentTelemetryConnector, TelemetryConnectorFactory } from '@3sixty/telemetry-models';
+
+TelemetryConnectorFactory.register('silent-default', () => new SilentTelemetryConnector());
+
+const connector = TelemetryConnectorFactory.get('silent-default');
+console.log(connector.className()); // silentTelemetryConnector
+```

package/docs/reference/classes/MetricHelper.md

@@ -0,0 +1,226 @@
+# Class: MetricHelper
+
+Helper class for performing common metric operations, swallowing any errors from the telemetry component.
+
+## Constructors
+
+### Constructor
+
+> **new MetricHelper**(): `MetricHelper`
+
+#### Returns
+
+`MetricHelper`
+
+## Methods
+
+### createMetrics() {#createmetrics}
+
+> `static` **createMetrics**(`telemetryComponent`, `metrics`): `Promise`\<`void`\>
+
+Create multiple metrics if they don't already exist, swallowing any already exists errors.
+A convenience wrapper over createMetric for callers that always have a list.
+
+#### Parameters
+
+##### telemetryComponent
+
+[`ITelemetryComponent`](../interfaces/ITelemetryComponent.md) \| `undefined`
+
+The telemetry component to use for creating the metrics.
+
+##### metrics
+
+[`ITelemetryMetric`](../interfaces/ITelemetryMetric.md)[]
+
+The telemetry metrics to create.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when all metrics have been created or confirmed to exist.
+
+***
+
+### createMetric() {#createmetric}
+
+> `static` **createMetric**(`telemetryComponent`, `metric`): `Promise`\<`void`\>
+
+Create one or more metrics if they don't already exist, swallowing any already exists errors.
+
+#### Parameters
+
+##### telemetryComponent
+
+[`ITelemetryComponent`](../interfaces/ITelemetryComponent.md) \| `undefined`
+
+The telemetry component to use for creating the metrics.
+
+##### metric
+
+[`ITelemetryMetric`](../interfaces/ITelemetryMetric.md) \| [`ITelemetryMetric`](../interfaces/ITelemetryMetric.md)[]
+
+The telemetry metric to create, or the metrics to create.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the metrics have been created or confirmed to exist.
+
+***
+
+### metricIncrement() {#metricincrement}
+
+> `static` **metricIncrement**(`telemetryComponent`, `id`, `customData?`, `onError?`): `Promise`\<`void`\>
+
+Increment a metric counter, swallowing any telemetry errors.
+
+#### Parameters
+
+##### telemetryComponent
+
+[`ITelemetryComponent`](../interfaces/ITelemetryComponent.md) \| `undefined`
+
+The telemetry component to use for incrementing the metric.
+
+##### id
+
+`string`
+
+The metric ID.
+
+##### customData?
+
+Optional custom data for the increment.
+
+##### onError?
+
+(`err`) => `void` \| `Promise`\<`void`\>
+
+Optional callback invoked with the swallowed error, for callers that want visibility.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the increment has been recorded or the error swallowed.
+
+***
+
+### metricDecrement() {#metricdecrement}
+
+> `static` **metricDecrement**(`telemetryComponent`, `id`, `customData?`, `onError?`): `Promise`\<`void`\>
+
+Decrement a metric counter, swallowing any telemetry errors.
+
+#### Parameters
+
+##### telemetryComponent
+
+[`ITelemetryComponent`](../interfaces/ITelemetryComponent.md) \| `undefined`
+
+The telemetry component to use for decrementing the metric.
+
+##### id
+
+`string`
+
+The metric ID.
+
+##### customData?
+
+Optional custom data for the decrement.
+
+##### onError?
+
+(`err`) => `void` \| `Promise`\<`void`\>
+
+Optional callback invoked with the swallowed error, for callers that want visibility.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the decrement has been recorded or the error swallowed.
+
+***
+
+### metricValue() {#metricvalue}
+
+> `static` **metricValue**(`telemetryComponent`, `id`, `value`, `customData?`, `onError?`): `Promise`\<`void`\>
+
+Set a metric value, swallowing any telemetry errors.
+
+#### Parameters
+
+##### telemetryComponent
+
+[`ITelemetryComponent`](../interfaces/ITelemetryComponent.md) \| `undefined`
+
+The telemetry component to use for setting the metric value.
+
+##### id
+
+`string`
+
+The metric ID.
+
+##### value
+
+`number`
+
+The metric value to set.
+
+##### customData?
+
+Optional custom data for setting the value.
+
+##### onError?
+
+(`err`) => `void` \| `Promise`\<`void`\>
+
+Optional callback invoked with the swallowed error, for callers that want visibility.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the value has been recorded or the error swallowed.
+
+***
+
+### metricValues() {#metricvalues}
+
+> `static` **metricValues**(`telemetryComponent`, `values`, `onError?`): `Promise`\<`void`\>
+
+Set several metric values at once, swallowing any telemetry errors.
+Components which support it record the whole set in one operation, which for a persisted
+connector is a single write rather than one per value.
+
+#### Parameters
+
+##### telemetryComponent
+
+[`ITelemetryComponent`](../interfaces/ITelemetryComponent.md) \| `undefined`
+
+The telemetry component to use for setting the metric values.
+
+##### values
+
+[`ITelemetryMetricValueEntry`](../interfaces/ITelemetryMetricValueEntry.md)[]
+
+The metric values to set.
+
+##### onError?
+
+(`err`) => `void` \| `Promise`\<`void`\>
+
+Optional callback invoked with the swallowed error, for callers that want visibility.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the values have been recorded or the error swallowed.