@cratis/chronicle 6.33.0 → 6.34.0

package/ChronicleClient.ts

@@ -2,7 +2,9 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import * as os from 'os';
-import { diag } from '@opentelemetry/api';
+import { createLogger } from './logging/createLogger.js';
+import { setTelemetryAttribute, recordSafeException } from './telemetry/spanAttributes.js';
+import { WellKnownTelemetryNames } from './WellKnownTelemetryNames.js';
 import { SpanStatusCode } from '@opentelemetry/api';
 import { ChronicleOptions } from './ChronicleOptions.js';
 import { ChronicleConnection } from './connection/index.js';
@@ -19,7 +21,8 @@ import { EventStoreNamespaceName } from './EventStoreNamespaceName.js';
 import { IChronicleClient } from './IChronicleClient.js';
 import { IEventStore } from './IEventStore.js';
 import { ChronicleMetrics } from './Metrics.js';
-import { ChronicleTracer } from './Tracing.js';
+import { observeOperation } from './telemetry/observeOperation.js';
+import { runInBackgroundContext } from './telemetry/runInBackgroundContext.js';
 import { TypeDiscoverer } from './types/index.js';
 import { takeUnregisteredModelBoundMappings } from './types/modelBoundPropertyMetadata.js';
 import { reachableReadModelTypes } from './readModels/rootReadModelTypes.js';
@@ -45,9 +48,7 @@ export class ChronicleClient implements IChronicleClient {
     private readonly _stores: Map<string, EventStore> = new Map();
     private readonly _lifecycle = new ConnectionLifecycle();
 
-    private readonly _logger = diag.createComponentLogger({
-        namespace: '@cratis/chronicle/ChronicleClient'
-    });
+    private readonly _logger: ReturnType<typeof createLogger>;
 
     private _watchdogHandle?: ReturnType<typeof setInterval>;
     private _connectOperation?: Promise<void>;
@@ -64,6 +65,7 @@ export class ChronicleClient implements IChronicleClient {
      * @param options - The options to configure the client, including the connection string.
      */
     constructor(readonly options: ChronicleOptions) {
+        this._logger = createLogger('@cratis/chronicle/ChronicleClient', options.logger);
         // When TLS is disabled, pass pre-built insecure credentials directly.
         // @cratis/chronicle.contracts ≤15.24.3 always composes call credentials with
         // channel credentials, which gRPC forbids for insecure channels. Passing
@@ -72,7 +74,7 @@ export class ChronicleClient implements IChronicleClient {
         const connectionOptions = options.connectionString.disableTls
             ? { connectionString: options.connectionString, credentials: options.connectionString.createCredentials() }
             : { connectionString: options.connectionString };
-        this._connection = new ChronicleConnection(connectionOptions);
+        this._connection = new ChronicleConnection({ ...connectionOptions, logger: options.logger });
 
         this._logger.info('Created Chronicle client', {
             serverAddress: `${options.connectionString.serverAddress.host}:${options.connectionString.serverAddress.port}`,
@@ -80,9 +82,11 @@ export class ChronicleClient implements IChronicleClient {
         });
 
         if (options.discoveryPatterns.length > 0) {
-            this._discoveryOperation = TypeDiscoverer.default.discover(options.discoveryPatterns);
-            this._discoveryOperation.catch(error => {
-                this._logger.error('Artifact file discovery failed', { error: String(error) });
+            runInBackgroundContext(() => {
+                this._discoveryOperation = TypeDiscoverer.default.discover(options.discoveryPatterns);
+                this._discoveryOperation.catch(error => {
+                    this._logger.error('Artifact file discovery failed', { error });
+                });
             });
         }
 
@@ -120,9 +124,9 @@ export class ChronicleClient implements IChronicleClient {
                 ? new EventStoreNamespaceName(namespace)
                 : namespace;
 
-        return ChronicleTracer.startActiveSpan('chronicle.client.get_event_store', async span => {
-            span.setAttribute('chronicle.event_store', storeName.value);
-            span.setAttribute('chronicle.namespace', namespaceName.value);
+        return observeOperation(WellKnownTelemetryNames.spans.getEventStore, async span => {
+            setTelemetryAttribute(span, 'eventStore', storeName.value);
+            setTelemetryAttribute(span, 'namespace', namespaceName.value);
             try {
                 const store = await this.withReconnect('get_event_store', async () => {
                     await this.ensureConnected();
@@ -142,7 +146,7 @@ export class ChronicleClient implements IChronicleClient {
                     });
                     ensureCommandSuccess('ensure event store', await this._connection.eventStores.ensureEventStore({ Name: storeName.value }));
 
-                    const created = new EventStore(storeName, namespaceName, this._connection, this._lifecycle, this.options.defaultSinkTypeId, this.options.clientArtifactsProvider, this.options.reactorResultHandler, this.options.artifactActivator, this.options.readModelNamingPolicy);
+                    const created = new EventStore(storeName, namespaceName, this._connection, this._lifecycle, this.options.defaultSinkTypeId, this.options.clientArtifactsProvider, this.options.reactorResultHandler, this.options.artifactActivator, this.options.readModelNamingPolicy, this.options.telemetry);
                     this._stores.set(key, created);
 
                     await this.registerArtifactsForStore(created, 'new-store');
@@ -156,12 +160,11 @@ export class ChronicleClient implements IChronicleClient {
                 span.setStatus({ code: SpanStatusCode.OK });
                 return store;
             } catch (error) {
-                span.setStatus({ code: SpanStatusCode.ERROR, message: String(error) });
-                span.recordException(error as Error);
+                recordSafeException(span, error);
                 this._logger.error('Failed getting event store', {
                     eventStore: storeName.value,
                     namespace: namespaceName.value,
-                    error: this.toErrorMessage(error)
+                    error
                 });
                 throw error;
             } finally {
@@ -172,7 +175,7 @@ export class ChronicleClient implements IChronicleClient {
 
     /** @inheritdoc */
     async getEventStores(): Promise<EventStoreName[]> {
-        return ChronicleTracer.startActiveSpan('chronicle.client.get_event_stores', async span => {
+        return observeOperation(WellKnownTelemetryNames.spans.getEventStores, async span => {
             try {
                 const response = await this.withReconnect('get_event_stores', async () => {
                     await this.ensureConnected();
@@ -185,10 +188,9 @@ export class ChronicleClient implements IChronicleClient {
                 span.setStatus({ code: SpanStatusCode.OK });
                 return result;
             } catch (error) {
-                span.setStatus({ code: SpanStatusCode.ERROR, message: String(error) });
-                span.recordException(error as Error);
+                recordSafeException(span, error);
                 this._logger.error('Failed retrieving event stores', {
-                    error: this.toErrorMessage(error)
+                    error
                 });
                 throw error;
             } finally {
@@ -210,7 +212,7 @@ export class ChronicleClient implements IChronicleClient {
         if (this._lifecycle.isConnected) {
             void this._lifecycle.disconnected(error => {
                 this._logger.error('Disconnected lifecycle callback failed during dispose', {
-                    error: this.toErrorMessage(error)
+                    error
                 });
             });
         }
@@ -244,7 +246,7 @@ export class ChronicleClient implements IChronicleClient {
                 await this.startKernelKeepAlive();
                 await this._lifecycle.connected(error => {
                     this._logger.error('Connected lifecycle callback failed', {
-                        error: this.toErrorMessage(error)
+                        error
                     });
                 });
                 return;
@@ -280,7 +282,7 @@ export class ChronicleClient implements IChronicleClient {
         }
 
         if (!this._connectOperation) {
-            this._connectOperation = this.connectWithRetry().finally(() => {
+            this._connectOperation = runInBackgroundContext(() => this.connectWithRetry()).finally(() => {
                 this._connectOperation = undefined;
             });
         }
@@ -292,16 +294,16 @@ export class ChronicleClient implements IChronicleClient {
         if (this._connectionFailure) throw this._connectionFailure;
 
         if (!this._reconnectOperation) {
-            this._reconnectOperation = (async () => {
+            this._reconnectOperation = runInBackgroundContext(async () => {
                 this._logger.warn('Reconnecting to Chronicle kernel', {
                     reason,
-                    error: this.toErrorMessage(error)
+                    error
                 });
 
                 if (this._lifecycle.isConnected) {
                     await this._lifecycle.disconnected(disconnectError => {
                         this._logger.error('Disconnected lifecycle callback failed', {
-                            error: this.toErrorMessage(disconnectError)
+                            error: disconnectError
                         });
                     });
                 }
@@ -317,7 +319,7 @@ export class ChronicleClient implements IChronicleClient {
                         await this.startKernelKeepAlive();
                         await this._lifecycle.connected(connectedError => {
                             this._logger.error('Connected lifecycle callback failed after reconnect', {
-                                error: this.toErrorMessage(connectedError)
+                                error: connectedError
                             });
                         });
                         return;
@@ -331,7 +333,7 @@ export class ChronicleClient implements IChronicleClient {
                         await this.backOff(attempt, 'Reconnect attempt failed, retrying', reconnectError);
                     }
                 }
-            })().finally(() => {
+            }).finally(() => {
                 this._reconnectOperation = undefined;
             });
         }
@@ -351,7 +353,7 @@ export class ChronicleClient implements IChronicleClient {
         this._logger.warn(message, {
             attempt,
             delayMs,
-            error: this.toErrorMessage(error)
+            error
         });
 
         await new Promise(resolve => setTimeout(resolve, delayMs));
@@ -437,9 +439,9 @@ export class ChronicleClient implements IChronicleClient {
     }
 
     private startConnectionWatchdog(): void {
-        this._watchdogHandle = setInterval(() => {
+        this._watchdogHandle = runInBackgroundContext(() => setInterval(() => {
             void this.runHealthCheck().catch(error => this.backgroundConnectionFailed('watchdog-health-check', error));
-        }, ChronicleClient._healthCheckIntervalMs);
+        }, ChronicleClient._healthCheckIntervalMs));
 
         this._watchdogHandle.unref?.();
     }
@@ -477,7 +479,7 @@ export class ChronicleClient implements IChronicleClient {
             }
 
             void this.reconnect(reason, error).catch(failure => this.backgroundConnectionFailed(reason, failure));
-        });
+        }, {}, this.options.logger);
 
         await keepAlive.start(
             {
@@ -511,7 +513,7 @@ export class ChronicleClient implements IChronicleClient {
         this.failConnection(error instanceof Error ? error : new Error(String(error)));
         this._logger.error('Background connection recovery failed; create a new client after correcting the server', {
             reason,
-            error: this.toErrorMessage(error)
+            error
         });
     }
 

package/ChronicleOptions.ts

@@ -1,14 +1,19 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
+import { types } from 'node:util';
 import { DefaultClientArtifactsProvider, IClientArtifactsProvider } from './artifacts/index.js';
 import { ChronicleConnectionString } from './connection/index.js';
 import { WellKnownSinks } from './sinks/index.js';
 import type { ReactorResultHandler } from './reactors/ReactorResultHandler.js';
 import type { ClientArtifactsActivator } from './artifacts/ClientArtifactsActivator.js';
 import type { ReadModelNamingPolicy } from './readModels/ReadModelNamingPolicy.js';
+import type { ChronicleTelemetryOptions } from './telemetry/ChronicleTelemetryOptions.js';
+import type { IChronicleLogger } from './logging/IChronicleLogger.js';
 
 type ChronicleOptionsConstructorParams = {
+    telemetry?: ChronicleTelemetryOptions;
+    logger?: IChronicleLogger;
     connectionString: ChronicleConnectionString;
     programIdentifier?: string;
     softwareVersion?: string;
@@ -22,6 +27,8 @@ type ChronicleOptionsConstructorParams = {
 };
 
 type ChronicleOptionsFactoryParams = {
+    telemetry?: ChronicleTelemetryOptions;
+    logger?: IChronicleLogger;
     clientArtifactsProvider?: IClientArtifactsProvider;
     discoveryPatterns?: string[];
     defaultSinkTypeId?: string;
@@ -34,6 +41,12 @@ type ChronicleOptionsFactoryParams = {
  * Represents configuration options for the Chronicle client.
  */
 export class ChronicleOptions {
+    /** Per-client telemetry privacy settings. Event source identifiers are omitted by default. */
+    readonly telemetry?: ChronicleTelemetryOptions;
+
+    /** Application diagnostic sink. Absent uses the OpenTelemetry diag compatibility adapter. */
+    readonly logger?: IChronicleLogger;
+
     /**
      * The connection string used to connect to the Chronicle Kernel.
      */
@@ -101,6 +114,17 @@ export class ChronicleOptions {
         this.reactorResultHandler = options.reactorResultHandler;
         this.artifactActivator = options.artifactActivator;
         this.readModelNamingPolicy = options.readModelNamingPolicy;
+        const policy = options.telemetry?.eventSourceId;
+        if (policy !== undefined) {
+            if (policy?.mode !== 'raw' && policy?.mode !== 'hmac') {
+                throw new TypeError('telemetry.eventSourceId.mode must be raw or hmac.');
+            }
+            if (policy.mode === 'hmac' && (!types.isUint8Array(policy.key) || policy.key.byteLength === 0)) {
+                throw new TypeError('telemetry.eventSourceId.key must be a non-empty Uint8Array for hmac mode.');
+            }
+        }
+        this.telemetry = options.telemetry;
+        this.logger = options.logger;
     }
 
     private static defaultDiscoveryPatterns(): string[] {
@@ -144,7 +168,9 @@ export class ChronicleOptions {
             defaultSinkTypeId: options?.defaultSinkTypeId,
             reactorResultHandler: options?.reactorResultHandler,
             artifactActivator: options?.artifactActivator,
-            readModelNamingPolicy: options?.readModelNamingPolicy
+            readModelNamingPolicy: options?.readModelNamingPolicy,
+            telemetry: options?.telemetry,
+            logger: options?.logger
         });
     }
 

package/EventStore.ts

@@ -1,7 +1,10 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-import { diag } from '@opentelemetry/api';
+import { createLogger } from './logging/createLogger.js';
+import type { ChronicleTelemetryOptions } from './telemetry/ChronicleTelemetryOptions.js';
+import { setTelemetryAttribute, recordSafeException } from './telemetry/spanAttributes.js';
+import { WellKnownTelemetryNames } from './WellKnownTelemetryNames.js';
 import { SpanStatusCode } from '@opentelemetry/api';
 import { ChronicleConnection } from './connection/index.js';
 import { ConnectionLifecycle } from './connection/ConnectionLifecycle.js';
@@ -31,7 +34,7 @@ import { IReadModels } from './readModels/IReadModels.js';
 import { ReadModels } from './readModels/ReadModels.js';
 import { EventSeeding } from './seeding/EventSeeding.js';
 import { IEventSeeding } from './seeding/IEventSeeding.js';
-import { ChronicleTracer } from './Tracing.js';
+import { observeOperation } from './telemetry/observeOperation.js';
 import { DefaultClientArtifactsProvider } from './artifacts/DefaultClientArtifactsProvider.js';
 import type { IClientArtifactsProvider } from './artifacts/IClientArtifactsProvider.js';
 import { validateArtifactSchemas } from './artifacts/validateArtifactSchemas.js';
@@ -59,9 +62,7 @@ import { Observers } from './observation/Observers.js';
  * via gRPC using the provided {@link ChronicleConnection}.
  */
 export class EventStore implements IEventStore {
-    private readonly _logger = diag.createComponentLogger({
-        namespace: '@cratis/chronicle/EventStore'
-    });
+    private readonly _logger: ReturnType<typeof createLogger>;
 
     readonly eventLog: IEventLog;
     readonly eventTypes: IEventTypes;
@@ -93,15 +94,17 @@ export class EventStore implements IEventStore {
         private readonly _artifacts: IClientArtifactsProvider = DefaultClientArtifactsProvider.default,
         reactorResultHandler?: ReactorResultHandler,
         artifactActivator?: ClientArtifactsActivator,
-        readModelNamingPolicy?: ReadModelNamingPolicy
+        readModelNamingPolicy?: ReadModelNamingPolicy,
+        private readonly _telemetry?: ChronicleTelemetryOptions
     ) {
+        this._logger = createLogger('@cratis/chronicle/EventStore', _connection.logger);
         this.unitOfWorkManager = new UnitOfWorkManager(this);
 
         const artifacts = this._artifacts;
         this._constraints = new Constraints(name.value, _connection, artifacts);
         this.constraints = this._constraints;
         const resolveConstraintMessage = this._constraints.resolveMessageFor.bind(this._constraints);
-        this.eventLog = new EventLog(name.value, namespace.value, _connection, this.unitOfWorkManager, resolveConstraintMessage);
+        this.eventLog = new EventLog(name.value, namespace.value, _connection, this.unitOfWorkManager, resolveConstraintMessage, _telemetry);
         this._sequences.set(EventSequenceId.eventLog.value, this.eventLog);
 
         this.eventTypes = new EventTypes(name.value, _connection, artifacts);
@@ -180,7 +183,7 @@ export class EventStore implements IEventStore {
 
         const sequence = new EventSequence(
             id, this.name.value, this.namespace.value, this._connection, this.unitOfWorkManager,
-            this._constraints.resolveMessageFor.bind(this._constraints)
+            this._constraints.resolveMessageFor.bind(this._constraints), this._telemetry
         );
         this._sequences.set(id.value, sequence);
         return sequence;
@@ -188,16 +191,15 @@ export class EventStore implements IEventStore {
 
     /** @inheritdoc */
     async getNamespaces(): Promise<EventStoreNamespaceName[]> {
-        return ChronicleTracer.startActiveSpan('chronicle.event_store.get_namespaces', async span => {
-            span.setAttribute('chronicle.event_store', this.name.value);
+        return observeOperation(WellKnownTelemetryNames.spans.getNamespaces, async span => {
+            setTelemetryAttribute(span, 'eventStore', this.name.value);
             try {
                 const response = await this._connection.namespaces.allNamespaces({ EventStore: this.name.value });
                 const result = ensureQuerySuccess('get namespaces', response).map(namespace => new EventStoreNamespaceName(namespace.Name));
                 span.setStatus({ code: SpanStatusCode.OK });
                 return result;
             } catch (error) {
-                span.setStatus({ code: SpanStatusCode.ERROR, message: String(error) });
-                span.recordException(error as Error);
+                recordSafeException(span, error);
                 throw error;
             } finally {
                 span.end();

package/Metrics.ts

@@ -1,109 +1,83 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-import { metrics } from '@opentelemetry/api';
+import { metrics, type Attributes, type Counter, type Histogram } from '@opentelemetry/api';
+import { clientVersion } from './connection/clientVersion.js';
+import { WellKnownTelemetryNames as names } from './WellKnownTelemetryNames.js';
 
-/**
- * The name of the Chronicle metrics instrumentation library.
- * This matches {@link ChronicleInstrumentationName} from Tracing so that all Chronicle
- * telemetry is grouped under a single instrumentation scope in your observability backend.
- */
-export const ChronicleMeterName = '@cratis/chronicle';
+/** The versioned instrumentation scope shared by Chronicle client traces and metrics. */
+export const ChronicleMeterName = names.scope;
 
-/**
- * The OpenTelemetry meter used by the Chronicle client for all metric instrumentation.
- *
- * If your application has configured an OpenTelemetry SDK (e.g. via {@link https://www.npmjs.com/package/@opentelemetry/sdk-node}),
- * Chronicle metrics will automatically flow through it.
- * If no SDK is configured, the no-op meter is used and no overhead is incurred.
- */
-export const ChronicleMeter = metrics.getMeter(ChronicleMeterName);
+/** The Chronicle meter. Applications own SDK configuration and export. */
+export const ChronicleMeter = metrics.getMeter(ChronicleMeterName, clientVersion);
 
-/**
- * Pre-built metric instruments for all Chronicle client operations.
- * These are created once and shared across all invocations.
- */
-export const ChronicleMetrics = {
-    /**
-     * Counts the number of individual events appended to an event sequence.
-     *
-     * Attributes: `chronicle.event_store`, `chronicle.namespace`,
-     * `chronicle.event_sequence_id`, `chronicle.event_type_id`
-     */
-    eventsAppended: ChronicleMeter.createCounter('chronicle.events.appended', {
-        description: 'Number of individual events appended to an event sequence.',
-        unit: '{event}'
-    }),
+// Resolve instruments at recording time: the OTel metrics API does not proxy a meter
+// acquired before the application installs its provider. SDKs cache these instruments.
+function counter(name: string, description: string, unit: string): Counter {
+    return { add: (value, attributes, context) => metrics.getMeter(ChronicleMeterName, clientVersion)
+        .createCounter(name, { description, unit }).add(value, attributes, context) };
+}
 
-    /**
-     * Counts the number of batch-append operations performed on an event sequence.
-     * Each call to appendMany counts as one batch regardless of how many events it contains.
-     *
-     * Attributes: `chronicle.event_store`, `chronicle.namespace`,
-     * `chronicle.event_sequence_id`, `chronicle.events_count`
-     */
-    batchAppendsPerformed: ChronicleMeter.createCounter('chronicle.events.batch_appends', {
-        description: 'Number of batch-append operations performed on an event sequence.',
-        unit: '{operation}'
-    }),
+function duration(name: string, unit: 's' | 'ms'): Histogram {
+    const scale = unit === 's' ? 0.001 : 1;
+    return { record: (value, attributes, context) => metrics.getMeter(ChronicleMeterName, clientVersion)
+        .createHistogram(name, {
+            description: 'Duration of completed event append RPCs, including returned rejections.',
+            unit,
+            advice: { explicitBucketBoundaries: [1, 5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000].map(value => value * scale) }
+        }).record(value, attributes, context) };
+}
 
-    /**
-     * Counts the number of event store retrieval operations.
-     *
-     * Attributes: `chronicle.event_store`, `chronicle.namespace`
-     */
-    eventStoreRetrievals: ChronicleMeter.createCounter('chronicle.client.event_store_retrievals', {
-        description: 'Number of event store retrieval operations.',
-        unit: '{operation}'
-    }),
+/** Shared-convention instruments. Durations are seconds; batch size is not a dimension. */
+export const ChronicleConventionMetrics = {
+    eventsAppended: counter(names.metrics.eventsAppended, 'Number of individual events appended to an event sequence.', '{event}'),
+    batchAppendsPerformed: counter(names.metrics.batchAppendsPerformed, 'Number of batch-append operations.', '{operation}'),
+    eventStoreRetrievals: counter(names.metrics.eventStoreRetrievals, 'Number of event store retrieval operations.', '{operation}'),
+    appendDuration: duration(names.metrics.appendDuration, 's'),
+    appendManyDuration: duration(names.metrics.appendManyDuration, 's'),
+    constraintViolations: counter(names.metrics.constraintViolations, 'Number of constraint violations encountered during event appends.', '{violation}'),
+    appendErrors: counter(names.metrics.appendErrors, 'Number of errors encountered during event appends.', '{error}')
+};
 
-    /**
-     * Measures the duration of append operations in milliseconds.
-     *
-     * Attributes: `chronicle.event_store`, `chronicle.namespace`,
-     * `chronicle.event_sequence_id`, `chronicle.event_type_id`
-     */
-    appendDuration: ChronicleMeter.createHistogram('chronicle.events.append_duration', {
-        description: 'Duration of individual event append operations.',
-        unit: 'ms',
-        advice: {
-            explicitBucketBoundaries: [1, 5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000]
-        }
-    }),
+/** Only the existing bounded-by-configuration dimensions belong on the new instruments. */
+function sharedAttributes(attributes: Attributes = {}): Attributes {
+    const result: Attributes = {};
+    for (const name of ['eventStore', 'namespace', 'eventSequenceId', 'eventTypeId'] as const) {
+        const value = attributes[names.attributes[name]] ?? attributes[names.legacyAttributes[name]];
+        if (value !== undefined) result[names.attributes[name]] = value;
+    }
+    return result;
+}
 
-    /**
-     * Measures the duration of batch-append operations in milliseconds.
-     *
-     * Attributes: `chronicle.event_store`, `chronicle.namespace`,
-     * `chronicle.event_sequence_id`, `chronicle.events_count`
-     */
-    appendManyDuration: ChronicleMeter.createHistogram('chronicle.events.append_many_duration', {
-        description: 'Duration of batch event append operations.',
-        unit: 'ms',
-        advice: {
-            explicitBucketBoundaries: [1, 5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000]
-        }
-    }),
+function bridgeCounter(legacy: Counter, shared: Counter): Counter {
+    return { add: (value, attributes, context) => {
+        legacy.add(value, attributes, context);
+        shared.add(value, sharedAttributes(attributes), context);
+    } };
+}
 
-    /**
-     * Counts the number of append constraint violations encountered.
-     *
-     * Attributes: `chronicle.event_store`, `chronicle.namespace`,
-     * `chronicle.event_sequence_id`
-     */
-    constraintViolations: ChronicleMeter.createCounter('chronicle.events.constraint_violations', {
-        description: 'Number of constraint violations encountered during event appends.',
-        unit: '{violation}'
-    }),
+function bridgeDuration(legacy: Histogram, shared: Histogram): Histogram {
+    return { record: (milliseconds, attributes, context) => {
+        legacy.record(milliseconds, attributes, context);
+        shared.record(milliseconds / 1000, sharedAttributes(attributes), context);
+    } };
+}
 
-    /**
-     * Counts the number of append errors encountered.
-     *
-     * Attributes: `chronicle.event_store`, `chronicle.namespace`,
-     * `chronicle.event_sequence_id`
-     */
-    appendErrors: ChronicleMeter.createCounter('chronicle.events.append_errors', {
-        description: 'Number of errors encountered during event appends.',
-        unit: '{error}'
-    })
+/**
+ * Compatibility instruments: existing callers still record milliseconds and legacy attributes.
+ * Each measurement also records its shared-convention equivalent, without adding sensitive dimensions.
+ */
+export const ChronicleMetrics = {
+    eventsAppended: bridgeCounter(counter(names.legacyMetrics.eventsAppended,
+        'Number of individual events appended to an event sequence.', '{event}'), ChronicleConventionMetrics.eventsAppended),
+    batchAppendsPerformed: bridgeCounter(counter(names.legacyMetrics.batchAppendsPerformed,
+        'Number of batch-append operations.', '{operation}'), ChronicleConventionMetrics.batchAppendsPerformed),
+    eventStoreRetrievals: bridgeCounter(counter(names.legacyMetrics.eventStoreRetrievals,
+        'Number of event store retrieval operations.', '{operation}'), ChronicleConventionMetrics.eventStoreRetrievals),
+    appendDuration: bridgeDuration(duration(names.legacyMetrics.appendDuration, 'ms'), ChronicleConventionMetrics.appendDuration),
+    appendManyDuration: bridgeDuration(duration(names.legacyMetrics.appendManyDuration, 'ms'), ChronicleConventionMetrics.appendManyDuration),
+    constraintViolations: bridgeCounter(counter(names.legacyMetrics.constraintViolations,
+        'Number of constraint violations encountered during event appends.', '{violation}'), ChronicleConventionMetrics.constraintViolations),
+    appendErrors: bridgeCounter(counter(names.legacyMetrics.appendErrors,
+        'Number of errors encountered during event appends.', '{error}'), ChronicleConventionMetrics.appendErrors)
 };

package/Tracing.ts

@@ -2,12 +2,14 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import { trace } from '@opentelemetry/api';
+import { clientVersion } from './connection/clientVersion.js';
+import { WellKnownTelemetryNames } from './WellKnownTelemetryNames.js';
 
 /**
  * The name of the Chronicle instrumentation library.
  * Use this name to filter or configure Chronicle client spans in your observability backend.
  */
-export const ChronicleInstrumentationName = '@cratis/chronicle';
+export const ChronicleInstrumentationName = WellKnownTelemetryNames.scope;
 
 /**
  * The OpenTelemetry tracer used by the Chronicle client for all instrumentation.
@@ -18,4 +20,4 @@ export const ChronicleInstrumentationName = '@cratis/chronicle';
  * Chronicle spans will automatically flow through it.
  * If no SDK is configured, the no-op tracer is used and no overhead is incurred.
  */
-export const ChronicleTracer = trace.getTracer(ChronicleInstrumentationName);
+export const ChronicleTracer = trace.getTracer(ChronicleInstrumentationName, clientVersion);

package/WellKnownTelemetryNames.ts

@@ -0,0 +1,67 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** Public telemetry names. Legacy names remain available during the minor-release overlap. */
+export const WellKnownTelemetryNames = {
+    scope: 'Cratis.Chronicle.Client',
+    legacyScope: '@cratis/chronicle',
+    attributes: {
+        correlationId: 'cratis.correlation_id',
+        eventStore: 'cratis.event_store.name',
+        namespace: 'cratis.event_store.namespace',
+        eventSequenceId: 'cratis.event_sequence.id',
+        sequenceNumber: 'cratis.event_sequence.number',
+        eventTypeId: 'cratis.event_type.id',
+        eventTypeGeneration: 'cratis.event_type.generation',
+        eventSourceType: 'cratis.event_source.type',
+        eventSourceId: 'cratis.event_source.id',
+        eventCount: 'cratis.event.count',
+        errorType: 'error.type',
+        exceptionType: 'exception.type'
+    },
+    legacyAttributes: {
+        eventStore: 'chronicle.event_store',
+        namespace: 'chronicle.namespace',
+        eventSequenceId: 'chronicle.event_sequence_id',
+        sequenceNumber: 'chronicle.sequence_number',
+        eventTypeId: 'chronicle.event_type_id',
+        eventTypeGeneration: 'chronicle.event_type_generation',
+        eventSourceId: 'chronicle.event_source_id',
+        eventCount: 'chronicle.events_count',
+        hasEvents: 'chronicle.has_events',
+        eventStreamType: 'chronicle.event_stream_type',
+        eventStreamId: 'chronicle.event_stream_id'
+    },
+    spans: {
+        append: 'chronicle.event_sequences.append',
+        appendMany: 'chronicle.event_sequences.append_many',
+        getTailSequenceNumber: 'chronicle.event_sequences.get_tail_sequence_number',
+        hasEventsFor: 'chronicle.event_sequences.has_events_for',
+        getForEventSourceIdAndEventTypes: 'chronicle.event_sequences.get_for_event_source_id_and_event_types',
+        getFromSequenceNumber: 'chronicle.event_sequences.get_from_sequence_number',
+        redact: 'chronicle.event_sequences.redact',
+        redactForEventSource: 'chronicle.event_sequences.redact_for_event_source',
+        completeStream: 'chronicle.event_sequences.complete_stream',
+        getEventStore: 'chronicle.client.get_event_store',
+        getEventStores: 'chronicle.client.get_event_stores',
+        getNamespaces: 'chronicle.event_store.get_namespaces'
+    },
+    metrics: {
+        eventsAppended: 'cratis.chronicle.event_sequence.appended',
+        batchAppendsPerformed: 'cratis.chronicle.event_sequence.batch_appends',
+        eventStoreRetrievals: 'cratis.chronicle.event_store.retrievals',
+        appendDuration: 'cratis.chronicle.event_sequence.append_duration',
+        appendManyDuration: 'cratis.chronicle.event_sequence.append_many_duration',
+        constraintViolations: 'cratis.chronicle.event_sequence.constraint_violations',
+        appendErrors: 'cratis.chronicle.event_sequence.append_errors'
+    },
+    legacyMetrics: {
+        eventsAppended: 'chronicle.events.appended',
+        batchAppendsPerformed: 'chronicle.events.batch_appends',
+        eventStoreRetrievals: 'chronicle.client.event_store_retrievals',
+        appendDuration: 'chronicle.events.append_duration',
+        appendManyDuration: 'chronicle.events.append_many_duration',
+        constraintViolations: 'chronicle.events.constraint_violations',
+        appendErrors: 'chronicle.events.append_errors'
+    }
+} as const;