@cratis/chronicle 6.33.0 → 6.34.0

package/reactors/for_Reactors/when_delivering/with_activation.spec.ts

@@ -4,7 +4,8 @@
 import { EventContext as WireContext, EventObservationState, EventType, ObservationState, type ReactorMessage } from '@cratis/chronicle.contracts';
 import { ReplayState } from '../../../index.js';
 import { chai, describe, it, vi } from 'vitest';
-import { diag, DiagLogLevel, type DiagLogger } from '@opentelemetry/api';
+import type { IChronicleLogger } from '../../../logging/IChronicleLogger.js';
+import type { ChronicleLogEntry } from '../../../logging/ChronicleLogEntry.js';
 import type { ChronicleConnection } from '../../../connection/index.js';
 import { ConnectionLifecycle } from '../../../connection/ConnectionLifecycle.js';
 import type { IClientArtifactsProvider } from '../../../artifacts/IClientArtifactsProvider.js';
@@ -98,7 +99,7 @@ function delivery(events: ReturnType<typeof event>[], replayState = ReplayState.
 }
 
 async function observe(type: Function, batches: ReturnType<typeof delivery>[], namespace = 'tenant-a',
-    activator?: ClientArtifactsActivator, appendResult = true, onAppendMany?: () => void) {
+    activator?: ClientArtifactsActivator, appendResult = true, onAppendMany?: () => void, logger?: IChronicleLogger) {
     const acknowledgements: NonNullable<ReactorMessage['Content']>['Value1'][] = [];
     const append = vi.fn().mockResolvedValue({ isSuccess: appendResult });
     const appendMany = vi.fn().mockImplementation(async () => {
@@ -122,7 +123,7 @@ async function observe(type: Function, batches: ReturnType<typeof delivery>[], n
         await lifecycle.disconnected(error => { throw error; });
         finished();
     }
-    const connection = { reactors: { observe: stream } } as unknown as ChronicleConnection;
+    const connection = { logger, reactors: { observe: stream } } as unknown as ChronicleConnection;
     const artifacts = { reactors: [type], eventTypes: [ActivationEvent] } as unknown as IClientArtifactsProvider;
     await new Reactors(artifacts, connection, 'store', namespace, lifecycle, eventLog, undefined, store, activator).register();
     await complete;
@@ -462,16 +463,15 @@ describe('when delivering reactor batches', () => {
     });
 
     it('should log disposal failure without changing successful acknowledgement', async () => {
-        const errors: string[] = [];
-        diag.setLogger({ error: (...values: unknown[]) => { errors.push(values.map(String).join(' ')); } } as DiagLogger, DiagLogLevel.ERROR);
-        try {
-            const activator: ClientArtifactsActivator = type => ({ instance: new type(), dispose: async () => { throw new Error('cleanup'); } });
-            const result = await observe(ActivationReactor, [delivery([event('live', 1n)])], 'tenant-a', activator);
-            result.acknowledgements[0]?.State.should.equal(ObservationState.Success);
-            result.acknowledgements[0]?.LastSuccessfulObservation.should.equal(1n);
-            errors.some(value => value.includes('Error disposing activated artifact')).should.be.true;
-        } finally {
-            diag.disable();
-        }
+        const entries: ChronicleLogEntry[] = [];
+        const activator: ClientArtifactsActivator = type => ({ instance: new type(), dispose: async () => { throw new Error('private cleanup details'); } });
+        const result = await observe(ActivationReactor, [delivery([event('private payload', 1n)])], 'tenant-a', activator,
+            true, undefined, { log: entry => entries.push(entry) });
+        result.acknowledgements[0]?.State.should.equal(ObservationState.Success);
+        result.acknowledgements[0]?.LastSuccessfulObservation.should.equal(1n);
+        entries.filter(entry => entry.attributes['exception.type'] === 'Error').should.have.lengthOf(1);
+        JSON.stringify(entries).should.not.contain('private cleanup details');
+        JSON.stringify(entries).should.not.contain('private payload');
+        JSON.stringify(entries).should.not.contain('book-1');
     });
 });

package/reducers/Reducers.ts

@@ -2,7 +2,8 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 import 'reflect-metadata';
-import { diag } from '@opentelemetry/api';
+import { createLogger } from '../logging/createLogger.js';
+import { runInBackgroundContext } from '../telemetry/runInBackgroundContext.js';
 import { Constructor } from '@cratis/fundamentals';
 import { ObservationState, ReadModelObserverType, ReducerMessage, ReplayState } from '@cratis/chronicle.contracts';
 import { IClientArtifactsProvider } from '../artifacts/index.js';
@@ -102,7 +103,7 @@ export class Reducers implements IReducers {
     /** How long to wait before re-establishing an observation whose stream ended. */
     private static readonly _reobserveDelayMs = 2000;
 
-    private readonly _logger = diag.createComponentLogger({ namespace: '@cratis/chronicle/reducers' });
+    private readonly _logger: ReturnType<typeof createLogger>;
     private readonly _lifecycle: ConnectionLifecycle;
     private readonly _reducers = new Map<string, Constructor>();
     private readonly _queues = new Map<string, AsyncQueue<ReducerMessage>>();
@@ -133,6 +134,7 @@ export class Reducers implements IReducers {
         private readonly _artifactActivator?: ClientArtifactsActivator,
         private readonly _readModelNamingPolicy?: ReadModelNamingPolicy
     ) {
+        this._logger = createLogger('@cratis/chronicle/reducers', _connection.logger);
         this._lifecycle = lifecycle;
         lifecycle.onDisconnected(async () => {
             this._logger.info('Disconnected — stopping all reducer observations');
@@ -235,21 +237,23 @@ export class Reducers implements IReducers {
     }
 
     private startObservation(id: string, reducerType: Constructor): void {
-        if (this._disposed) return;
-        const metadata = getReducerMetadata(reducerType)!;
-        const eventSequenceId = metadata.eventSequenceId ?? EventSequenceId.eventLog.value;
-        const dispatcher = new ReducerEventDispatcher(reducerType, this._clientArtifacts.eventTypes);
-        const readModelName = this.getReducerReadModelIdentifier(reducerType);
-
-        this._logger.info('Starting reducer observation', {
-            reducerId: id,
-            eventSequenceId,
-            readModel: readModelName,
-            handlerCount: dispatcher.handlers.length,
-            handlers: dispatcher.handlers.map(e => e.methodName)
-        });
+        runInBackgroundContext(() => {
+            if (this._disposed) return;
+            const metadata = getReducerMetadata(reducerType)!;
+            const eventSequenceId = metadata.eventSequenceId ?? EventSequenceId.eventLog.value;
+            const dispatcher = new ReducerEventDispatcher(reducerType, this._clientArtifacts.eventTypes);
+            const readModelName = this.getReducerReadModelIdentifier(reducerType);
 
-        void this.runObservation(id, reducerType, eventSequenceId, readModelName, dispatcher);
+            this._logger.info('Starting reducer observation', {
+                reducerId: id,
+                eventSequenceId,
+                readModel: readModelName,
+                handlerCount: dispatcher.handlers.length,
+                handlers: dispatcher.handlers.map(e => e.methodName)
+            });
+
+            void this.runObservation(id, reducerType, eventSequenceId, readModelName, dispatcher);
+        });
     }
 
     private async runObservation(
@@ -262,7 +266,7 @@ export class Reducers implements IReducers {
         try {
             await this.observeReducer(id, reducerType, eventSequenceId, readModelName, dispatcher);
         } catch (error) {
-            this._logger.error('Reducer observation loop exited with error', { reducerId: id, error: String(error) });
+            this._logger.error('Reducer observation loop exited with error', { reducerId: id, error });
         }
 
         this.scheduleReobserve(id, reducerType);
@@ -285,14 +289,14 @@ export class Reducers implements IReducers {
             return;
         }
 
-        const handle = setTimeout(() => {
+        const handle = runInBackgroundContext(() => setTimeout(() => {
             if (!this._registered || this._disposed) {
                 return;
             }
 
             this._logger.info('Re-establishing reducer observation', { reducerId: id });
             this.startObservation(id, reducerType);
-        }, Reducers._reobserveDelayMs);
+        }, Reducers._reobserveDelayMs));
 
         handle.unref?.();
     }
@@ -359,7 +363,6 @@ export class Reducers implements IReducers {
 
                 this._logger.debug('Received reduce operation', {
                     reducerId: id,
-                    partition: operation.Partition,
                     count: operation.Events.length,
                     hasInitialState: operation.InitialState !== '',
                     replayState: operation.ReplayState
@@ -375,12 +378,12 @@ export class Reducers implements IReducers {
                             replayState: operation.ReplayState
                         }, this._artifactActivator, artifact => runActivated(artifact, () =>
                             notifyReplayLifecycle(artifact.instance, operation.ReplayState, operation.Partition),
-                            { delivery: ArtifactDelivery.ReplayNotification, replayState: operation.ReplayState }));
+                            { delivery: ArtifactDelivery.ReplayNotification, replayState: operation.ReplayState }), this._connection.logger);
                     } else if (reducerInstance) {
                         await notifyReplayLifecycle(reducerInstance, operation.ReplayState, operation.Partition);
                     }
                 } catch (err) {
-                    this._logger.error('Error notifying reducer of replay lifecycle transition', { reducerId: id, error: String(err) });
+                    this._logger.error('Error notifying reducer of replay lifecycle transition', { reducerId: id, error: err });
                     if (err instanceof ArtifactCompletionFailed && err.processingError !== undefined) {
                         exceptionMessages.push(String(err.processingError));
                     }
@@ -424,7 +427,7 @@ export class Reducers implements IReducers {
                                 { delivery: ArtifactDelivery.Events, eventContext: context, methodName: entry.methodName });
                             lastSuccessfullyObservedEvent = event.Context!.SequenceNumber;
                         } catch (err) {
-                            this._logger.error('Error handling event in reducer', { reducerId: id, error: String(err) });
+                            this._logger.error('Error handling event in reducer', { reducerId: id, error: err });
                             exceptionMessages.push(String(err));
                             exceptionStackTrace = err instanceof Error ? (err.stack ?? '') : '';
                             state = ObservationState.Failed;
@@ -445,9 +448,9 @@ export class Reducers implements IReducers {
                             readModels: this._eventStore.readModels, eventSequenceId, partition: operation.Partition,
                             signal: controller.signal, delivery: ArtifactDelivery.Events,
                             eventContext: toClientEventContext(firstInvocableEvent.Context!)
-                        }, this._artifactActivator, processEvents);
+                        }, this._artifactActivator, processEvents, this._connection.logger);
                     } catch (err) {
-                        this._logger.error('Error activating reducer', { reducerId: id, error: String(err) });
+                        this._logger.error('Error activating reducer', { reducerId: id, error: err });
                         exceptionMessages.push(String(err));
                         const completionStack = err instanceof Error ? (err.stack ?? '') : '';
                         exceptionStackTrace = err instanceof ArtifactCompletionFailed && exceptionStackTrace
@@ -483,7 +486,7 @@ export class Reducers implements IReducers {
             if (!this._queues.has(id)) {
                 this._logger.debug('Reducer observation stream closed cleanly', { reducerId: id });
             } else {
-                this._logger.error('Reducer observation stream ended unexpectedly', { reducerId: id, error: String(err) });
+                this._logger.error('Reducer observation stream ended unexpectedly', { reducerId: id, error: err });
             }
         } finally {
             // Only retire our own queue: a reconnect can already have replaced it,

package/seeding/EventSeeding.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 { IClientArtifactsProvider } from '../artifacts/index.js';
 import { ChronicleConnection } from '../connection/index.js';
 import { ensureCommandSuccess } from '../connection/callResults.js';
@@ -27,7 +27,7 @@ interface SeedingEntry {
  * with the Chronicle Kernel.
  */
 export class EventSeeding implements IEventSeeding {
-    private readonly _logger = diag.createComponentLogger({ namespace: '@cratis/chronicle/EventSeeding' });
+    private readonly _logger: ReturnType<typeof createLogger>;
     private readonly _entries: SeedingEntry[] = [];
 
     /**
@@ -40,7 +40,9 @@ export class EventSeeding implements IEventSeeding {
         private readonly _eventStoreName: string,
         private readonly _connection: ChronicleConnection,
         private readonly _clientArtifacts: IClientArtifactsProvider
-    ) {}
+    ) {
+        this._logger = createLogger('@cratis/chronicle/EventSeeding', _connection.logger);
+    }
 
     /** @inheritdoc */
     for<TEvent extends object>(eventSourceId: string, events: Iterable<TEvent>): IEventSeedingBuilder {
@@ -69,7 +71,7 @@ export class EventSeeding implements IEventSeeding {
             } catch (error) {
                 this._logger.warn('Failed to activate or execute event seeder - skipping seeder', {
                     seederType: seederType.name,
-                    error: String(error)
+                    error
                 });
             }
         }

package/telemetry/ChronicleTelemetryOptions.ts

@@ -0,0 +1,8 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** Per-client privacy settings; instrumentation itself is always available. */
+export interface ChronicleTelemetryOptions {
+    /** Absent means no event source identifiers. HMAC uses SHA-256 and a deployment-owned key. */
+    eventSourceId?: { mode: 'raw' } | { mode: 'hmac'; key: Uint8Array };
+}

package/telemetry/for_ChronicleTelemetry/given/a_telemetry_session.fixture.ts

@@ -0,0 +1,36 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeAll, beforeEach, afterAll } from 'vitest';
+import { context, metrics, propagation, trace } from '@opentelemetry/api';
+import { AsyncLocalStorageContextManager } from '@opentelemetry/context-async-hooks';
+import { CompositePropagator, W3CBaggagePropagator, W3CTraceContextPropagator } from '@opentelemetry/core';
+import { BasicTracerProvider, InMemorySpanExporter, SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base';
+import { InMemoryMetricExporter, MeterProvider, PeriodicExportingMetricReader, AggregationTemporality } from '@opentelemetry/sdk-metrics';
+
+/** In-process providers only; no export outside the spec process. */
+export function telemetrySession() {
+    const spans = new InMemorySpanExporter();
+    const traces = new BasicTracerProvider({ spanProcessors: [new SimpleSpanProcessor(spans)] });
+    const metricExporter = new InMemoryMetricExporter(AggregationTemporality.CUMULATIVE);
+    const reader = new PeriodicExportingMetricReader({ exporter: metricExporter, exportIntervalMillis: 60000 });
+    const meters = new MeterProvider({ readers: [reader] });
+    const contextManager = new AsyncLocalStorageContextManager();
+    beforeAll(() => {
+        context.setGlobalContextManager(contextManager.enable());
+        trace.setGlobalTracerProvider(traces);
+        metrics.setGlobalMeterProvider(meters);
+        propagation.setGlobalPropagator(new CompositePropagator({ propagators: [new W3CTraceContextPropagator(), new W3CBaggagePropagator()] }));
+    });
+    beforeEach(() => spans.reset());
+    afterAll(async () => {
+        await traces.shutdown();
+        await meters.shutdown();
+        context.disable();
+        trace.disable();
+        metrics.disable();
+        propagation.disable();
+        contextManager.disable();
+    });
+    return { spans, traces, reader };
+}

package/telemetry/for_ChronicleTelemetry/given/an_event_sequence.fixture.ts

@@ -0,0 +1,29 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { vi } from 'vitest';
+import { EventSequence } from '../../../eventSequences/EventSequence.js';
+import { EventSequenceId } from '../../../eventSequences/EventSequenceId.js';
+import { eventType } from '../../../events/eventTypeDecorator.js';
+import type { ChronicleConnection } from '../../../connection/ChronicleConnection.js';
+import type { IUnitOfWorkManager } from '../../../transactions/IUnitOfWorkManager.js';
+import type { ChronicleTelemetryOptions } from '../../ChronicleTelemetryOptions.js';
+
+export class Recorded { constructor(readonly value = 'sensitive payload') {} }
+eventType('telemetry-recorded')(Recorded);
+
+export function eventSequence(telemetry?: ChronicleTelemetryOptions) {
+    const services = {
+        append: vi.fn().mockResolvedValue({ Response: { SequenceNumber: 42n } }),
+        appendManyForEventSources: vi.fn().mockResolvedValue({ Response: { SequenceNumbers: [42n, 43n] } }),
+        tailSequenceNumber: vi.fn().mockResolvedValue({ IsAuthorized: true, Data: { SequenceNumber: 42n } }),
+        hasEventsForEventSourceId: vi.fn().mockResolvedValue({ IsAuthorized: true, Data: { HasEvents: true } }),
+        forEventSourceIdAndEventTypes: vi.fn().mockResolvedValue({ IsAuthorized: true, Data: [] }),
+        fromSequenceNumber: vi.fn().mockResolvedValue({ IsAuthorized: true, Data: [] }),
+        redact: vi.fn().mockResolvedValue({}),
+        redactForEventSource: vi.fn().mockResolvedValue({})
+    };
+    const connection = { eventSequences: services } as unknown as ChronicleConnection;
+    return { services, sequence: new EventSequence(EventSequenceId.eventLog, 'store', 'namespace', connection,
+        {} as IUnitOfWorkManager, undefined, telemetry) };
+}

package/telemetry/for_ChronicleTelemetry/when_appending/with_shared_and_legacy_attributes.spec.ts

@@ -0,0 +1,58 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it } from 'vitest';
+import { SpanKind, context, propagation } from '@opentelemetry/api';
+import type { ReadableSpan } from '@opentelemetry/sdk-trace-base';
+import { telemetrySession } from '../given/a_telemetry_session.fixture.js';
+import { eventSequence, Recorded } from '../given/an_event_sequence.fixture.js';
+import { clientVersion } from '../../../connection/clientVersion.js';
+import { CorrelationId, correlationIdManager } from '../../../correlation/index.js';
+
+const should = chai.should();
+const telemetry = telemetrySession();
+const correlation = '95bd1c83-de97-45f7-84a0-fb462af14d0c';
+
+describe('when appending with a business correlation override', () => {
+    let span: ReadableSpan;
+    let injectedCorrelation: string | undefined;
+    beforeEach(async () => {
+        const { sequence, services } = eventSequence();
+        services.append.mockImplementation(async () => {
+            await Promise.resolve();
+            injectedCorrelation = propagation.getBaggage(context.active())?.getEntry('cratis.correlation_id')?.value;
+            return { Response: { SequenceNumber: 42n } };
+        });
+        await correlationIdManager.run(new CorrelationId('outer'), () => sequence.append('sensitive-id', new Recorded(), { correlationId: correlation }));
+        span = telemetry.spans.getFinishedSpans()[0];
+    });
+    it('should produce one client span with the unchanged operation name', () => {
+        telemetry.spans.getFinishedSpans().should.have.lengthOf(1);
+        span.kind.should.equal(SpanKind.CLIENT);
+        span.name.should.equal('chronicle.event_sequences.append');
+    });
+    it('should use the versioned shared instrumentation scope', () => {
+        span.instrumentationScope.name.should.equal('Cratis.Chronicle.Client');
+        should.equal(span.instrumentationScope.version, clientVersion);
+    });
+    it('should emit both registries on the same span', () => {
+        span.attributes.should.include({
+            'cratis.event_store.name': 'store', 'chronicle.event_store': 'store',
+            'cratis.event_store.namespace': 'namespace', 'chronicle.namespace': 'namespace',
+            'cratis.event_sequence.id': 'event-log', 'chronicle.event_sequence_id': 'event-log',
+            'cratis.event_type.id': 'telemetry-recorded', 'chronicle.event_type_id': 'telemetry-recorded',
+            'cratis.event_type.generation': 1, 'chronicle.event_type_generation': 1,
+            'cratis.event_sequence.number': 42, 'chronicle.sequence_number': '42'
+        });
+    });
+    it('should scope the resolved correlation consistently for propagation', () => {
+        should.equal(span.attributes['cratis.correlation_id'], correlation);
+        should.equal(injectedCorrelation, correlation);
+        should.equal(correlationIdManager.scoped, undefined);
+    });
+    it('should not record identifiers or payloads by default', () => {
+        JSON.stringify(span.attributes).should.not.contain('sensitive');
+        should.equal(span.attributes['cratis.event_source.id'], undefined);
+        should.equal(span.attributes['chronicle.event_source_id'], undefined);
+    });
+});

package/telemetry/for_ChronicleTelemetry/when_appending/without_an_sdk.spec.ts

@@ -0,0 +1,15 @@
+// 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 { eventSequence, Recorded } from '../given/an_event_sequence.fixture.js';
+
+chai.should();
+describe('when appending without an OpenTelemetry SDK', () => {
+    it('should preserve append behavior without telemetry setup', async () => {
+        const { sequence, services } = eventSequence();
+        const result = await sequence.append('source', new Recorded());
+        result.sequenceNumber.value.should.equal(42n);
+        services.append.mock.calls.should.have.lengthOf(1);
+    });
+});

package/telemetry/for_ChronicleTelemetry/when_documenting/with_public_names.spec.ts

@@ -0,0 +1,15 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { readFileSync } from 'node:fs';
+import { chai, describe, it } from 'vitest';
+import { WellKnownTelemetryNames } from '../../../WellKnownTelemetryNames.js';
+import { telemetryReference } from '../../../scripts/telemetry-reference.mjs';
+
+chai.should();
+describe('when publishing the telemetry reference', () => {
+    it('should keep the documented registry identical to the public constants', () => {
+        const documentation = readFileSync(new URL('../../../../Documentation/observability.md', import.meta.url), 'utf8');
+        documentation.should.contain(telemetryReference(WellKnownTelemetryNames));
+    });
+});

package/telemetry/for_ChronicleTelemetry/when_recording_failures/with_sensitive_exception_details.spec.ts

@@ -0,0 +1,34 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it } from 'vitest';
+import { SpanStatusCode } from '@opentelemetry/api';
+import type { ReadableSpan } from '@opentelemetry/sdk-trace-base';
+import { telemetrySession } from '../given/a_telemetry_session.fixture.js';
+import { eventSequence, Recorded } from '../given/an_event_sequence.fixture.js';
+
+chai.should();
+const telemetry = telemetrySession();
+
+describe('when an append fails with sensitive exception details', () => {
+    const failure = new TypeError('sensitive token in error message');
+    let span: ReadableSpan;
+    let thrown: unknown;
+    beforeEach(async () => {
+        const { sequence, services } = eventSequence();
+        services.append.mockRejectedValue(failure);
+        try { await sequence.append('private', new Recorded()); } catch (error) { thrown = error; }
+        span = telemetry.spans.getFinishedSpans()[0];
+    });
+    it('should rethrow the original failure', () => { (thrown === failure).should.be.true; });
+    it('should record only failure types and error status', () => {
+        span.status.should.deep.equal({ code: SpanStatusCode.ERROR });
+        span.attributes.should.include({ 'error.type': 'TypeError' });
+        span.events.should.have.lengthOf(1);
+        span.events[0].attributes!.should.deep.equal({ 'exception.type': 'TypeError' });
+    });
+    it('should never export the exception message or stack', () => {
+        JSON.stringify({ attributes: span.attributes, status: span.status, events: span.events }).should.not.contain('sensitive');
+        span.events[0].attributes!.should.not.have.property('exception.stacktrace');
+    });
+});

package/telemetry/for_ChronicleTelemetry/when_recording_identifiers/with_per_client_privacy.spec.ts

@@ -0,0 +1,92 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { createHmac } from 'node:crypto';
+import { beforeEach, chai, describe, it } from 'vitest';
+import { telemetrySession } from '../given/a_telemetry_session.fixture.js';
+import { eventSequence, Recorded } from '../given/an_event_sequence.fixture.js';
+import { EventSequenceNumber } from '../../../eventSequences/EventSequenceNumber.js';
+import { ChronicleOptions } from '../../../ChronicleOptions.js';
+import type { ChronicleTelemetryOptions } from '../../ChronicleTelemetryOptions.js';
+
+const should = chai.should();
+const telemetry = telemetrySession();
+const source = 'sensitive-source';
+const key = new Uint8Array([10, 20, 30, 40]);
+
+for (const [label, policy, expected] of [
+    ['absent', undefined, undefined],
+    ['raw', { eventSourceId: { mode: 'raw' } }, source],
+    ['hmac', { eventSourceId: { mode: 'hmac', key } }, createHmac('sha256', key).update(source).digest('hex')]
+] as const) {
+    describe(`when recording event source identifiers with ${label} privacy`, () => {
+        beforeEach(async () => {
+            const { sequence, services } = eventSequence(policy as ChronicleTelemetryOptions | undefined);
+            await sequence.append(source, new Recorded());
+            await sequence.appendMany(source, [new Recorded(), new Recorded()]);
+            await sequence.appendMany([{ eventSourceId: source, event: new Recorded() }, { eventSourceId: source, event: new Recorded() }]);
+            await sequence.getTailSequenceNumber(source);
+            await sequence.hasEventsFor(source);
+            await sequence.getForEventSourceIdAndEventTypes(source, [Recorded]);
+            await sequence.getFromSequenceNumber(new EventSequenceNumber(1n), source);
+            await sequence.redactForEventSource(source, 'private reason');
+            services.append.mock.calls[0][0].EventSourceId.should.equal(source);
+        });
+        it('should apply the policy equally to both names on every operation', () => {
+            telemetry.spans.getFinishedSpans().should.have.lengthOf(8);
+            for (const span of telemetry.spans.getFinishedSpans()) {
+                should.equal(span.attributes['cratis.event_source.id'], expected);
+                should.equal(span.attributes['chronicle.event_source_id'], expected);
+            }
+        });
+    });
+}
+
+describe('when a validated telemetry policy is later mutated by an untyped caller', () => {
+    beforeEach(async () => {
+        const options = ChronicleOptions.development({ telemetry: { eventSourceId: { mode: 'hmac', key } } });
+        Object.assign(options.telemetry!.eventSourceId!, { key: undefined });
+        const { sequence, services } = eventSequence(options.telemetry);
+        await sequence.append(source, new Recorded());
+        await sequence.getTailSequenceNumber(source);
+        await sequence.redactForEventSource(source, 'reason');
+        services.append.mock.calls.should.have.lengthOf(1);
+        services.tailSequenceNumber.mock.calls.should.have.lengthOf(1);
+        services.redactForEventSource.mock.calls.should.have.lengthOf(1);
+    });
+    it('should omit the failed enrichment without failing business calls or leaving spans open', () => {
+        telemetry.spans.getFinishedSpans().should.have.lengthOf(3);
+        for (const span of telemetry.spans.getFinishedSpans()) {
+            span.attributes.should.not.have.property('cratis.event_source.id');
+            span.attributes.should.not.have.property('chronicle.event_source_id');
+        }
+    });
+});
+
+describe('when appending a batch with multiple event sources', () => {
+    beforeEach(async () => {
+        await eventSequence({ eventSourceId: { mode: 'raw' } }).sequence.appendMany([
+            { eventSourceId: 'first', event: new Recorded() }, { eventSourceId: 'second', event: new Recorded() }
+        ]);
+    });
+    it('should record the count without an identifier array', () => {
+        const attributes = telemetry.spans.getFinishedSpans()[0].attributes;
+        attributes.should.include({ 'cratis.event.count': 2, 'chronicle.events_count': 2 });
+        should.equal(attributes['cratis.event_source.id'], undefined);
+        should.equal(attributes['chronicle.event_source_id'], undefined);
+    });
+});
+
+describe('when clients use different identifier policies concurrently', () => {
+    beforeEach(async () => {
+        await Promise.all([
+            eventSequence().sequence.append(source, new Recorded()),
+            eventSequence({ eventSourceId: { mode: 'raw' } }).sequence.append(source, new Recorded()),
+            eventSequence({ eventSourceId: { mode: 'hmac', key } }).sequence.append(source, new Recorded())
+        ]);
+    });
+    it('should keep each policy local to its client', () => {
+        const identifiers = telemetry.spans.getFinishedSpans().map(span => span.attributes['cratis.event_source.id']);
+        identifiers.should.have.members([undefined, source, createHmac('sha256', key).update(source).digest('hex')]);
+    });
+});

package/telemetry/for_ChronicleTelemetry/when_recording_metrics/with_legacy_overlap.spec.ts

@@ -0,0 +1,40 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it } from 'vitest';
+import { telemetrySession } from '../given/a_telemetry_session.fixture.js';
+import { ChronicleMetrics } from '../../../Metrics.js';
+import { clientVersion } from '../../../connection/clientVersion.js';
+import type { ScopeMetrics } from '@opentelemetry/sdk-metrics';
+
+chai.should();
+const telemetry = telemetrySession();
+describe('when recording metrics after installing the SDK', () => {
+    let scope: ScopeMetrics;
+    beforeEach(async () => {
+        // Metrics was imported before provider installation: recording must still reach the SDK.
+        const attributes = { 'chronicle.event_store': 'store', 'chronicle.namespace': 'namespace',
+            'chronicle.event_sequence_id': 'event-log', 'chronicle.events_count': 237 };
+        ChronicleMetrics.batchAppendsPerformed.add(1, attributes);
+        ChronicleMetrics.appendManyDuration.record(250, attributes);
+        scope = (await telemetry.reader.collect()).resourceMetrics.scopeMetrics[0];
+    });
+    it('should use the shared scope and installed version', () => {
+        scope.scope.should.include({ name: 'Cratis.Chronicle.Client', version: clientVersion });
+    });
+    it('should retain legacy milliseconds while emitting seconds', () => {
+        const legacy = scope.metrics.find(metric => metric.descriptor.name === 'chronicle.events.append_many_duration')!;
+        const shared = scope.metrics.find(metric => metric.descriptor.name === 'cratis.chronicle.event_sequence.append_many_duration')!;
+        legacy.descriptor.unit.should.equal('ms');
+        shared.descriptor.unit.should.equal('s');
+        legacy.dataPoints[0].value.should.include({ min: 250, max: 250 });
+        shared.dataPoints[0].value.should.include({ min: 0.25, max: 0.25 });
+    });
+    it('should exclude batch size from only the new metric dimensions', () => {
+        const legacy = scope.metrics.find(metric => metric.descriptor.name === 'chronicle.events.batch_appends')!;
+        const shared = scope.metrics.find(metric => metric.descriptor.name === 'cratis.chronicle.event_sequence.batch_appends')!;
+        legacy.dataPoints[0].attributes.should.have.property('chronicle.events_count', 237);
+        shared.dataPoints[0].attributes.should.deep.equal({ 'cratis.event_store.name': 'store',
+            'cratis.event_store.namespace': 'namespace', 'cratis.event_sequence.id': 'event-log' });
+    });
+});

package/telemetry/for_ChronicleTelemetry/when_recording_sequence_numbers/with_integer_precision.spec.ts

@@ -0,0 +1,23 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { beforeEach, chai, describe, it } from 'vitest';
+import { telemetrySession } from '../given/a_telemetry_session.fixture.js';
+import { eventSequence } from '../given/an_event_sequence.fixture.js';
+
+const should = chai.should();
+const telemetry = telemetrySession();
+for (const [number, expected] of [[42n, 42], [9007199254740991n, Number.MAX_SAFE_INTEGER], [9007199254740992n, undefined], [18446744073709551615n, undefined]] as const) {
+    describe(`when reading sequence number ${number}`, () => {
+        beforeEach(async () => {
+            const { sequence, services } = eventSequence();
+            services.tailSequenceNumber.mockResolvedValue({ IsAuthorized: true, Data: { SequenceNumber: number } });
+            await sequence.getTailSequenceNumber();
+        });
+        it('should keep the legacy string and emit only exactly representable shared integers', () => {
+            const attributes = telemetry.spans.getFinishedSpans()[0].attributes;
+            should.equal(attributes['cratis.event_sequence.number'], expected);
+            should.equal(attributes['chronicle.sequence_number'], number.toString());
+        });
+    });
+}

package/telemetry/observeOperation.ts

@@ -0,0 +1,25 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { context, propagation, SpanKind, type Span } from '@opentelemetry/api';
+import { ChronicleTracer } from '../Tracing.js';
+import { correlationIdManager } from '../correlation/index.js';
+import { CorrelationId } from '../correlation/CorrelationId.js';
+import { WellKnownTelemetryNames } from '../WellKnownTelemetryNames.js';
+
+/** Opens one client span, scoping the resolved business correlation without generating a new one. */
+export function observeOperation<T>(name: string, action: (span: Span) => Promise<T>, correlationId?: { toString(): string }): Promise<T> {
+    const resolved = correlationId ? new CorrelationId(correlationId.toString()) : correlationIdManager.scoped;
+    const run = () => {
+        const active = context.active();
+        const key = WellKnownTelemetryNames.attributes.correlationId;
+        const correlation = resolved?.toString() ?? propagation.getBaggage(active)?.getEntry(key)?.value;
+        const parent = correlation ? propagation.setBaggage(active,
+            (propagation.getBaggage(active) ?? propagation.createBaggage()).setEntry(key, { value: correlation })) : active;
+        return ChronicleTracer.startActiveSpan(name, {
+            kind: SpanKind.CLIENT,
+            attributes: correlation ? { [key]: correlation } : {}
+        }, parent, action);
+    };
+    return resolved ? correlationIdManager.run(resolved, run) : run();
+}

package/telemetry/runInBackgroundContext.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 { context, ROOT_CONTEXT } from '@opentelemetry/api';
+import { correlationIdManager } from '../correlation/index.js';
+
+/** Starts client-owned work without retaining the initiating request's trace or business correlation. */
+export function runInBackgroundContext<T>(action: () => T): T {
+    return context.with(ROOT_CONTEXT, () => correlationIdManager.runWithout(action));
+}