@equipe-tech/observability 0.2.0 → 0.3.5

package/dist/nestjs/TelemetryModule.js

@@ -1,428 +0,0 @@
-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,5 +0,0 @@
-export { BrowserEventsRejection, createBrowserEventsController, defaultBrowserEventsPath, type BrowserEventsControllerOptions, } from "./BrowserEventsController.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,4 +0,0 @@
-export { BrowserEventsRejection, createBrowserEventsController, defaultBrowserEventsPath, } from "./BrowserEventsController.js";
-export { requestSpan, TelemetryInterceptor, TelemetryRequestTracker, withRequestSpan, } from "./TelemetryInterceptor.js";
-export { createRequestWideEventTraceCorrelation, RequestWideEventTraceCorrelation, } from "./RequestWideEventTraceCorrelation.js";
-export { InvalidTelemetryModuleOptions, TelemetryModule, TelemetryShutdownError, TelemetryStartupError, } from "./TelemetryModule.js";