@equipe-tech/observability 0.1.0 → 0.2.1

package/dist/nestjs/TelemetryModule.js

@@ -0,0 +1,428 @@
+import { Module } from "@nestjs/common";
+import { APP_INTERCEPTOR, HttpAdapterHost } from "@nestjs/core";
+import { Duration, Effect, Layer, ManagedRuntime, Option, Schema } from "effect";
+import { OtlpExporter as Otlp } from "effect/unstable/observability";
+import { layer } from "../Telemetry.js";
+import { OtlpEndpoint, TelemetryConfig } from "../TelemetryConfig.js";
+import { telemetryRoutePolicy } from "./HttpRoutePolicy.js";
+import { RequestWideEventTraceCorrelation } from "./RequestWideEventTraceCorrelation.js";
+import { TelemetryInterceptor, TelemetryRequestTracker } from "./TelemetryInterceptor.js";
+export class InvalidTelemetryModuleOptions extends Error {
+    _tag = "InvalidTelemetryModuleOptions";
+    code = "OBS_TELEMETRY_INVALID_MODULE_OPTIONS";
+    cause;
+    constructor(cause) {
+        super("Telemetry module options are invalid. Provide valid service identity, HTTP OTLP endpoint, route templates, proxy policy, and shutdown timeout.", { cause });
+        this.name = "InvalidTelemetryModuleOptions";
+        this.cause = cause;
+    }
+}
+export class TelemetryStartupError extends Error {
+    _tag = "TelemetryStartupError";
+    code = "OBS_TELEMETRY_STARTUP_FAILED";
+    cause;
+    constructor(cause) {
+        super("Telemetry startup failed. Verify the OTLP transport and runtime configuration before restarting the application.", { cause });
+        this.name = "TelemetryStartupError";
+        this.cause = cause;
+    }
+}
+export class TelemetryShutdownError extends Error {
+    _tag = "TelemetryShutdownError";
+    code = "OBS_TELEMETRY_SHUTDOWN_FAILED";
+    cause;
+    constructor(cause) {
+        super("Telemetry shutdown failed. Telemetry resources were disposed, but the final drain or flush did not complete.", { cause });
+        this.name = "TelemetryShutdownError";
+        this.cause = cause;
+    }
+}
+const Identity = Schema.NonEmptyString.check(Schema.makeFilter((value) => value.trim() === value, { expected: "a nonempty trimmed string" }));
+const ShutdownTimeout = Schema.Number.check(Schema.isInt(), Schema.makeFilter((value) => Number.isSafeInteger(value) && value > 0, {
+    expected: "a positive safe integer",
+}));
+const EnabledOptions = Schema.Struct({
+    enabled: Schema.Literal(true),
+    serviceName: Identity,
+    serviceVersion: Identity,
+    environment: Identity,
+    otlpEndpoint: OtlpEndpoint,
+    healthRouteTemplates: Schema.Union([Schema.Array(Schema.String), Schema.Undefined]).pipe(Schema.optionalKey),
+    proxyPolicy: Schema.Union([Schema.Literals(["direct", "framework"]), Schema.Undefined]).pipe(Schema.optionalKey),
+    requestWideEventTraceCorrelation: Schema.Union([
+        Schema.instanceOf(RequestWideEventTraceCorrelation),
+        Schema.Undefined,
+    ]).pipe(Schema.optionalKey),
+    shutdownTimeoutMilliseconds: Schema.Union([ShutdownTimeout, Schema.Undefined]).pipe(Schema.optionalKey),
+});
+const DisabledOptions = Schema.Struct({ enabled: Schema.Literal(false) });
+const ModuleOptions = Schema.Union([DisabledOptions, EnabledOptions]);
+const decodeModuleOptions = Schema.decodeUnknownSync(ModuleOptions);
+const parseModuleOptions = (input) => {
+    try {
+        const options = decodeModuleOptions(input);
+        if (!options.enabled) {
+            return { enabled: false };
+        }
+        telemetryRoutePolicy({
+            healthRouteTemplates: options.healthRouteTemplates,
+            proxyPolicy: options.proxyPolicy,
+        });
+        return {
+            enabled: true,
+            config: new TelemetryConfig({
+                serviceName: options.serviceName,
+                serviceVersion: options.serviceVersion,
+                environment: options.environment,
+                otlpEndpoint: options.otlpEndpoint,
+            }),
+            healthRouteTemplates: options.healthRouteTemplates,
+            proxyPolicy: options.proxyPolicy ?? "direct",
+            requestWideEventTraceCorrelation: options.requestWideEventTraceCorrelation,
+            shutdownTimeoutMilliseconds: options.shutdownTimeoutMilliseconds ?? 5_000,
+        };
+    }
+    catch (cause) {
+        throw new InvalidTelemetryModuleOptions(cause);
+    }
+};
+class DisabledTelemetryInterceptor {
+    intercept(_context, next) {
+        return next.handle();
+    }
+}
+class DisabledTelemetryIntegration {
+    interceptor = new DisabledTelemetryInterceptor();
+    beforeApplicationShutdown() { }
+    onApplicationShutdown() { }
+}
+class EnabledTelemetryIntegration {
+    interceptor;
+    #runtime;
+    #flusher;
+    #requestTracker;
+    #shutdownTimeoutMilliseconds;
+    #releaseRuntime;
+    #beforeRequestDrain;
+    #shutdownPromise;
+    #disposePromise;
+    #shutdownError;
+    constructor(runtime, flusher, options, releaseRuntime, beforeRequestDrain) {
+        this.#runtime = runtime;
+        this.#flusher = flusher;
+        this.#releaseRuntime = releaseRuntime;
+        this.#beforeRequestDrain = beforeRequestDrain;
+        this.#requestTracker = new TelemetryRequestTracker();
+        this.#shutdownTimeoutMilliseconds = options.shutdownTimeoutMilliseconds;
+        this.interceptor = new TelemetryInterceptor(runtime, {
+            healthRouteTemplates: options.healthRouteTemplates,
+            proxyPolicy: options.proxyPolicy,
+            requestTracker: this.#requestTracker,
+            requestWideEventTraceCorrelation: options.requestWideEventTraceCorrelation,
+        });
+    }
+    beforeApplicationShutdown() {
+        this.#shutdownPromise ??= this.#shutdown();
+        return this.#shutdownPromise;
+    }
+    async onApplicationShutdown() {
+        try {
+            await this.beforeApplicationShutdown();
+        }
+        catch (cause) {
+            this.#recordShutdownError(cause);
+        }
+        finally {
+            this.#disposePromise ??= this.#releaseRuntime();
+            try {
+                await this.#disposePromise;
+            }
+            catch (cause) {
+                this.#recordShutdownError(cause);
+            }
+        }
+        if (this.#shutdownError !== undefined) {
+            throw this.#shutdownError;
+        }
+    }
+    async #shutdown() {
+        const deadline = Date.now() + this.#shutdownTimeoutMilliseconds;
+        try {
+            this.#requestTracker.closeAdmission();
+            await this.#beforeRequestDrain();
+            const idle = await this.#withinDeadline(this.#requestTracker.waitForIdle(), deadline);
+            if (!idle) {
+                this.#requestTracker.interruptActive();
+                const interrupted = await this.#withinDeadline(this.#requestTracker.waitForIdle(), deadline);
+                if (!interrupted) {
+                    this.#recordShutdownError(new Error("The telemetry request interruption exhausted the shutdown deadline."));
+                }
+            }
+        }
+        catch (cause) {
+            this.#recordShutdownError(cause);
+        }
+        const remaining = Math.max(0, deadline - Date.now());
+        if (remaining === 0) {
+            this.#recordShutdownError(new Error("The telemetry request drain exhausted the shutdown deadline."));
+            return;
+        }
+        try {
+            const flushed = await this.#runtime.runPromise(this.#flusher.flush.pipe(Effect.timeoutOption(Duration.millis(remaining))));
+            if (Option.isNone(flushed)) {
+                this.#recordShutdownError(new Error("The telemetry flush exceeded the shutdown deadline."));
+            }
+        }
+        catch (cause) {
+            this.#recordShutdownError(cause);
+        }
+    }
+    #recordShutdownError(cause) {
+        if (this.#shutdownError === undefined) {
+            this.#shutdownError =
+                cause instanceof TelemetryShutdownError ? cause : new TelemetryShutdownError(cause);
+            return;
+        }
+        this.#shutdownError = new TelemetryShutdownError(new AggregateError([this.#shutdownError.cause, cause]));
+    }
+    async #withinDeadline(operation, deadline) {
+        const remaining = Math.max(0, deadline - Date.now());
+        if (remaining === 0) {
+            return false;
+        }
+        let timer;
+        const timeout = new Promise((resolve) => {
+            timer = setTimeout(() => resolve(false), remaining);
+        });
+        const completed = operation.then(() => true);
+        try {
+            return await Promise.race([completed, timeout]);
+        }
+        finally {
+            if (timer !== undefined) {
+                clearTimeout(timer);
+            }
+        }
+    }
+}
+class DeferredTelemetryInterceptor {
+    #target;
+    setTarget(target) {
+        this.#target = target;
+    }
+    intercept(context, next) {
+        return this.#target?.intercept(context, next) ?? next.handle();
+    }
+}
+class PendingTelemetryIntegration {
+    interceptor = new DeferredTelemetryInterceptor();
+    #application;
+    #options;
+    #state;
+    #overrides;
+    #integration;
+    constructor(application, options, state, overrides) {
+        this.#application = application;
+        this.#options = options;
+        this.#state = state;
+        this.#overrides = overrides;
+    }
+    async onModuleInit() {
+        const lease = await acquireApplicationRuntime(this.#application, this.#state, this.#options, this.#overrides);
+        this.#integration = new EnabledTelemetryIntegration(lease.runtime, lease.flusher, this.#options, lease.release, this.#overrides.beforeRequestDrain ?? (() => undefined));
+        this.interceptor.setTarget(this.#integration.interceptor);
+    }
+    beforeApplicationShutdown() {
+        return this.#integration?.beforeApplicationShutdown();
+    }
+    onApplicationShutdown() {
+        return this.#integration?.onApplicationShutdown();
+    }
+}
+const ASYNC_OPTIONS = Symbol("TelemetryModuleAsyncOptions");
+const NORMALIZED_OPTIONS = Symbol("TelemetryModuleNormalizedOptions");
+const TELEMETRY_INTEGRATION = Symbol("TelemetryModuleIntegration");
+const runtimePool = new Map();
+const applicationRuntimes = new WeakMap();
+const runtimeKey = (options) => JSON.stringify([
+    options.config.otlpEndpoint.toString(),
+    options.config.serviceName,
+    options.config.serviceVersion,
+    options.config.environment,
+    options.shutdownTimeoutMilliseconds,
+]);
+const createSharedRuntime = async (options, overrides) => {
+    let runtime;
+    try {
+        let runtimeLayer = layer(options.config, {
+            shutdownTimeout: Duration.millis(options.shutdownTimeoutMilliseconds),
+        });
+        if (overrides.scopedResource !== undefined) {
+            const resource = overrides.scopedResource;
+            const resourceLayer = Layer.effectDiscard(Effect.acquireRelease(Effect.promise(() => Promise.resolve(resource.acquire())), () => Effect.promise(() => Promise.resolve(resource.release()))));
+            runtimeLayer = Layer.merge(runtimeLayer, resourceLayer);
+        }
+        runtime = ManagedRuntime.make(runtimeLayer);
+        await runtime.context();
+        await (overrides.startupProbe ?? (() => undefined))();
+        const flusher = await runtime.runPromise(Otlp.Flusher);
+        return { runtime, flusher };
+    }
+    catch (cause) {
+        if (runtime !== undefined) {
+            try {
+                await runtime.dispose();
+                overrides.onRuntimeDisposed?.();
+            }
+            catch (disposeCause) {
+                throw new TelemetryStartupError(new AggregateError([cause, disposeCause]));
+            }
+        }
+        throw new TelemetryStartupError(cause);
+    }
+};
+const acquireRuntime = async (options, overrides) => {
+    const key = runtimeKey(options);
+    let entry = runtimePool.get(key);
+    if (entry?.closing !== undefined) {
+        try {
+            await entry.closing;
+        }
+        catch (cause) {
+            throw new TelemetryStartupError(cause);
+        }
+        entry = runtimePool.get(key);
+    }
+    if (entry === undefined) {
+        const shared = createSharedRuntime(options, overrides);
+        entry = { shared, references: 0, closing: undefined };
+        runtimePool.set(key, entry);
+        try {
+            await shared;
+        }
+        catch (cause) {
+            if (runtimePool.get(key) === entry) {
+                runtimePool.delete(key);
+            }
+            throw cause;
+        }
+    }
+    const shared = await entry.shared;
+    entry.references++;
+    let releasePromise;
+    const release = () => {
+        if (releasePromise !== undefined) {
+            return releasePromise;
+        }
+        entry.references--;
+        if (entry.references > 0) {
+            releasePromise = Promise.resolve();
+            return releasePromise;
+        }
+        entry.closing = (async () => {
+            let failure;
+            try {
+                await overrides.beforeRuntimeDispose?.();
+            }
+            catch (cause) {
+                failure = new Error("Telemetry runtime disposal preparation failed.", { cause });
+            }
+            try {
+                await shared.runtime.dispose();
+                overrides.onRuntimeDisposed?.();
+            }
+            catch (cause) {
+                failure =
+                    failure === undefined
+                        ? new Error("Telemetry runtime disposal failed.", { cause })
+                        : new AggregateError([failure, cause]);
+            }
+            if (failure !== undefined) {
+                throw failure;
+            }
+        })().finally(() => {
+            if (runtimePool.get(key) === entry) {
+                runtimePool.delete(key);
+            }
+        });
+        releasePromise = entry.closing;
+        return releasePromise;
+    };
+    return { runtime: shared.runtime, flusher: shared.flusher, release };
+};
+const registerApplicationRuntime = (application, options) => {
+    const key = runtimeKey(options);
+    const state = applicationRuntimes.get(application);
+    if (state === undefined) {
+        const registered = {
+            key,
+            requestWideEventTraceCorrelation: options.requestWideEventTraceCorrelation,
+            releases: new Set(),
+            failed: false,
+        };
+        applicationRuntimes.set(application, registered);
+        return registered;
+    }
+    if (state.key !== key ||
+        state.requestWideEventTraceCorrelation !== options.requestWideEventTraceCorrelation) {
+        state.failed = true;
+    }
+    return state;
+};
+const acquireApplicationRuntime = async (application, state, options, overrides) => {
+    if (state.failed) {
+        applicationRuntimes.delete(application);
+        throw new InvalidTelemetryModuleOptions(new Error("TelemetryModule imports in one application must use one telemetry configuration."));
+    }
+    const lease = await acquireRuntime(options, overrides);
+    const release = () => {
+        state.releases.delete(release);
+        if (state.releases.size === 0) {
+            applicationRuntimes.delete(application);
+        }
+        return lease.release();
+    };
+    state.releases.add(release);
+    return { runtime: lease.runtime, flusher: lease.flusher, release };
+};
+const makeIntegration = (options, application, overrides) => {
+    if (!options.enabled) {
+        return new DisabledTelemetryIntegration();
+    }
+    return new PendingTelemetryIntegration(application, options, registerApplicationRuntime(application, options), overrides);
+};
+const makeTelemetryModule = (options, overrides = {}) => {
+    const providers = [
+        {
+            provide: ASYNC_OPTIONS,
+            inject: options.inject ?? [],
+            useFactory: options.useFactory,
+        },
+        {
+            provide: NORMALIZED_OPTIONS,
+            inject: [ASYNC_OPTIONS],
+            useFactory: parseModuleOptions,
+        },
+        {
+            provide: TELEMETRY_INTEGRATION,
+            inject: [NORMALIZED_OPTIONS, HttpAdapterHost],
+            useFactory: (normalized, application) => makeIntegration(normalized, application, overrides),
+        },
+        {
+            provide: APP_INTERCEPTOR,
+            inject: [TELEMETRY_INTEGRATION],
+            useFactory: (integration) => integration.interceptor,
+        },
+    ];
+    if (options.imports === undefined) {
+        return { module: TelemetryModule, providers };
+    }
+    return { module: TelemetryModule, imports: options.imports, providers };
+};
+export const telemetryModuleForTesting = (options, overrides) => makeTelemetryModule(options, overrides);
+export class TelemetryModule {
+    static forRootAsync(options) {
+        return makeTelemetryModule(options);
+    }
+}
+Module({})(TelemetryModule);

package/dist/nestjs/index.d.ts

@@ -1,2 +1,5 @@
 export { BrowserEventsRejection, createBrowserEventsController, defaultBrowserEventsPath, type BrowserEventsControllerOptions, } from "./BrowserEventsController.js";
-export { requestSpan, TelemetryInterceptor, withRequestSpan, type RequestReference, } from "./TelemetryInterceptor.js";
+export { requestSpan, TelemetryInterceptor, TelemetryRequestTracker, withRequestSpan, type TelemetryInterceptorOptions, } from "./TelemetryInterceptor.js";
+export { createRequestWideEventTraceCorrelation, RequestWideEventTraceCorrelation, type RequestReference, type RequestWideEventLogger, type RequestWideEventLoggerResolver, type ServerSpanCorrelation, } from "./RequestWideEventTraceCorrelation.js";
+export type { ProxyPolicy, TelemetryRoutePolicyOptions } from "./HttpRoutePolicy.js";
+export { InvalidTelemetryModuleOptions, TelemetryModule, TelemetryShutdownError, TelemetryStartupError, type TelemetryModuleAsyncOptions, type TelemetryModuleOptions, } from "./TelemetryModule.js";

package/dist/nestjs/index.js

@@ -1,2 +1,4 @@
 export { BrowserEventsRejection, createBrowserEventsController, defaultBrowserEventsPath, } from "./BrowserEventsController.js";
-export { requestSpan, TelemetryInterceptor, withRequestSpan, } from "./TelemetryInterceptor.js";
+export { requestSpan, TelemetryInterceptor, TelemetryRequestTracker, withRequestSpan, } from "./TelemetryInterceptor.js";
+export { createRequestWideEventTraceCorrelation, RequestWideEventTraceCorrelation, } from "./RequestWideEventTraceCorrelation.js";
+export { InvalidTelemetryModuleOptions, TelemetryModule, TelemetryShutdownError, TelemetryStartupError, } from "./TelemetryModule.js";

package/dist/node/BrowserEventIngest.d.ts

@@ -7,10 +7,10 @@ declare const InvalidBrowserEventBatch_base: Schema.Class<InvalidBrowserEventBat
 }>, import("effect/Cause").YieldableError>;
 export declare class InvalidBrowserEventBatch extends InvalidBrowserEventBatch_base {
 }
-export declare const parseBrowserEventBatch: (input: unknown) => Effect.Effect<BrowserEventBatch, InvalidBrowserEventBatch>;
+export declare const parseBrowserEventBatch: (input: unknown, options?: import("effect/SchemaAST").ParseOptions | undefined) => Effect.Effect<BrowserEventBatch, InvalidBrowserEventBatch, never>;
 export type BrowserEventIngestReceipt = {
     readonly accepted: number;
 };
 export declare const ingestBrowserEventBatch: (batch: BrowserEventBatch) => Effect.Effect<BrowserEventIngestReceipt, never, never>;
-export declare const ingestBrowserEvents: (input: unknown) => Effect.Effect<BrowserEventIngestReceipt, InvalidBrowserEventBatch>;
+export declare const ingestBrowserEvents: (input: unknown, options?: import("effect/SchemaAST").ParseOptions | undefined) => Effect.Effect<BrowserEventIngestReceipt, InvalidBrowserEventBatch, never>;
 export {};

package/dist/node/BrowserEventIngest.js

@@ -1,4 +1,4 @@
-import { Effect, Schema } from "effect";
+import { Effect, flow, Schema } from "effect";
 import { BrowserEventBatch } from "../BrowserEvents.js";
 import * as WideEvent from "../WideEvent.js";
 export class InvalidBrowserEventBatch extends Schema.TaggedError()("InvalidBrowserEventBatch", {
@@ -8,7 +8,7 @@ export class InvalidBrowserEventBatch extends Schema.TaggedError()("InvalidBrows
 }) {
 }
 const decodeBrowserEventBatch = Schema.decodeUnknownEffect(BrowserEventBatch);
-export const parseBrowserEventBatch = (input) => decodeBrowserEventBatch(input).pipe(Effect.mapError((cause) => new InvalidBrowserEventBatch({
+export const parseBrowserEventBatch = flow(decodeBrowserEventBatch, Effect.mapError((cause) => new InvalidBrowserEventBatch({
     code: "OBS_BROWSER_EVENTS_INVALID_BATCH",
     message: "The browser event batch is invalid. Send a version 1 batch with bounded events and scalar fields.",
     cause,
@@ -35,4 +35,4 @@ export const ingestBrowserEventBatch = Effect.fn("ingestBrowserEventBatch")(func
     }
     return { accepted: batch.events.length };
 });
-export const ingestBrowserEvents = (input) => parseBrowserEventBatch(input).pipe(Effect.flatMap(ingestBrowserEventBatch));
+export const ingestBrowserEvents = flow(parseBrowserEventBatch, Effect.flatMap(ingestBrowserEventBatch));

package/dist/testing/index.d.ts

@@ -1,4 +1,5 @@
 import { Effect, Layer, Option, type Exit } from "effect";
+import { OtlpExporter } from "effect/unstable/observability";
 import { TelemetryConfig } from "../TelemetryConfig.js";
 export type CapturedAttributeValue = string | number | boolean;
 export type CapturedAttributes = ReadonlyMap<string, CapturedAttributeValue>;
@@ -7,9 +8,12 @@ export type CapturedSpan = {
     readonly spanId: string;
     readonly parentSpanId: Option.Option<string>;
     readonly name: string;
+    readonly kind: number;
     readonly statusCode: number;
     readonly statusMessage: Option.Option<string>;
     readonly attributes: CapturedAttributes;
+    readonly eventNames: ReadonlyArray<string>;
+    readonly linkedSpanIds: ReadonlyArray<string>;
     readonly resourceAttributes: CapturedAttributes;
 };
 export type CapturedLog = {
@@ -24,11 +28,38 @@ export type CapturedMetricPoint = {
     readonly value: Option.Option<number>;
     readonly attributes: CapturedAttributes;
 };
-export type CapturedMetric = {
+export type CapturedHistogramPoint = {
+    readonly attributes: CapturedAttributes;
+    readonly count: number;
+    readonly sum: number;
+    readonly min: number;
+    readonly max: number;
+    readonly explicitBounds: ReadonlyArray<number>;
+    readonly bucketCounts: ReadonlyArray<number>;
+};
+type CapturedMetricCommon = {
     readonly name: string;
+    readonly description: string;
+    readonly unit: string;
     readonly points: ReadonlyArray<CapturedMetricPoint>;
     readonly resourceAttributes: CapturedAttributes;
 };
+export type CapturedMetric = (CapturedMetricCommon & {
+    readonly kind: "sum";
+    readonly isMonotonic: boolean;
+    readonly aggregationTemporality: number;
+}) | (CapturedMetricCommon & {
+    readonly kind: "gauge";
+}) | (CapturedMetricCommon & {
+    readonly kind: "histogram";
+    readonly aggregationTemporality: number;
+    readonly histogramPoints: ReadonlyArray<CapturedHistogramPoint>;
+}) | (CapturedMetricCommon & {
+    readonly kind: "exponentialHistogram";
+    readonly aggregationTemporality: number;
+}) | (CapturedMetricCommon & {
+    readonly kind: "summary";
+});
 export type CapturedTelemetry = {
     readonly spans: ReadonlyArray<CapturedSpan>;
     readonly logs: ReadonlyArray<CapturedLog>;
@@ -47,8 +78,9 @@ export type RunOptions = {
     readonly config?: TelemetryConfig;
 };
 export type TelemetryCapture = {
-    readonly layer: Layer.Layer<never>;
+    readonly layer: Layer.Layer<OtlpExporter.Flusher>;
     readonly telemetry: Effect.Effect<CapturedTelemetry>;
 };
 export declare const makeCapture: (options?: RunOptions | undefined) => Effect.Effect<TelemetryCapture, never, never>;
 export declare const run: <A, E, R>(program: Effect.Effect<A, E, R>, options?: RunOptions) => Effect.Effect<TelemetryRun<A, E>, never, R>;
+export {};