@celerity-sdk/telemetry 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,106 @@
+import { CelerityLayer, HandlerContext, HandlerResponse, LogLevel, CelerityLogger, CeleritySpan, CelerityTracer, HttpRequest, ServiceContainer } from '@celerity-sdk/types';
+export { extractUserId } from '@celerity-sdk/common';
+import pino from 'pino';
+import { Span, Context } from '@opentelemetry/api';
+
+declare class TelemetryLayer implements CelerityLayer {
+    private config;
+    private rootLogger;
+    private currentLevel;
+    private initPromise;
+    constructor();
+    handle(context: HandlerContext, next: () => Promise<HandlerResponse>): Promise<HandlerResponse>;
+    dispose(): Promise<void>;
+    private refreshLogLevelFromConfig;
+}
+
+type TelemetryConfig = {
+    tracingEnabled: boolean;
+    otlpEndpoint: string;
+    serviceName: string;
+    serviceVersion: string;
+    logLevel: LogLevel;
+    logFormat: "json" | "human" | "auto";
+    logFilePath: string | null;
+};
+declare function readTelemetryEnv(): TelemetryConfig;
+
+/**
+ * Thin pino wrapper implementing CelerityLogger.
+ * Every method delegates directly to the underlying pino instance.
+ */
+declare class CelerityLoggerImpl implements CelerityLogger {
+    private pinoLogger;
+    constructor(pinoLogger: pino.Logger);
+    debug(message: string, attributes?: Record<string, unknown>): void;
+    info(message: string, attributes?: Record<string, unknown>): void;
+    warn(message: string, attributes?: Record<string, unknown>): void;
+    error(message: string, attributes?: Record<string, unknown>): void;
+    private log;
+    child(name: string, attributes?: Record<string, unknown>): CelerityLogger;
+    withContext(attributes: Record<string, unknown>): CelerityLogger;
+    /** Update the log level at runtime. Internal — used by TelemetryLayer for dynamic config. */
+    setLevel(level: LogLevel): void;
+}
+declare function createLogger(config: TelemetryConfig): CelerityLoggerImpl;
+
+/**
+ * Get the request-scoped logger from the current async context.
+ *
+ * Works anywhere in the async call chain during request handling —
+ * handlers, services, repositories, API clients.
+ *
+ * Returns `undefined` outside a request context (e.g., startup code, background tasks).
+ */
+declare function getRequestLogger(): CelerityLogger | undefined;
+/**
+ * Context-aware logger proxy registered under LOGGER_TOKEN.
+ *
+ * Delegates to the request-scoped logger (via AsyncLocalStorage) when inside
+ * a request context, falls back to the root logger otherwise.
+ *
+ * This means `@Inject(LOGGER_TOKEN)` automatically resolves to the most
+ * appropriate logger for the current context — no manual wiring needed.
+ */
+declare class ContextAwareLogger implements CelerityLogger {
+    private rootLogger;
+    constructor(rootLogger: CelerityLogger);
+    private get current();
+    debug(message: string, attributes?: Record<string, unknown>): void;
+    info(message: string, attributes?: Record<string, unknown>): void;
+    warn(message: string, attributes?: Record<string, unknown>): void;
+    error(message: string, attributes?: Record<string, unknown>): void;
+    child(name: string, attributes?: Record<string, unknown>): CelerityLogger;
+    withContext(attributes: Record<string, unknown>): CelerityLogger;
+}
+
+declare class OTelTracer implements CelerityTracer {
+    private tracer;
+    startSpan(name: string, attributes?: Record<string, unknown>): CeleritySpan;
+    withSpan<T>(name: string, fn: (span: CeleritySpan) => T | Promise<T>, attributes?: Record<string, unknown>): Promise<T>;
+}
+declare class OTelSpan implements CeleritySpan {
+    private span;
+    constructor(span: Span);
+    setAttribute(key: string, value: string | number | boolean): void;
+    setAttributes(attributes: Record<string, string | number | boolean>): void;
+    recordError(error: Error): void;
+    setOk(): void;
+    end(): void;
+}
+
+declare class NoopTracer implements CelerityTracer {
+    startSpan(): CeleritySpan;
+    withSpan<T>(_name: string, fn: (span: CeleritySpan) => T | Promise<T>): Promise<T>;
+}
+declare const NOOP_SPAN: CeleritySpan;
+
+declare const LOGGER_TOKEN = "CelerityLogger";
+declare const TRACER_TOKEN = "CelerityTracer";
+
+declare function extractTraceContext(request: HttpRequest): Context;
+
+declare function getLogger(container: ServiceContainer): Promise<CelerityLogger>;
+declare function getTracer(container: ServiceContainer): Promise<CelerityTracer>;
+
+export { CelerityLoggerImpl, ContextAwareLogger, LOGGER_TOKEN, NOOP_SPAN, NoopTracer, OTelSpan, OTelTracer, TRACER_TOKEN, type TelemetryConfig, TelemetryLayer, createLogger, extractTraceContext, getLogger, getRequestLogger, getTracer, readTelemetryEnv };

package/dist/index.d.ts

@@ -0,0 +1,106 @@
+import { CelerityLayer, HandlerContext, HandlerResponse, LogLevel, CelerityLogger, CeleritySpan, CelerityTracer, HttpRequest, ServiceContainer } from '@celerity-sdk/types';
+export { extractUserId } from '@celerity-sdk/common';
+import pino from 'pino';
+import { Span, Context } from '@opentelemetry/api';
+
+declare class TelemetryLayer implements CelerityLayer {
+    private config;
+    private rootLogger;
+    private currentLevel;
+    private initPromise;
+    constructor();
+    handle(context: HandlerContext, next: () => Promise<HandlerResponse>): Promise<HandlerResponse>;
+    dispose(): Promise<void>;
+    private refreshLogLevelFromConfig;
+}
+
+type TelemetryConfig = {
+    tracingEnabled: boolean;
+    otlpEndpoint: string;
+    serviceName: string;
+    serviceVersion: string;
+    logLevel: LogLevel;
+    logFormat: "json" | "human" | "auto";
+    logFilePath: string | null;
+};
+declare function readTelemetryEnv(): TelemetryConfig;
+
+/**
+ * Thin pino wrapper implementing CelerityLogger.
+ * Every method delegates directly to the underlying pino instance.
+ */
+declare class CelerityLoggerImpl implements CelerityLogger {
+    private pinoLogger;
+    constructor(pinoLogger: pino.Logger);
+    debug(message: string, attributes?: Record<string, unknown>): void;
+    info(message: string, attributes?: Record<string, unknown>): void;
+    warn(message: string, attributes?: Record<string, unknown>): void;
+    error(message: string, attributes?: Record<string, unknown>): void;
+    private log;
+    child(name: string, attributes?: Record<string, unknown>): CelerityLogger;
+    withContext(attributes: Record<string, unknown>): CelerityLogger;
+    /** Update the log level at runtime. Internal — used by TelemetryLayer for dynamic config. */
+    setLevel(level: LogLevel): void;
+}
+declare function createLogger(config: TelemetryConfig): CelerityLoggerImpl;
+
+/**
+ * Get the request-scoped logger from the current async context.
+ *
+ * Works anywhere in the async call chain during request handling —
+ * handlers, services, repositories, API clients.
+ *
+ * Returns `undefined` outside a request context (e.g., startup code, background tasks).
+ */
+declare function getRequestLogger(): CelerityLogger | undefined;
+/**
+ * Context-aware logger proxy registered under LOGGER_TOKEN.
+ *
+ * Delegates to the request-scoped logger (via AsyncLocalStorage) when inside
+ * a request context, falls back to the root logger otherwise.
+ *
+ * This means `@Inject(LOGGER_TOKEN)` automatically resolves to the most
+ * appropriate logger for the current context — no manual wiring needed.
+ */
+declare class ContextAwareLogger implements CelerityLogger {
+    private rootLogger;
+    constructor(rootLogger: CelerityLogger);
+    private get current();
+    debug(message: string, attributes?: Record<string, unknown>): void;
+    info(message: string, attributes?: Record<string, unknown>): void;
+    warn(message: string, attributes?: Record<string, unknown>): void;
+    error(message: string, attributes?: Record<string, unknown>): void;
+    child(name: string, attributes?: Record<string, unknown>): CelerityLogger;
+    withContext(attributes: Record<string, unknown>): CelerityLogger;
+}
+
+declare class OTelTracer implements CelerityTracer {
+    private tracer;
+    startSpan(name: string, attributes?: Record<string, unknown>): CeleritySpan;
+    withSpan<T>(name: string, fn: (span: CeleritySpan) => T | Promise<T>, attributes?: Record<string, unknown>): Promise<T>;
+}
+declare class OTelSpan implements CeleritySpan {
+    private span;
+    constructor(span: Span);
+    setAttribute(key: string, value: string | number | boolean): void;
+    setAttributes(attributes: Record<string, string | number | boolean>): void;
+    recordError(error: Error): void;
+    setOk(): void;
+    end(): void;
+}
+
+declare class NoopTracer implements CelerityTracer {
+    startSpan(): CeleritySpan;
+    withSpan<T>(_name: string, fn: (span: CeleritySpan) => T | Promise<T>): Promise<T>;
+}
+declare const NOOP_SPAN: CeleritySpan;
+
+declare const LOGGER_TOKEN = "CelerityLogger";
+declare const TRACER_TOKEN = "CelerityTracer";
+
+declare function extractTraceContext(request: HttpRequest): Context;
+
+declare function getLogger(container: ServiceContainer): Promise<CelerityLogger>;
+declare function getTracer(container: ServiceContainer): Promise<CelerityTracer>;
+
+export { CelerityLoggerImpl, ContextAwareLogger, LOGGER_TOKEN, NOOP_SPAN, NoopTracer, OTelSpan, OTelTracer, TRACER_TOKEN, type TelemetryConfig, TelemetryLayer, createLogger, extractTraceContext, getLogger, getRequestLogger, getTracer, readTelemetryEnv };