@cratis/chronicle 6.32.1 → 6.34.0

package/eventSequences/EventSequence.ts

@@ -2,7 +2,7 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import { ChronicleConnection } from '../connection/index.js';
-import { SpanStatusCode } from '@opentelemetry/api';
+import { SpanStatusCode, type Span } from '@opentelemetry/api';
 import type {
     AppendedEventResponse as ContractsAppendedEvent,
     AppendManyResponse as ContractsAppendManyResponse,
@@ -37,7 +37,10 @@ import type { WaitForCompletionOptions } from './WaitForCompletionOptions.js';
 
 /** Default timeout for {@link AppendResult.waitForCompletion}, matching the C# client's default. */
 const DEFAULT_WAIT_FOR_COMPLETION_TIMEOUT_MS = 5000;
-import { ChronicleTracer } from '../Tracing.js';
+import { observeOperation } from '../telemetry/observeOperation.js';
+import { setTelemetryAttribute, setEventSourceId, setSequenceNumber, recordSafeException } from '../telemetry/spanAttributes.js';
+import type { ChronicleTelemetryOptions } from '../telemetry/ChronicleTelemetryOptions.js';
+import { WellKnownTelemetryNames as names } from '../WellKnownTelemetryNames.js';
 import { ChronicleMetrics } from '../Metrics.js';
 import { identityProvider, Identity } from '../identity/index.js';
 import { causationManager, CausationType } from '../auditing/index.js';
@@ -60,7 +63,8 @@ export class EventSequence implements IEventSequence {
         private readonly _namespace: string,
         private readonly _connection: ChronicleConnection,
         private readonly _unitOfWorkManager: IUnitOfWorkManager,
-        private readonly _resolveConstraintMessage?: (violation: ConstraintViolation) => ConstraintViolation
+        private readonly _resolveConstraintMessage?: (violation: ConstraintViolation) => ConstraintViolation,
+        private readonly _telemetry?: ChronicleTelemetryOptions
     ) {
         this.transactional = new TransactionalEventSequence(this, this._unitOfWorkManager);
     }
@@ -76,14 +80,13 @@ export class EventSequence implements IEventSequence {
             'chronicle.event_type_id': eventType.id.value
         };
 
-        return ChronicleTracer.startActiveSpan('chronicle.event_sequences.append', async span => {
-            span.setAttribute('chronicle.event_store', this._eventStoreName);
-            span.setAttribute('chronicle.namespace', this._namespace);
-            span.setAttribute('chronicle.event_sequence_id', this.id.value);
-            span.setAttribute('chronicle.event_source_id', eventSourceId);
-            span.setAttribute('chronicle.event_type_id', eventType.id.value);
-            span.setAttribute('chronicle.event_type_generation', eventType.generation.value);
-            const startTime = Date.now();
+        return observeOperation(names.spans.append, async span => {
+            this.setSequenceAttributes(span);
+            setEventSourceId(span, eventSourceId, this._telemetry);
+            setTelemetryAttribute(span, 'eventTypeId', eventType.id.value);
+            setTelemetryAttribute(span, 'eventTypeGeneration', eventType.generation.value);
+            if (options?.sourceType) span.setAttribute(names.attributes.eventSourceType, options.sourceType);
+            const startTime = performance.now();
             try {
                 const response = await this._connection.eventSequences.append({
                     EventStore: this._eventStoreName,
@@ -113,14 +116,14 @@ export class EventSequence implements IEventSequence {
                 });
 
                 const appendResponse = ensureCommandResponse('append event', response);
-                const duration = Date.now() - startTime;
+                const duration = performance.now() - startTime;
                 const result = this.mapAppendResponse(
                     appendResponse.SequenceNumber,
                     appendResponse.ConstraintViolations ?? [],
                     appendResponse.Errors ?? [],
                     appendResponse.ConcurrencyViolation
                 );
-                span.setAttribute('chronicle.sequence_number', result.sequenceNumber.value.toString());
+                setSequenceNumber(span, result.sequenceNumber.value);
                 span.setStatus({ code: SpanStatusCode.OK });
 
                 ChronicleMetrics.eventsAppended.add(1, metricAttributes);
@@ -147,8 +150,7 @@ export class EventSequence implements IEventSequence {
 
                 return result;
             } catch (error) {
-                span.setStatus({ code: SpanStatusCode.ERROR, message: String(error) });
-                span.recordException(error as Error);
+                recordSafeException(span, error);
                 ChronicleMetrics.appendErrors.add(1, {
                     'chronicle.event_store': this._eventStoreName,
                     'chronicle.namespace': this._namespace,
@@ -158,7 +160,7 @@ export class EventSequence implements IEventSequence {
             } finally {
                 span.end();
             }
-        });
+        }, correlationId);
     }
 
     /** @inheritdoc */
@@ -181,15 +183,13 @@ export class EventSequence implements IEventSequence {
             'chronicle.events_count': eventsForEventSourceIds.length
         };
 
-        return ChronicleTracer.startActiveSpan('chronicle.event_sequences.append_many', async span => {
-            span.setAttribute('chronicle.event_store', this._eventStoreName);
-            span.setAttribute('chronicle.namespace', this._namespace);
-            span.setAttribute('chronicle.event_sequence_id', this.id.value);
+        return observeOperation(names.spans.appendMany, async span => {
+            this.setSequenceAttributes(span);
             if (distinctEventSourceIds.length === 1) {
-                span.setAttribute('chronicle.event_source_id', distinctEventSourceIds[0]);
+                setEventSourceId(span, distinctEventSourceIds[0], this._telemetry);
             }
-            span.setAttribute('chronicle.events_count', eventsForEventSourceIds.length);
-            const startTime = Date.now();
+            setTelemetryAttribute(span, 'eventCount', eventsForEventSourceIds.length);
+            const startTime = performance.now();
             try {
                 const response = await this._connection.eventSequences.appendManyForEventSources({
                     EventStore: this._eventStoreName,
@@ -210,7 +210,7 @@ export class EventSequence implements IEventSequence {
                 });
 
                 const appendManyResponse = ensureCommandResponse('append many events', response);
-                const duration = Date.now() - startTime;
+                const duration = performance.now() - startTime;
                 // Mirrors the C# client: every per-event AppendResult in a batch carries all
                 // constraint violations and the first concurrency violation of the whole batch —
                 // the wire response doesn't correlate either back to a specific event index.
@@ -269,8 +269,7 @@ export class EventSequence implements IEventSequence {
 
                 return result;
             } catch (error) {
-                span.setStatus({ code: SpanStatusCode.ERROR, message: String(error) });
-                span.recordException(error as Error);
+                recordSafeException(span, error);
                 ChronicleMetrics.appendErrors.add(1, {
                     'chronicle.event_store': this._eventStoreName,
                     'chronicle.namespace': this._namespace,
@@ -280,7 +279,7 @@ export class EventSequence implements IEventSequence {
             } finally {
                 span.end();
             }
-        });
+        }, correlationId);
     }
 
     /** @inheritdoc */
@@ -300,13 +299,9 @@ export class EventSequence implements IEventSequence {
         eventStreamId?: string,
         filterEventTypes?: Constructor[]
     ): Promise<EventSequenceNumber> {
-        return ChronicleTracer.startActiveSpan('chronicle.event_sequences.get_tail_sequence_number', async span => {
-            span.setAttribute('chronicle.event_store', this._eventStoreName);
-            span.setAttribute('chronicle.namespace', this._namespace);
-            span.setAttribute('chronicle.event_sequence_id', this.id.value);
-            if (eventSourceId !== undefined) {
-                span.setAttribute('chronicle.event_source_id', eventSourceId);
-            }
+        return observeOperation(names.spans.getTailSequenceNumber, async span => {
+            this.setSequenceAttributes(span);
+            setEventSourceId(span, eventSourceId, this._telemetry);
             try {
                 const response = await this._connection.eventSequences.tailSequenceNumber({
                     EventStore: this._eventStoreName,
@@ -324,12 +319,11 @@ export class EventSequence implements IEventSequence {
 
                 const data = ensureQuerySuccess('get tail sequence number', response);
                 const result = new EventSequenceNumber(data?.SequenceNumber ?? 0n);
-                span.setAttribute('chronicle.sequence_number', result.value.toString());
+                setSequenceNumber(span, result.value);
                 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();
@@ -345,11 +339,9 @@ export class EventSequence implements IEventSequence {
 
     /** @inheritdoc */
     async hasEventsFor(eventSourceId: string): Promise<boolean> {
-        return ChronicleTracer.startActiveSpan('chronicle.event_sequences.has_events_for', async span => {
-            span.setAttribute('chronicle.event_store', this._eventStoreName);
-            span.setAttribute('chronicle.namespace', this._namespace);
-            span.setAttribute('chronicle.event_sequence_id', this.id.value);
-            span.setAttribute('chronicle.event_source_id', eventSourceId);
+        return observeOperation(names.spans.hasEventsFor, async span => {
+            this.setSequenceAttributes(span);
+            setEventSourceId(span, eventSourceId, this._telemetry);
             try {
                 const response = await this._connection.eventSequences.hasEventsForEventSourceId({
                     EventStore: this._eventStoreName,
@@ -359,12 +351,11 @@ export class EventSequence implements IEventSequence {
                 });
 
                 const result = ensureQuerySuccess('has events for event source', response)?.HasEvents ?? false;
-                span.setAttribute('chronicle.has_events', result);
+                setTelemetryAttribute(span, 'hasEvents', result);
                 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();
@@ -380,11 +371,9 @@ export class EventSequence implements IEventSequence {
         eventStreamId?: string,
         eventSourceType?: string
     ): Promise<AppendedEvent[]> {
-        return ChronicleTracer.startActiveSpan('chronicle.event_sequences.get_for_event_source_id_and_event_types', async span => {
-            span.setAttribute('chronicle.event_store', this._eventStoreName);
-            span.setAttribute('chronicle.namespace', this._namespace);
-            span.setAttribute('chronicle.event_sequence_id', this.id.value);
-            span.setAttribute('chronicle.event_source_id', eventSourceId);
+        return observeOperation(names.spans.getForEventSourceIdAndEventTypes, async span => {
+            this.setSequenceAttributes(span);
+            setEventSourceId(span, eventSourceId, this._telemetry);
             try {
                 const response = await this._connection.eventSequences.forEventSourceIdAndEventTypes({
                     EventStore: this._eventStoreName,
@@ -403,8 +392,7 @@ export class EventSequence implements IEventSequence {
                 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();
@@ -418,11 +406,10 @@ export class EventSequence implements IEventSequence {
         eventSourceId?: string,
         filterEventTypes?: Constructor[]
     ): Promise<AppendedEvent[]> {
-        return ChronicleTracer.startActiveSpan('chronicle.event_sequences.get_from_sequence_number', async span => {
-            span.setAttribute('chronicle.event_store', this._eventStoreName);
-            span.setAttribute('chronicle.namespace', this._namespace);
-            span.setAttribute('chronicle.event_sequence_id', this.id.value);
-            span.setAttribute('chronicle.sequence_number', sequenceNumber.value.toString());
+        return observeOperation(names.spans.getFromSequenceNumber, async span => {
+            this.setSequenceAttributes(span);
+            setSequenceNumber(span, sequenceNumber.value);
+            setEventSourceId(span, eventSourceId, this._telemetry);
             try {
                 const response = await this._connection.eventSequences.fromSequenceNumber({
                     EventStore: this._eventStoreName,
@@ -437,8 +424,7 @@ export class EventSequence implements IEventSequence {
                 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();
@@ -452,11 +438,9 @@ export class EventSequence implements IEventSequence {
         const causationChain = causationManager.getCurrentChain();
         const identity = identityProvider.getCurrent();
 
-        return ChronicleTracer.startActiveSpan('chronicle.event_sequences.redact', async span => {
-            span.setAttribute('chronicle.event_store', this._eventStoreName);
-            span.setAttribute('chronicle.namespace', this._namespace);
-            span.setAttribute('chronicle.event_sequence_id', this.id.value);
-            span.setAttribute('chronicle.sequence_number', sequenceNumber.value.toString());
+        return observeOperation(names.spans.redact, async span => {
+            this.setSequenceAttributes(span);
+            setSequenceNumber(span, sequenceNumber.value);
             try {
                 ensureCommandSuccess('redact event', await this._connection.eventSequences.redact({
                     EventStore: this._eventStoreName,
@@ -473,8 +457,7 @@ export class EventSequence implements IEventSequence {
                 }));
                 span.setStatus({ code: SpanStatusCode.OK });
             } catch (error) {
-                span.setStatus({ code: SpanStatusCode.ERROR, message: String(error) });
-                span.recordException(error as Error);
+                recordSafeException(span, error);
                 throw error;
             } finally {
                 span.end();
@@ -489,11 +472,9 @@ export class EventSequence implements IEventSequence {
         const identity = identityProvider.getCurrent();
         const wireEventTypeIds = (eventTypes ?? []).map(constructor => getEventTypeFor(constructor as unknown as Function).id.value);
 
-        return ChronicleTracer.startActiveSpan('chronicle.event_sequences.redact_for_event_source', async span => {
-            span.setAttribute('chronicle.event_store', this._eventStoreName);
-            span.setAttribute('chronicle.namespace', this._namespace);
-            span.setAttribute('chronicle.event_sequence_id', this.id.value);
-            span.setAttribute('chronicle.event_source_id', eventSourceId);
+        return observeOperation(names.spans.redactForEventSource, async span => {
+            this.setSequenceAttributes(span);
+            setEventSourceId(span, eventSourceId, this._telemetry);
             try {
                 ensureCommandSuccess('redact event source', await this._connection.eventSequences.redactForEventSource({
                     EventStore: this._eventStoreName,
@@ -511,8 +492,7 @@ export class EventSequence implements IEventSequence {
                 }));
                 span.setStatus({ code: SpanStatusCode.OK });
             } catch (error) {
-                span.setStatus({ code: SpanStatusCode.ERROR, message: String(error) });
-                span.recordException(error as Error);
+                recordSafeException(span, error);
                 throw error;
             } finally {
                 span.end();
@@ -538,12 +518,10 @@ export class EventSequence implements IEventSequence {
 
     /** @inheritdoc */
     async completeStream(eventStreamType: string, eventStreamId: string): Promise<CompleteStreamResult> {
-        return ChronicleTracer.startActiveSpan('chronicle.event_sequences.complete_stream', async span => {
-            span.setAttribute('chronicle.event_store', this._eventStoreName);
-            span.setAttribute('chronicle.namespace', this._namespace);
-            span.setAttribute('chronicle.event_sequence_id', this.id.value);
-            span.setAttribute('chronicle.event_stream_type', eventStreamType);
-            span.setAttribute('chronicle.event_stream_id', eventStreamId);
+        return observeOperation(names.spans.completeStream, async span => {
+            this.setSequenceAttributes(span);
+            setTelemetryAttribute(span, 'eventStreamType', eventStreamType);
+            setTelemetryAttribute(span, 'eventStreamId', eventStreamId);
             try {
                 const response = await this._connection.eventSequences.completeStream({
                     EventStore: this._eventStoreName,
@@ -561,8 +539,7 @@ export class EventSequence implements IEventSequence {
                 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();
@@ -570,6 +547,12 @@ export class EventSequence implements IEventSequence {
         });
     }
 
+    private setSequenceAttributes(span: Span): void {
+        setTelemetryAttribute(span, 'eventStore', this._eventStoreName);
+        setTelemetryAttribute(span, 'namespace', this._namespace);
+        setTelemetryAttribute(span, 'eventSequenceId', this.id.value);
+    }
+
     private toClientCompleteStreamError(error: number): CompleteStreamError {
         // Mirrors the C# client's switch: any wire value other than DefaultStreamCannotBeCompleted
         // (including UNRECOGNIZED) is treated as AlreadyCompleted.

package/eventStoreSubscriptions/EventStoreSubscriptions.ts

@@ -1,7 +1,7 @@
 // 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 { ChronicleConnection } from '../connection/index.js';
 import { EventStoreName } from '../EventStoreName.js';
 import { EventType, EventTypeGeneration, EventTypeId, IEventTypes } from '../events/index.js';
@@ -15,15 +15,15 @@ import { IEventStoreSubscriptions } from './IEventStoreSubscriptions.js';
  * Represents an implementation of {@link IEventStoreSubscriptions}.
  */
 export class EventStoreSubscriptions implements IEventStoreSubscriptions {
-    private readonly _logger = diag.createComponentLogger({
-        namespace: '@cratis/chronicle/EventStoreSubscriptions'
-    });
+    private readonly _logger: ReturnType<typeof createLogger>;
 
     constructor(
         private readonly _eventTypes: IEventTypes,
         private readonly _targetEventStore: string,
         private readonly _connection: ChronicleConnection
-    ) {}
+    ) {
+        this._logger = createLogger('@cratis/chronicle/EventStoreSubscriptions', _connection.logger);
+    }
 
     /** @inheritdoc */
     async subscribe(

package/for_ChronicleClient/when_starting_background_work/with_a_correlated_caller.spec.ts

@@ -0,0 +1,150 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { afterEach, beforeEach, chai, describe, it } from 'vitest';
+import { context, propagation, trace } from '@opentelemetry/api';
+import { createServer, ServerError, Status, type ServiceImplementation } from 'nice-grpc';
+import { Metadata } from 'nice-grpc-common';
+import { ConnectionServiceDefinition, EventStoresDefinition, ServerDefinition, ReactorsDefinition, ReducersDefinition, ReadModelsDefinition } from '@cratis/chronicle.contracts';
+import { ChronicleClient } from '../../ChronicleClient.js';
+import { ChronicleOptions } from '../../ChronicleOptions.js';
+import type { IClientArtifactsProvider } from '../../artifacts/IClientArtifactsProvider.js';
+import { CorrelationId, correlationIdManager } from '../../correlation/index.js';
+import type { ChronicleLogEntry } from '../../logging/ChronicleLogEntry.js';
+import { reactor } from '../../reactors/reactor.js';
+import { reducer } from '../../reducers/reducer.js';
+import { telemetrySession } from '../../telemetry/for_ChronicleTelemetry/given/a_telemetry_session.fixture.js';
+
+const should = chai.should();
+const telemetry = telemetrySession();
+class BackgroundReactor {}
+reactor('background-reactor')(BackgroundReactor);
+class BackgroundReducer {}
+reducer('background-reducer')(BackgroundReducer);
+const artifacts: IClientArtifactsProvider = {
+    eventTypes: [], readModels: [], reactors: [BackgroundReactor], reducers: [BackgroundReducer],
+    seeders: [], constraints: [], projections: [], webhooks: [], eventTypeMigrations: [], globalForHandlers: []
+};
+let server: ReturnType<typeof createServer>;
+let client: ChronicleClient;
+let received: { method: string; metadata: Metadata }[];
+let logs: ChronicleLogEntry[];
+let hostTraceId: string;
+const correlation = new CorrelationId('a4450131-7cd4-40ba-9438-69c680efc1f3');
+
+function deferred() {
+    let resolve!: () => void;
+    const promise = new Promise<void>(complete => { resolve = complete; });
+    return { promise, resolve };
+}
+
+beforeEach(async () => {
+    received = [];
+    logs = [];
+    const reobserved = deferred();
+    const reconnected = deferred();
+    const endKeepAlive = deferred();
+    const counts = new Map<string, number>();
+    server = createServer().use(async function* (call, callContext) {
+        const method = call.method.path;
+        received.push({ method, metadata: Metadata(callContext.metadata) });
+        const count = (counts.get(method) ?? 0) + 1;
+        counts.set(method, count);
+        const observations = [...counts].filter(([path]) => path.endsWith('/Observe'));
+        if (observations.length === 2 && observations.every(([, total]) => total >= 2)) reobserved.resolve();
+        if (observations.length === 2 && observations.every(([, total]) => total >= 3)) reconnected.resolve();
+        return yield* call.next(call.request, callContext);
+    });
+    const unused = async () => { throw new Error('Unexpected RPC'); };
+    const success = async () => ({ IsAuthorized: true, ValidationResults: [], ExceptionMessages: [] });
+    let connections = 0;
+    server.add(ConnectionServiceDefinition, {
+        ...Object.fromEntries(Object.keys(ConnectionServiceDefinition.methods).map(name => [name, unused])),
+        checkCompatibility: async () => ({ IsCompatible: true, Incompatibilities: [], ServerVersion: 'test' }),
+        connectionKeepAlive: async () => ({}),
+        connect: async function* (request, callContext) {
+            const first = ++connections === 1;
+            yield { ConnectionId: request.ConnectionId };
+            if (first) await endKeepAlive.promise;
+            else await new Promise<void>(resolve => callContext.signal.addEventListener('abort', () => resolve(), { once: true }));
+        }
+    } as ServiceImplementation<typeof ConnectionServiceDefinition>);
+    server.add(ServerDefinition, {
+        ...Object.fromEntries(Object.keys(ServerDefinition.methods).map(name => [name, unused])),
+        getVersionInfo: async () => ({})
+    } as ServiceImplementation<typeof ServerDefinition>);
+    server.add(EventStoresDefinition, {
+        allEventStores: unused, ensureEventStore: success, observeEventStores: unused
+    } as ServiceImplementation<typeof EventStoresDefinition>);
+    server.add(ReadModelsDefinition, {
+        ...Object.fromEntries(Object.keys(ReadModelsDefinition.methods).map(name => [name, unused])),
+        registerMany: success
+    } as ServiceImplementation<typeof ReadModelsDefinition>);
+    server.add(ReactorsDefinition, {
+        ...Object.fromEntries(Object.keys(ReactorsDefinition.methods).map(name => [name, unused])),
+        observe: async function* (requests) {
+            for await (const _request of requests) {
+                yield { Events: [], Partition: '', ReplayState: 0 };
+                throw new ServerError(Status.UNAVAILABLE, 'End stream to exercise re-observation');
+            }
+        }
+    } as ServiceImplementation<typeof ReactorsDefinition>);
+    server.add(ReducersDefinition, {
+        ...Object.fromEntries(Object.keys(ReducersDefinition.methods).map(name => [name, unused])),
+        observe: async function* (requests) {
+            for await (const _request of requests) {
+                yield { Events: [], Partition: '', ReplayState: 0 };
+                throw new ServerError(Status.UNAVAILABLE, 'End stream to exercise re-observation');
+            }
+        }
+    } as ServiceImplementation<typeof ReducersDefinition>);
+    const port = await server.listen('127.0.0.1:0');
+    const span = telemetry.traces.getTracer('host').startSpan('host');
+    hostTraceId = span.spanContext().traceId;
+    const active = propagation.setBaggage(trace.setSpan(context.active(), span), propagation.createBaggage({
+        'cratis.correlation_id': { value: correlation.toString() }, email: { value: 'private@example.com' }
+    }));
+    try {
+        await context.with(active, () => correlationIdManager.run(correlation, async () => {
+            client = new ChronicleClient(ChronicleOptions.fromConnectionString(`chronicle://127.0.0.1:${port}?disableTls=true&apiKey=test`, {
+                discoveryPatterns: [], clientArtifactsProvider: artifacts, logger: { log: entry => logs.push(entry) }
+            }));
+            await client.getEventStore('store');
+            context.active().should.equal(active);
+            correlationIdManager.scoped!.should.equal(correlation);
+        }));
+        await reobserved.promise;
+        endKeepAlive.resolve();
+        await reconnected.promise;
+    } finally { span.end(); endKeepAlive.resolve(); }
+});
+
+afterEach(async () => {
+    client?.dispose();
+    await server?.shutdown();
+});
+
+describe('when a correlated getEventStore starts background streams and their recovery loops', () => {
+    it('should not propagate the caller trace or baggage on observations or keep-alive RPCs', () => {
+        const background = received.filter(({ method }) => /\/(Observe|Connect|ConnectionKeepAlive)$/.test(method));
+        background.length.should.be.greaterThanOrEqual(10);
+        for (const { metadata } of background) {
+            should.equal(metadata.get('traceparent'), undefined);
+            should.equal(metadata.get('baggage'), undefined);
+        }
+    });
+    it('should retain the caller context on the foreground operation', () => {
+        const foreground = received.find(({ method }) => method.endsWith('/EnsureEventStore'))!;
+        foreground.metadata.get('traceparent')!.should.contain(hostTraceId);
+        should.equal(foreground.metadata.get('baggage'), `cratis.correlation_id=${correlation}`);
+    });
+    it('should not label background-loop diagnostics with the initiating business correlation or trace', () => {
+        const background = logs.filter(entry => /observation|keep-alive|Reconnect/.test(entry.message));
+        background.length.should.be.greaterThan(0);
+        for (const entry of background) {
+            entry.attributes.should.not.have.property('cratis.correlation_id');
+            entry.attributes.should.not.have.property('trace_id');
+            entry.attributes.should.not.have.property('span_id');
+        }
+    });
+});

package/for_ChronicleOptions/when_configuring_telemetry/with_event_source_identifiers.spec.ts

@@ -0,0 +1,44 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { chai, describe, it } from 'vitest';
+import { runInNewContext } from 'node:vm';
+import { ChronicleOptions } from '../../ChronicleOptions.js';
+import type { ChronicleTelemetryOptions } from '../../telemetry/ChronicleTelemetryOptions.js';
+
+chai.should();
+
+for (const policy of [
+    { mode: 'unknown' }, {}, null,
+    { mode: 'hmac' }, { mode: 'hmac', key: '' }, { mode: 'hmac', key: 'secret' },
+    { mode: 'hmac', key: [] }, { mode: 'hmac', key: new Uint8Array() },
+    { mode: 'hmac', key: Buffer.alloc(0) }, { mode: 'hmac', key: new Uint16Array([1]) },
+    { mode: 'hmac', key: new DataView(new ArrayBuffer(1)) },
+    { mode: 'hmac', key: runInNewContext('new Uint8Array()') },
+    { mode: 'hmac', key: runInNewContext('new Uint16Array([1])') }
+]) {
+    describe(`when configuring event source privacy with ${JSON.stringify(policy)}`, () => {
+        it('should reject invalid telemetry configuration before a client can make business calls', () => {
+            const telemetry = { eventSourceId: policy } as unknown as ChronicleTelemetryOptions;
+            (() => ChronicleOptions.development({ telemetry })).should.throw(TypeError);
+            (() => ChronicleOptions.fromConnectionString('chronicle://localhost:35000', { telemetry })).should.throw(TypeError);
+        });
+    });
+}
+
+describe('when configuring an HMAC key created in another realm', () => {
+    it('should accept a non-empty byte array without relying on its realm constructor', () => {
+        const key = runInNewContext('new Uint8Array([1, 2, 3])') as Uint8Array;
+        (key instanceof Uint8Array).should.be.false;
+        (() => ChronicleOptions.development({ telemetry: { eventSourceId: { mode: 'hmac', key } } })).should.not.throw();
+        (() => ChronicleOptions.fromConnectionString('chronicle://localhost:35000', { telemetry: { eventSourceId: { mode: 'hmac', key } } })).should.not.throw();
+    });
+});
+
+for (const eventSourceId of [undefined, { mode: 'raw' }, { mode: 'hmac', key: new Uint8Array([1]) }, { mode: 'hmac', key: Buffer.from('key') }] as const) {
+    describe('when configuring a supported event source privacy policy', () => {
+        it('should accept omitted identifiers, raw identifiers and non-empty byte keys', () => {
+            (() => ChronicleOptions.development({ telemetry: { eventSourceId } })).should.not.throw();
+        });
+    });
+}

package/index.ts

@@ -37,7 +37,13 @@ export { EventStoreNamespaceName } from './EventStoreNamespaceName.js';
 export { Guid } from '@cratis/fundamentals';
 export { ReplayState } from '@cratis/chronicle.contracts';
 export { ChronicleInstrumentationName, ChronicleTracer } from './Tracing.js';
-export { ChronicleMeter, ChronicleMeterName, ChronicleMetrics } from './Metrics.js';
+export { ChronicleMeter, ChronicleMeterName, ChronicleMetrics, ChronicleConventionMetrics } from './Metrics.js';
+export { WellKnownTelemetryNames } from './WellKnownTelemetryNames.js';
+export type { ChronicleTelemetryOptions } from './telemetry/ChronicleTelemetryOptions.js';
+export type { IChronicleLogger } from './logging/IChronicleLogger.js';
+export type { ChronicleLogEntry } from './logging/ChronicleLogEntry.js';
+export { ChronicleLogLevel } from './logging/ChronicleLogLevel.js';
+export { DiagChronicleLogger } from './logging/DiagChronicleLogger.js';
 
 export * from './events/index.js';
 export * from './eventSequences/index.js';

package/logging/ChronicleLogEntry.ts

@@ -0,0 +1,14 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { Attributes } from '@opentelemetry/api';
+import type { ChronicleLogLevel } from './ChronicleLogLevel.js';
+
+/** Structured diagnostic without event payloads, error messages or error stacks. */
+export interface ChronicleLogEntry {
+    readonly category: string;
+    readonly level: ChronicleLogLevel;
+    readonly message: string;
+    /** Safe diagnostic fields, including correlation and valid trace/span identifiers when available. */
+    readonly attributes: Readonly<Attributes>;
+}

package/logging/ChronicleLogLevel.ts

@@ -0,0 +1,11 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** Severity of a Chronicle diagnostic. */
+export enum ChronicleLogLevel {
+    Verbose = 'verbose',
+    Debug = 'debug',
+    Info = 'info',
+    Warn = 'warn',
+    Error = 'error'
+}

package/logging/DiagChronicleLogger.ts

@@ -0,0 +1,13 @@
+// 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 type { IChronicleLogger } from './IChronicleLogger.js';
+import type { ChronicleLogEntry } from './ChronicleLogEntry.js';
+
+/** Compatibility adapter used when no application logger is supplied during the minor-release overlap. */
+export class DiagChronicleLogger implements IChronicleLogger {
+    log(entry: ChronicleLogEntry): void {
+        diag.createComponentLogger({ namespace: entry.category })[entry.level](entry.message, entry.attributes);
+    }
+}

package/logging/IChronicleLogger.ts

@@ -0,0 +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 type { ChronicleLogEntry } from './ChronicleLogEntry.js';
+
+/** Application-owned diagnostic sink, configured separately for each Chronicle client. */
+export interface IChronicleLogger {
+    /** Receives one sanitized diagnostic. Implementations should not throw. */
+    log(entry: ChronicleLogEntry): void;
+}