@equipe-tech/observability 0.1.0 → 0.2.0

package/dist/nestjs/TelemetryInterceptor.js

@@ -1,34 +1,87 @@
-import { Context, Effect, Exit, Option, Schema } from "effect";
+import { Context, Effect, Exit, Option, Predicate, Schema, Tracer } from "effect";
+import { EventEmitter } from "node:events";
 import { Observable } from "rxjs";
-const HttpRequestBoundary = Schema.Struct({
-    method: Schema.NonEmptyString,
+import { telemetryRoutePolicy, } from "./HttpRoutePolicy.js";
+const TraceparentRequest = Schema.Struct({
+    headers: Schema.Struct({
+        traceparent: Schema.String.check(Schema.isPattern(/^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$/), Schema.makeFilter((traceparent) => traceparent.slice(3, 35) !== "00000000000000000000000000000000" &&
+            traceparent.slice(36, 52) !== "0000000000000000")),
+    }),
 });
-const decodeHttpRequestBoundary = Schema.decodeUnknownOption(HttpRequestBoundary);
+const parseTraceparentRequest = Schema.decodeUnknownOption(TraceparentRequest);
 const HttpResponseBoundary = Schema.Struct({
-    statusCode: Schema.Number.check(Schema.isInt()),
+    statusCode: Schema.Number.check(Schema.isInt(), Schema.isBetween({ minimum: 100, maximum: 599 })),
 });
 const decodeHttpResponseBoundary = Schema.decodeUnknownOption(HttpResponseBoundary);
-const ClientErrorBoundary = Schema.Struct({
-    status: Schema.Number.check(Schema.isInt(), Schema.makeFilter((status) => status >= 400 && status <= 499, {
-        expected: "an HTTP client error status",
-    })),
+const HttpErrorBoundary = Schema.Struct({
+    status: Schema.Number.check(Schema.isInt(), Schema.isBetween({ minimum: 100, maximum: 599 })).pipe(Schema.optionalKey),
 });
-const decodeClientErrorBoundary = Schema.decodeUnknownOption(ClientErrorBoundary);
+const ErrorType = Schema.NonEmptyString.check(Schema.isMaxLength(128));
+const decodeHttpErrorBoundary = Schema.decodeUnknownOption(HttpErrorBoundary);
+const decodeErrorType = Schema.decodeUnknownOption(ErrorType);
+const decodeHeadersSent = Schema.decodeUnknownOption(Schema.Boolean);
+const decodeResponseEmitter = Schema.decodeUnknownOption(Schema.instanceOf(EventEmitter));
 const requestSpans = new WeakMap();
 export const requestSpan = (request) => Option.fromNullishOr(requestSpans.get(request));
 export const withRequestSpan = (request) => (effect) => Option.match(requestSpan(request), {
     onNone: () => effect,
     onSome: (span) => Effect.withParentSpan(effect, span),
 });
+export class TelemetryRequestTracker {
+    #accepting = true;
+    #active = new Set();
+    #idleWaiters = new Set();
+    get accepting() {
+        return this.#accepting;
+    }
+    register(activeRequest) {
+        if (!this.#accepting) {
+            return Option.none();
+        }
+        this.#active.add(activeRequest);
+        return Option.some(() => {
+            if (!this.#active.delete(activeRequest) || this.#active.size !== 0) {
+                return;
+            }
+            for (const resolve of this.#idleWaiters) {
+                resolve();
+            }
+            this.#idleWaiters.clear();
+        });
+    }
+    closeAdmission() {
+        this.#accepting = false;
+    }
+    waitForIdle() {
+        if (this.#active.size === 0) {
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => this.#idleWaiters.add(resolve));
+    }
+    interruptActive() {
+        for (const activeRequest of this.#active) {
+            activeRequest.interrupt();
+        }
+    }
+}
 export class TelemetryInterceptor {
     #runtime;
+    #routePolicy;
+    #requestTracker;
+    #requestWideEventTraceCorrelation;
     #tracer;
     #clock;
-    constructor(runtime) {
+    constructor(runtime, options = {}) {
         this.#runtime = runtime;
+        this.#routePolicy = telemetryRoutePolicy({
+            healthRouteTemplates: options.healthRouteTemplates,
+            proxyPolicy: options.proxyPolicy,
+        });
+        this.#requestTracker = options.requestTracker ?? new TelemetryRequestTracker();
+        this.#requestWideEventTraceCorrelation = options.requestWideEventTraceCorrelation;
     }
     intercept(context, next) {
-        if (context.getType() !== "http") {
+        if (context.getType() !== "http" || !this.#requestTracker.accepting) {
             return next.handle();
         }
         try {
@@ -39,61 +92,174 @@ export class TelemetryInterceptor {
         }
     }
     #instrument(context, next) {
-        const tracer = (this.#tracer ??= this.#runtime.runSync(Effect.tracer));
-        const clock = (this.#clock ??= this.#runtime.runSync(Effect.clockWith(Effect.succeed)));
         const httpContext = context.switchToHttp();
         const request = httpContext.getRequest();
-        const method = decodeHttpRequestBoundary(request).pipe(Option.map((boundary) => boundary.method.toUpperCase()), Option.getOrElse(() => "UNKNOWN"));
-        const controller = context.getClass().name;
-        const handler = context.getHandler().name;
+        if (requestSpans.has(request)) {
+            return next.handle();
+        }
+        const requestDetails = this.#routePolicy.inspect(request);
+        if (Option.isNone(requestDetails)) {
+            return next.handle();
+        }
+        const tracer = (this.#tracer ??= this.#runtime.runSync(Effect.tracer));
+        const clock = (this.#clock ??= this.#runtime.runSync(Effect.clockWith(Effect.succeed)));
+        const traceparentRequest = httpContext.getRequest();
+        const parent = parseTraceparentRequest({ headers: traceparentRequest.headers }).pipe(Option.map(({ headers }) => {
+            const traceparent = headers.traceparent;
+            return Tracer.externalSpan({
+                traceId: traceparent.slice(3, 35),
+                spanId: traceparent.slice(36, 52),
+                sampled: Number.parseInt(traceparent.slice(53, 55), 16) % 2 === 1,
+            });
+        }));
+        const details = requestDetails.value;
         const span = tracer.span({
-            name: `${method} ${controller}.${handler}`,
-            parent: Option.none(),
+            name: details.spanName,
+            parent,
             annotations: Context.empty(),
             links: [],
             startTime: clock.currentTimeNanosUnsafe(),
             kind: "server",
-            root: true,
-            sampled: true,
+            root: Option.isNone(parent),
+            sampled: Option.match(parent, {
+                onNone: () => true,
+                onSome: (remoteParent) => remoteParent.sampled,
+            }),
         });
-        span.attribute("http.request.method", method);
-        span.attribute("nestjs.controller", controller);
-        span.attribute("nestjs.handler", handler);
+        span.attribute("http.request.method", details.method);
+        if (Option.isSome(details.methodOriginal)) {
+            span.attribute("http.request.method_original", details.methodOriginal.value);
+        }
+        if (Option.isSome(details.route)) {
+            span.attribute("http.route", details.route.value);
+        }
+        if (Option.isSome(details.urlPath)) {
+            span.attribute("url.path", details.urlPath.value);
+        }
+        if (Option.isSome(details.urlScheme)) {
+            span.attribute("url.scheme", details.urlScheme.value);
+        }
+        if (Option.isSome(details.clientAddress)) {
+            span.attribute("client.address", details.clientAddress.value);
+        }
+        if (Option.isSome(details.networkPeerAddress)) {
+            span.attribute("network.peer.address", details.networkPeerAddress.value);
+        }
+        if (Option.isSome(details.networkPeerPort)) {
+            span.attribute("network.peer.port", details.networkPeerPort.value);
+        }
+        if (Option.isSome(details.serverAddress)) {
+            span.attribute("server.address", details.serverAddress.value);
+        }
         requestSpans.set(request, span);
+        this.#requestWideEventTraceCorrelation?.correlate(request, {
+            traceId: span.traceId,
+            spanId: span.spanId,
+        });
+        const response = httpContext.getResponse();
+        const responseEmitter = decodeResponseEmitter(response);
         return new Observable((subscriber) => {
-            let settled = false;
-            const finish = (exit, statusOverride) => {
-                if (settled) {
+            let ended = false;
+            let responseFinished = false;
+            let observableSettled = false;
+            let pendingExit = Exit.succeed(undefined);
+            let pendingErrorType = Option.none();
+            let release = () => { };
+            const responseStatus = (requireSent = false) => {
+                if (requireSent) {
+                    const headersSent = Predicate.hasProperty(response, "headersSent")
+                        ? decodeHeadersSent(response.headersSent)
+                        : Option.none();
+                    if (!Option.getOrElse(headersSent, () => false)) {
+                        return Option.none();
+                    }
+                }
+                return decodeHttpResponseBoundary(response).pipe(Option.map((boundary) => boundary.statusCode));
+            };
+            const removeResponseListeners = () => {
+                if (Option.isSome(responseEmitter)) {
+                    responseEmitter.value.off("finish", onResponseFinish);
+                    responseEmitter.value.off("close", onResponseClose);
+                }
+            };
+            const finish = (exit, status, errorType) => {
+                if (ended) {
                     return;
                 }
-                settled = true;
-                const status = statusOverride.pipe(Option.orElse(() => decodeHttpResponseBoundary(httpContext.getResponse()).pipe(Option.map((boundary) => boundary.statusCode))));
+                ended = true;
+                removeResponseListeners();
                 if (Option.isSome(status)) {
                     span.attribute("http.response.status_code", status.value);
                 }
+                const finalErrorType = Option.contains(errorType, "connection_closed")
+                    ? errorType
+                    : Option.match(status, {
+                        onNone: () => errorType,
+                        onSome: (statusCode) => {
+                            if (statusCode >= 500) {
+                                return Option.some(String(statusCode));
+                            }
+                            if (statusCode >= 400) {
+                                return Option.none();
+                            }
+                            return errorType;
+                        },
+                    });
+                if (Option.isSome(finalErrorType)) {
+                    span.attribute("error.type", finalErrorType.value);
+                }
+                requestSpans.delete(request);
+                release();
                 span.end(clock.currentTimeNanosUnsafe(), exit);
             };
+            const onResponseFinish = () => {
+                responseFinished = true;
+                finish(pendingExit, responseStatus(), pendingErrorType);
+            };
+            const onResponseClose = () => {
+                if (!responseFinished) {
+                    finish(Exit.interrupt(), responseStatus(true), Option.some("connection_closed"));
+                }
+            };
+            const registered = this.#requestTracker.register({
+                interrupt: () => finish(Exit.interrupt(), responseStatus(true), Option.none()),
+            });
+            if (Option.isNone(registered)) {
+                requestSpans.delete(request);
+                span.end(clock.currentTimeNanosUnsafe(), Exit.interrupt());
+                return next.handle().subscribe(subscriber);
+            }
+            release = registered.value;
+            if (Option.isSome(responseEmitter)) {
+                responseEmitter.value.on("finish", onResponseFinish);
+                responseEmitter.value.on("close", onResponseClose);
+            }
             const subscription = next.handle().subscribe({
                 next: (value) => subscriber.next(value),
                 error: (cause) => {
-                    const clientError = decodeClientErrorBoundary(cause);
-                    if (Option.isSome(clientError)) {
-                        finish(Exit.succeed(undefined), Option.some(clientError.value.status));
-                    }
-                    else {
-                        finish(Exit.die(cause), Option.none());
+                    observableSettled = true;
+                    const errorBoundary = decodeHttpErrorBoundary(cause);
+                    pendingExit = Exit.die(cause);
+                    pendingErrorType = Predicate.hasProperty(cause, "name")
+                        ? decodeErrorType(cause.name).pipe(Option.orElse(() => Option.some("exception")))
+                        : Option.some("exception");
+                    if (Option.isNone(responseEmitter)) {
+                        const status = errorBoundary.pipe(Option.flatMap((boundary) => Option.fromNullishOr(boundary.status)));
+                        finish(pendingExit, status, pendingErrorType);
                     }
                     subscriber.error(cause);
                 },
                 complete: () => {
-                    finish(Exit.succeed(undefined), Option.none());
+                    observableSettled = true;
+                    if (Option.isNone(responseEmitter)) {
+                        finish(Exit.succeed(undefined), responseStatus(), Option.none());
+                    }
                     subscriber.complete();
                 },
             });
             return () => {
-                if (!settled) {
-                    span.attribute("http.request.cancelled", true);
-                    finish(Exit.interrupt(), Option.none());
+                if (!observableSettled && Option.isNone(responseEmitter)) {
+                    finish(Exit.interrupt(), responseStatus(), Option.none());
                 }
                 subscription.unsubscribe();
             };

package/dist/nestjs/TelemetryModule.d.ts

@@ -0,0 +1,53 @@
+import type { DynamicModule, InjectionToken, ModuleMetadata, OptionalFactoryDependency } from "@nestjs/common";
+import { type ProxyPolicy } from "./HttpRoutePolicy.js";
+import { RequestWideEventTraceCorrelation } from "./RequestWideEventTraceCorrelation.js";
+export type TelemetryModuleOptions = {
+    readonly enabled: false;
+} | {
+    readonly enabled: true;
+    readonly serviceName: string;
+    readonly serviceVersion: string;
+    readonly environment: string;
+    readonly otlpEndpoint: string;
+    readonly healthRouteTemplates?: ReadonlyArray<string> | undefined;
+    readonly proxyPolicy?: ProxyPolicy | undefined;
+    readonly requestWideEventTraceCorrelation?: RequestWideEventTraceCorrelation | undefined;
+    readonly shutdownTimeoutMilliseconds?: number | undefined;
+};
+export interface TelemetryModuleAsyncOptions {
+    readonly imports?: ModuleMetadata["imports"] | undefined;
+    readonly inject?: Array<InjectionToken | OptionalFactoryDependency> | undefined;
+    readonly useFactory: (...dependencies: Array<never>) => TelemetryModuleOptions | Promise<TelemetryModuleOptions>;
+}
+export declare class InvalidTelemetryModuleOptions extends Error {
+    readonly _tag = "InvalidTelemetryModuleOptions";
+    readonly code = "OBS_TELEMETRY_INVALID_MODULE_OPTIONS";
+    readonly cause: unknown;
+    constructor(cause: unknown);
+}
+export declare class TelemetryStartupError extends Error {
+    readonly _tag = "TelemetryStartupError";
+    readonly code = "OBS_TELEMETRY_STARTUP_FAILED";
+    readonly cause: unknown;
+    constructor(cause: unknown);
+}
+export declare class TelemetryShutdownError extends Error {
+    readonly _tag = "TelemetryShutdownError";
+    readonly code = "OBS_TELEMETRY_SHUTDOWN_FAILED";
+    readonly cause: unknown;
+    constructor(cause: unknown);
+}
+export interface TelemetryModuleTestingOverrides {
+    readonly scopedResource?: {
+        readonly acquire: () => void | Promise<void>;
+        readonly release: () => void | Promise<void>;
+    } | undefined;
+    readonly startupProbe?: (() => void | Promise<void>) | undefined;
+    readonly beforeRequestDrain?: (() => void | Promise<void>) | undefined;
+    readonly beforeRuntimeDispose?: (() => void | Promise<void>) | undefined;
+    readonly onRuntimeDisposed?: (() => void) | undefined;
+}
+export declare const telemetryModuleForTesting: (options: TelemetryModuleAsyncOptions, overrides: TelemetryModuleTestingOverrides) => DynamicModule;
+export declare class TelemetryModule {
+    static forRootAsync(options: TelemetryModuleAsyncOptions): DynamicModule;
+}