@cratis/chronicle 6.33.0 → 6.34.0

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

package/logging/createLogger.ts

@@ -0,0 +1,50 @@
+// 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, trace, isSpanContextValid, type Attributes } from '@opentelemetry/api';
+import { ClientError, ServerError } from 'nice-grpc-common';
+import { correlationIdManager } from '../correlation/index.js';
+import { WellKnownTelemetryNames } from '../WellKnownTelemetryNames.js';
+import { exceptionType } from '../telemetry/spanAttributes.js';
+import { ChronicleLogLevel } from './ChronicleLogLevel.js';
+import { DiagChronicleLogger } from './DiagChronicleLogger.js';
+import type { IChronicleLogger } from './IChronicleLogger.js';
+
+/** Binds a category to a client-owned sink and adds safe correlation fields. */
+export function createLogger(category: string, sink: IChronicleLogger = new DiagChronicleLogger()) {
+    const log = (level: ChronicleLogLevel) => (message: string, fields: Record<string, unknown> = {}) => {
+        const attributes: Attributes = {};
+        for (const [key, value] of Object.entries(fields)) {
+            if (key === 'error') {
+                attributes['error.type'] = exceptionType(value);
+                attributes['exception.type'] = exceptionType(value);
+                if (value instanceof ClientError || value instanceof ServerError) attributes['rpc.grpc.status_code'] = value.code;
+            } else if (key === 'sequenceNumber') {
+                const number = Number(value);
+                if (Number.isSafeInteger(number)) attributes[WellKnownTelemetryNames.attributes.sequenceNumber] = number;
+            } else if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+                attributes[key] = value;
+            } else if (Array.isArray(value) && value.every(item => typeof item === 'string')) {
+                attributes[key] = value;
+            }
+        }
+        const active = context.active();
+        const correlationKey = WellKnownTelemetryNames.attributes.correlationId;
+        const correlation = correlationIdManager.scoped?.toString() ?? propagation.getBaggage(active)?.getEntry(correlationKey)?.value;
+        if (correlation) attributes[correlationKey] = correlation;
+        const spanContext = trace.getSpanContext(active);
+        if (spanContext && isSpanContextValid(spanContext)) {
+            attributes.trace_id = spanContext.traceId;
+            attributes.span_id = spanContext.spanId;
+        }
+        try {
+            sink.log({ category, level, message, attributes });
+        } catch {
+            // Diagnostics are not the operation's outcome. A broken sink must not change RPCs or acknowledgements.
+        }
+    };
+    return {
+        verbose: log(ChronicleLogLevel.Verbose), debug: log(ChronicleLogLevel.Debug),
+        info: log(ChronicleLogLevel.Info), warn: log(ChronicleLogLevel.Warn), error: log(ChronicleLogLevel.Error)
+    };
+}

package/logging/for_ChronicleLogger/when_logging/with_client_owned_sinks.spec.ts

@@ -0,0 +1,96 @@
+// 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, vi } from 'vitest';
+import { diag, DiagLogLevel } from '@opentelemetry/api';
+import { ClientError, ServerError, Status } from 'nice-grpc-common';
+import { ChronicleClient } from '../../../ChronicleClient.js';
+import { ChronicleOptions } from '../../../ChronicleOptions.js';
+import { createLogger } from '../../createLogger.js';
+import type { ChronicleLogEntry } from '../../ChronicleLogEntry.js';
+import { telemetrySession } from '../../../telemetry/for_ChronicleTelemetry/given/a_telemetry_session.fixture.js';
+import { CorrelationId, correlationIdManager } from '../../../correlation/index.js';
+
+vi.mock('../../../connection/ChronicleConnection.js', () => ({ ChronicleConnection: class { disconnect() {} } }));
+chai.should();
+const telemetry = telemetrySession();
+
+describe('when two clients have different diagnostic sinks', () => {
+    const first: ChronicleLogEntry[] = [];
+    const second: ChronicleLogEntry[] = [];
+    beforeEach(() => {
+        first.length = 0;
+        second.length = 0;
+        const one = new ChronicleClient(ChronicleOptions.development({ discoveryPatterns: [], logger: { log: entry => first.push(entry) } }));
+        const two = new ChronicleClient(ChronicleOptions.development({ discoveryPatterns: [], logger: { log: entry => second.push(entry) } }));
+        one.dispose();
+        two.dispose();
+    });
+    it('should route each diagnostic only to its owning sink', () => {
+        first.should.have.lengthOf(2);
+        second.should.have.lengthOf(2);
+        (first[0] === second[0]).should.be.false;
+    });
+});
+
+describe('when logging in a correlated trace', () => {
+    let entry: ChronicleLogEntry;
+    beforeEach(async () => {
+        const logger = createLogger('test', { log: value => { entry = value; } });
+        await correlationIdManager.run(new CorrelationId('business-id'), () => telemetry.traces.getTracer('host').startActiveSpan('operation', async span => {
+            try { logger.error('Operation failed', { error: new TypeError('secret'), sequenceNumber: 9007199254740992n }); }
+            finally { span.end(); }
+        }));
+    });
+    it('should export error types with business and trace identifiers but no exception details', () => {
+        entry.attributes.should.include({ 'error.type': 'TypeError', 'exception.type': 'TypeError', 'cratis.correlation_id': 'business-id' });
+        entry.attributes.should.have.property('trace_id');
+        entry.attributes.should.have.property('span_id');
+        entry.attributes.should.not.have.property('cratis.event_sequence.number');
+        JSON.stringify(entry).should.not.contain('secret');
+    });
+});
+
+for (const error of [new ClientError('/test', Status.UNAVAILABLE, 'secret'), new ServerError(Status.UNAVAILABLE, 'secret')]) {
+    describe('when logging a gRPC failure', () => {
+        let entry: ChronicleLogEntry;
+        beforeEach(() => {
+            createLogger('test', { log: value => { entry = value; } }).error('Operation failed', { error });
+        });
+        it('should retain the numeric status without exporting sensitive exception details', () => {
+            entry.attributes.should.include({ 'rpc.grpc.status_code': Status.UNAVAILABLE });
+            JSON.stringify(entry).should.not.contain('secret');
+        });
+    });
+}
+
+for (const error of [new DOMException('secret', 'TimeoutError'), new DOMException('secret', 'AbortError'), { code: Status.UNAVAILABLE, message: 'secret' }]) {
+    describe('when logging a non-gRPC error with a numeric code', () => {
+        let entry: ChronicleLogEntry;
+        beforeEach(() => {
+            createLogger('test', { log: value => { entry = value; } }).error('Operation failed', { error });
+        });
+        it('should not label its code as a gRPC status', () => {
+            entry.attributes.should.not.have.property('rpc.grpc.status_code');
+            JSON.stringify(entry).should.not.contain('secret');
+        });
+    });
+}
+
+describe('when no logger is configured during the compatibility period', () => {
+    it('should still deliver sanitized diagnostics to diag', () => {
+        const error = vi.fn();
+        diag.setLogger({ error, warn: vi.fn(), info: vi.fn(), debug: vi.fn(), verbose: vi.fn() }, DiagLogLevel.ERROR);
+        try {
+            createLogger('test').error('Operation failed', { error: new Error('secret') });
+            error.mock.calls.should.have.lengthOf(1);
+            JSON.stringify(error.mock.calls).should.not.contain('secret');
+        } finally { diag.disable(); }
+    });
+});
+
+describe('when a diagnostic sink throws', () => {
+    it('should leave the operation unaffected', () => {
+        (() => createLogger('test', { log: () => { throw new Error('sink failed'); } }).info('Diagnostic')).should.not.throw();
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cratis/chronicle",
-    "version": "6.33.0",
+    "version": "6.34.0",
     "description": "Event sourcing for TypeScript and Node.js — the idiomatic client for Cratis Chronicle, the open-source event-sourcing database",
     "author": "Cratis",
     "license": "MIT",
@@ -184,6 +184,12 @@
     },
     "devDependencies": {
         "@cratis/fundamentals": "7.20.0",
+        "@opentelemetry/context-async-hooks": "2.11.0",
+        "@opentelemetry/core": "2.11.0",
+        "@opentelemetry/instrumentation-grpc": "0.222.0",
+        "@opentelemetry/instrumentation-http": "0.222.0",
+        "@opentelemetry/sdk-metrics": "2.11.0",
+        "@opentelemetry/sdk-trace-base": "2.11.0",
         "@types/node": "^26.6.3",
         "@typescript/native": "npm:typescript@^7.0.2",
         "esbuild": "^0.28.2",

package/projections/Projections.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 { ProjectionOwner, type ProjectionDefinition } from '@cratis/chronicle.contracts';
 import { Constructor, Guid } from '@cratis/fundamentals';
 import { IClientArtifactsProvider } from '../artifacts/index.js';
@@ -36,7 +36,7 @@ export class Projections implements IProjections {
     private readonly _modelBound = new Map<string, Constructor>();
     private readonly _failedPartitions: FailedPartitions;
 
-    private readonly _logger = diag.createComponentLogger({ namespace: '@cratis/chronicle/projections' });
+    private readonly _logger: ReturnType<typeof createLogger>;
 
     /**
      * Creates a new {@link Projections} instance.
@@ -55,6 +55,7 @@ export class Projections implements IProjections {
         private readonly _defaultSinkTypeId: string,
         private readonly _readModelNamingPolicy?: ReadModelNamingPolicy
     ) {
+        this._logger = createLogger('@cratis/chronicle/projections', _connection.logger);
         this._failedPartitions = new FailedPartitions(_eventStore, _namespace, _connection);
     }
 
@@ -296,7 +297,7 @@ export class Projections implements IProjections {
                     identifier,
                     attempt,
                     nextAttemptInMs: delay,
-                    error: msg
+                    error
                 });
                 await new Promise(resolve => setTimeout(resolve, delay));
                 delay = Math.min(delay * 2, 15000);

package/reactors/Reactors.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, ReactorMessage, ReplayState } from '@cratis/chronicle.contracts';
 import { IClientArtifactsProvider } from '../artifacts/index.js';
@@ -102,7 +103,7 @@ export class Reactors implements IReactors {
     /** 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/reactors' });
+    private readonly _logger: ReturnType<typeof createLogger>;
     private readonly _lifecycle: ConnectionLifecycle;
     private readonly _reactors = new Map<string, Constructor>();
     private readonly _queues = new Map<string, AsyncQueue<ReactorMessage>>();
@@ -130,6 +131,7 @@ export class Reactors implements IReactors {
         private readonly _eventStore?: IEventStore,
         private readonly _artifactActivator?: ClientArtifactsActivator
     ) {
+        this._logger = createLogger('@cratis/chronicle/reactors', _connection.logger);
         this._lifecycle = lifecycle;
         lifecycle.onDisconnected(async () => {
             this._logger.info('Disconnected — stopping all reactor observations');
@@ -177,19 +179,21 @@ export class Reactors implements IReactors {
     }
 
     private startObservation(id: string, reactorType: Constructor): void {
-        if (this._disposed) return;
-        const metadata = getReactorMetadata(reactorType)!;
-        const eventSequenceId = metadata.eventSequenceId ?? EventSequenceId.eventLog.value;
-        const eventTypes = getReactorEventTypes(reactorType, this._clientArtifacts.eventTypes);
-
-        this._logger.info('Starting reactor observation', {
-            reactorId: id,
-            eventSequenceId,
-            handlerCount: eventTypes.length,
-            handlers: eventTypes.map(e => e.methodName)
+        runInBackgroundContext(() => {
+            if (this._disposed) return;
+            const metadata = getReactorMetadata(reactorType)!;
+            const eventSequenceId = metadata.eventSequenceId ?? EventSequenceId.eventLog.value;
+            const eventTypes = getReactorEventTypes(reactorType, this._clientArtifacts.eventTypes);
+
+            this._logger.info('Starting reactor observation', {
+                reactorId: id,
+                eventSequenceId,
+                handlerCount: eventTypes.length,
+                handlers: eventTypes.map(e => e.methodName)
+            });
+
+            void this.runObservation(id, reactorType, eventSequenceId, eventTypes);
         });
-
-        void this.runObservation(id, reactorType, eventSequenceId, eventTypes);
     }
 
     private async runObservation(
@@ -201,7 +205,7 @@ export class Reactors implements IReactors {
         try {
             await this.observeReactor(id, reactorType, eventSequenceId, eventTypes);
         } catch (error) {
-            this._logger.error('Reactor observation loop exited with error', { reactorId: id, error: String(error) });
+            this._logger.error('Reactor observation loop exited with error', { reactorId: id, error });
         }
 
         this.scheduleReobserve(id, reactorType);
@@ -223,14 +227,14 @@ export class Reactors implements IReactors {
             return;
         }
 
-        const handle = setTimeout(() => {
+        const handle = runInBackgroundContext(() => setTimeout(() => {
             if (!this._registered || this._disposed) {
                 return;
             }
 
             this._logger.info('Re-establishing reactor observation', { reactorId: id });
             this.startObservation(id, reactorType);
-        }, Reactors._reobserveDelayMs);
+        }, Reactors._reobserveDelayMs));
 
         handle.unref?.();
     }
@@ -286,7 +290,6 @@ export class Reactors implements IReactors {
 
                 this._logger.debug('Received events to observe', {
                     reactorId: id,
-                    partition: eventsToObserve.Partition,
                     count: eventsToObserve.Events.length,
                     replayState: eventsToObserve.ReplayState
                 });
@@ -301,12 +304,12 @@ export class Reactors implements IReactors {
                             replayState: eventsToObserve.ReplayState
                         }, this._artifactActivator, artifact => runActivated(artifact, () =>
                             notifyReplayLifecycle(artifact.instance, eventsToObserve.ReplayState, eventsToObserve.Partition),
-                            { delivery: ArtifactDelivery.ReplayNotification, replayState: eventsToObserve.ReplayState }));
+                            { delivery: ArtifactDelivery.ReplayNotification, replayState: eventsToObserve.ReplayState }), this._connection.logger);
                     } else if (reactorInstance) {
                         await notifyReplayLifecycle(reactorInstance, eventsToObserve.ReplayState, eventsToObserve.Partition);
                     }
                 } catch (err) {
-                    this._logger.error('Error notifying reactor of replay lifecycle transition', { reactorId: id, error: String(err) });
+                    this._logger.error('Error notifying reactor of replay lifecycle transition', { reactorId: id, error: err });
                     if (err instanceof ArtifactCompletionFailed && err.processingError !== undefined) {
                         exceptionMessages.push(String(err.processingError));
                     }
@@ -348,7 +351,6 @@ export class Reactors implements IReactors {
                             }
 
                             const content = JSON.parse(event.Content) as Record<string, unknown>;
-                            this._logger.debug('Event content', { reactorId: id, eventTypeId, contentKeys: Object.keys(content), rawContent: event.Content.substring(0, 200) });
                             const context = toClientEventContext(event.Context!);
 
                             this._logger.info('Invoking reactor handler', {
@@ -364,7 +366,7 @@ export class Reactors implements IReactors {
 
                             lastSuccessfullyObservedEvent = event.Context!.SequenceNumber;
                         } catch (err) {
-                            this._logger.error('Error handling event in reactor', { reactorId: id, error: String(err) });
+                            this._logger.error('Error handling event in reactor', { reactorId: id, error: err });
                             exceptionMessages.push(String(err));
                             exceptionStackTrace = err instanceof Error ? (err.stack ?? '') : '';
                             state = ObservationState.Failed;
@@ -386,9 +388,9 @@ export class Reactors implements IReactors {
                             readModels: services.readModels, eventSequenceId, partition: eventsToObserve.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 reactor', { reactorId: id, error: String(err) });
+                        this._logger.error('Error activating reactor', { reactorId: id, error: err });
                         exceptionMessages.push(String(err));
                         const completionStack = err instanceof Error ? (err.stack ?? '') : '';
                         exceptionStackTrace = err instanceof ArtifactCompletionFailed && exceptionStackTrace
@@ -419,7 +421,7 @@ export class Reactors implements IReactors {
             if (!this._queues.has(id)) {
                 this._logger.debug('Reactor observation stream closed cleanly', { reactorId: id });
             } else {
-                this._logger.error('Reactor observation stream ended unexpectedly', { reactorId: id, error: String(err) });
+                this._logger.error('Reactor observation stream ended unexpectedly', { reactorId: id, error: err });
             }
         } finally {
             // Only retire our own queue: a reconnect can already have replaced it,