@senad-d/observme 0.1.0

package/src/otel/metrics.ts

@@ -0,0 +1,165 @@
+import type { Meter } from "@opentelemetry/api";
+import { createNoopMeter, metrics } from "@opentelemetry/api";
+import type { Resource } from "@opentelemetry/resources";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-proto";
+import type { IMetricReader, PushMetricExporter } from "@opentelemetry/sdk-metrics";
+import { MeterProvider, PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
+import type { MetricsConfig, ObservMeConfig } from "../config/schema.ts";
+import { appendOtlpSignalPath } from "./otlp-endpoint.ts";
+import type { StartOtelSdkFactoryOptions } from "./sdk.ts";
+
+export const OBSERVME_METER_NAME = "@senad-d/observme";
+export const OTLP_METRIC_SIGNAL_PATH = "/v1/metrics";
+
+export const DOCUMENTED_METRIC_EXPORT_DEFAULTS = {
+  exportIntervalMillis: 15000,
+  exportTimeoutMillis: 3000,
+} satisfies Pick<MetricsConfig, "exportIntervalMillis" | "exportTimeoutMillis">;
+
+export type MetricPipelineState = "idle" | "disabled" | "started" | "shutdown";
+
+export interface OtlpMetricExporterOptions {
+  readonly url: string;
+  readonly headers: Record<string, string>;
+  readonly timeoutMillis: number;
+}
+
+export interface MetricReaderOptions {
+  readonly exportIntervalMillis: number;
+  readonly exportTimeoutMillis: number;
+}
+
+export interface MetricProviderOptions {
+  readonly resource: Resource;
+  readonly readers: IMetricReader[];
+}
+
+export interface MetricProviderLike {
+  getMeter: (name: string) => Meter;
+  forceFlush?: () => Promise<void> | void;
+  shutdown?: () => Promise<void> | void;
+}
+
+export type MetricExporterFactory = (options: OtlpMetricExporterOptions) => PushMetricExporter;
+export type MetricReaderFactory = (exporter: PushMetricExporter, options: MetricReaderOptions) => IMetricReader;
+export type MetricProviderFactory = (options: MetricProviderOptions) => MetricProviderLike;
+
+export interface ObservMeMetricSdkOptions {
+  readonly config: ObservMeConfig;
+  readonly meterName?: string;
+  readonly registerGlobal?: boolean;
+  readonly exporterFactory?: MetricExporterFactory;
+  readonly readerFactory?: MetricReaderFactory;
+  readonly meterProviderFactory?: MetricProviderFactory;
+}
+
+export interface MetricExporterWiring {
+  readonly enabled: boolean;
+  readonly exporter: OtlpMetricExporterOptions;
+  readonly reader: MetricReaderOptions;
+}
+
+const noopMeter = createNoopMeter();
+
+export class ObservMeMetricSdk {
+  readonly #config: ObservMeConfig;
+  readonly #meterName: string;
+  readonly #registerGlobal: boolean;
+  readonly #exporterFactory: MetricExporterFactory;
+  readonly #readerFactory: MetricReaderFactory;
+  readonly #meterProviderFactory: MetricProviderFactory;
+  #provider?: MetricProviderLike;
+  #meter: Meter = noopMeter;
+  #state: MetricPipelineState = "idle";
+
+  constructor(options: ObservMeMetricSdkOptions) {
+    this.#config = options.config;
+    this.#meterName = options.meterName ?? OBSERVME_METER_NAME;
+    this.#registerGlobal = options.registerGlobal ?? true;
+    this.#exporterFactory = options.exporterFactory ?? createOtlpMetricExporter;
+    this.#readerFactory = options.readerFactory ?? createPeriodicMetricReader;
+    this.#meterProviderFactory = options.meterProviderFactory ?? createMetricProvider;
+  }
+
+  get state(): MetricPipelineState {
+    return this.#state;
+  }
+
+  get meter(): Meter {
+    return this.#meter;
+  }
+
+  start(): void {
+    if (this.#state === "started" || this.#state === "disabled") return;
+    if (!this.#config.metrics.enabled) {
+      this.#state = "disabled";
+      return;
+    }
+
+    const wiring = buildMetricExporterWiring(this.#config);
+    const exporter = this.#exporterFactory(wiring.exporter);
+    const reader = this.#readerFactory(exporter, wiring.reader);
+    this.#provider = this.#meterProviderFactory({
+      resource: createMetricResource(this.#config),
+      readers: [reader],
+    });
+
+    if (this.#registerGlobal) metrics.setGlobalMeterProvider(this.#provider);
+    this.#meter = this.#provider.getMeter(this.#meterName);
+    this.#state = "started";
+  }
+
+  async forceFlush(): Promise<void> {
+    await this.#provider?.forceFlush?.();
+  }
+
+  async shutdown(): Promise<void> {
+    await this.#provider?.shutdown?.();
+    this.#state = "shutdown";
+    this.#meter = noopMeter;
+  }
+}
+
+export function createMetricSessionScopedOtelSdk(options: StartOtelSdkFactoryOptions): ObservMeMetricSdk {
+  return new ObservMeMetricSdk({ config: options.config });
+}
+
+export function buildMetricExporterWiring(config: ObservMeConfig): MetricExporterWiring {
+  return {
+    enabled: config.metrics.enabled,
+    exporter: buildOtlpMetricExporterOptions(config),
+    reader: {
+      exportIntervalMillis: config.metrics.exportIntervalMillis,
+      exportTimeoutMillis: config.metrics.exportTimeoutMillis,
+    },
+  };
+}
+
+export function buildOtlpMetricExporterOptions(config: ObservMeConfig): OtlpMetricExporterOptions {
+  return {
+    url: resolveMetricEndpoint(config),
+    headers: { ...config.otlp.headers },
+    timeoutMillis: config.otlp.timeoutMs,
+  };
+}
+
+export function resolveMetricEndpoint(config: ObservMeConfig): string {
+  return config.otlp.signalEndpoints?.metrics ?? appendOtlpSignalPath(config.otlp.endpoint, OTLP_METRIC_SIGNAL_PATH);
+}
+
+function createOtlpMetricExporter(options: OtlpMetricExporterOptions): PushMetricExporter {
+  return new OTLPMetricExporter(options);
+}
+
+function createPeriodicMetricReader(exporter: PushMetricExporter, options: MetricReaderOptions): IMetricReader {
+  return new PeriodicExportingMetricReader({ exporter, ...options });
+}
+
+function createMetricProvider(options: MetricProviderOptions): MetricProviderLike {
+  return new MeterProvider(options);
+}
+
+function createMetricResource(config: ObservMeConfig): Resource {
+  return resourceFromAttributes(config.resource.attributes);
+}

package/src/otel/otlp-endpoint.ts

@@ -0,0 +1,10 @@
+export function appendOtlpSignalPath(baseEndpoint: string, signalPath: string): string {
+  const trimmedBaseEndpoint = removeTrailingSlashes(baseEndpoint);
+  return `${trimmedBaseEndpoint}${signalPath}`;
+}
+
+function removeTrailingSlashes(value: string): string {
+  let end = value.length;
+  while (end > 0 && value[end - 1] === "/") end -= 1;
+  return value.slice(0, end);
+}

package/src/otel/sdk.ts

@@ -0,0 +1,114 @@
+import type { ObservMeConfig } from "../config/schema.ts";
+import type { AgentLineageContext } from "../pi/agent-lineage.ts";
+import type { BoundedOtelOperationResult, OtelShutdownLogSink, ShutdownableOtelSdk } from "./shutdown.ts";
+import { flushOtelSdk, shutdownOtelSdk } from "./shutdown.ts";
+
+export type OtelSdkLifecycleState = "idle" | "starting" | "started" | "shutting_down" | "shutdown";
+
+export interface StartOtelSdkFactoryOptions {
+  readonly config: ObservMeConfig;
+  readonly agent?: AgentLineageContext;
+}
+
+export interface SessionScopedOtelSdk extends ShutdownableOtelSdk {
+  start?: () => Promise<void> | void;
+}
+
+export type SessionScopedOtelSdkFactory = (options: StartOtelSdkFactoryOptions) => SessionScopedOtelSdk;
+
+export interface ObservMeOtelSdkControllerOptions {
+  readonly config: ObservMeConfig;
+  readonly agent?: AgentLineageContext;
+  readonly sdkFactory?: SessionScopedOtelSdkFactory;
+  readonly logger?: OtelShutdownLogSink;
+}
+
+export interface ObservMeOtelSdkControllerSnapshot {
+  readonly state: OtelSdkLifecycleState;
+  readonly started: boolean;
+  readonly shutdown: boolean;
+}
+
+export class ObservMeOtelSdkController {
+  readonly #config: ObservMeConfig;
+  readonly #agent?: AgentLineageContext;
+  readonly #sdkFactory: SessionScopedOtelSdkFactory;
+  readonly #logger?: OtelShutdownLogSink;
+  #sdk?: SessionScopedOtelSdk;
+  #state: OtelSdkLifecycleState = "idle";
+
+  constructor(options: ObservMeOtelSdkControllerOptions) {
+    this.#config = options.config;
+    this.#agent = options.agent;
+    this.#sdkFactory = options.sdkFactory ?? createNoopSessionScopedOtelSdk;
+    this.#logger = options.logger;
+  }
+
+  get state(): OtelSdkLifecycleState {
+    return this.#state;
+  }
+
+  get sdk(): SessionScopedOtelSdk | undefined {
+    return this.#sdk;
+  }
+
+  snapshot(): ObservMeOtelSdkControllerSnapshot {
+    return {
+      state: this.#state,
+      started: this.#state === "started",
+      shutdown: this.#state === "shutdown",
+    };
+  }
+
+  async start(): Promise<SessionScopedOtelSdk> {
+    if (this.#state === "started" && this.#sdk) return this.#sdk;
+    if (this.#state === "shutdown") throw new Error("ObservMe OTEL SDK controller cannot be restarted after shutdown.");
+
+    this.#state = "starting";
+    this.#sdk = this.#sdkFactory({ config: this.#config, agent: this.#agent });
+    await this.#sdk.start?.();
+    this.#state = "started";
+    return this.#sdk;
+  }
+
+  async flush(timeoutMs: number = this.#config.shutdown.flushTimeoutMs): Promise<BoundedOtelOperationResult> {
+    return flushOtelSdk(this.#sdk, timeoutMs, this.#logger);
+  }
+
+  async shutdown(timeoutMs: number = this.#config.shutdown.flushTimeoutMs): Promise<BoundedOtelOperationResult> {
+    if (this.#state === "shutdown") return { operation: "shutdown", completed: true, timedOut: false };
+
+    this.#state = "shutting_down";
+    const result = await shutdownOtelSdk(this.#sdk, timeoutMs, this.#logger);
+    this.#state = "shutdown";
+    return result;
+  }
+}
+
+export function createOtelSdkController(options: ObservMeOtelSdkControllerOptions): ObservMeOtelSdkController {
+  return new ObservMeOtelSdkController(options);
+}
+
+export async function startOtelSdk(options: ObservMeOtelSdkControllerOptions): Promise<ObservMeOtelSdkController> {
+  const controller = createOtelSdkController(options);
+  await controller.start();
+  return controller;
+}
+
+export function createNoopSessionScopedOtelSdk(): SessionScopedOtelSdk {
+  return new NoopSessionScopedOtelSdk();
+}
+
+class NoopSessionScopedOtelSdk implements SessionScopedOtelSdk {
+  async start(): Promise<void> {
+    await Promise.resolve();
+  }
+
+  async forceFlush(): Promise<void> {
+    await Promise.resolve();
+  }
+
+  async shutdown(): Promise<void> {
+    await Promise.resolve();
+  }
+}

package/src/otel/shutdown.ts

@@ -0,0 +1,102 @@
+import { setTimeout as delay } from "node:timers/promises";
+import { readDiagnosticMessage, sanitizeDiagnosticText } from "../diagnostics/sanitize.ts";
+
+export interface FlushableOtelSdk {
+  forceFlush?: () => Promise<void> | void;
+}
+
+export interface ShutdownableOtelSdk extends FlushableOtelSdk {
+  shutdown?: () => Promise<void> | void;
+}
+
+export interface BoundedOtelOperationResult {
+  readonly operation: "flush" | "shutdown";
+  readonly completed: boolean;
+  readonly timedOut: boolean;
+  readonly error?: unknown;
+}
+
+export interface OtelShutdownLogSink {
+  warn?: (message: string) => void;
+}
+
+export async function flushOtelSdk(
+  sdk: FlushableOtelSdk | undefined,
+  timeoutMs: number,
+  logger?: OtelShutdownLogSink,
+): Promise<BoundedOtelOperationResult> {
+  if (!sdk?.forceFlush) return completedOperation("flush");
+
+  const result = await runBoundedOtelOperation("flush", sdk.forceFlush.bind(sdk), timeoutMs);
+  logBoundedOperationIssue(result, logger);
+  return result;
+}
+
+export async function shutdownOtelSdk(
+  sdk: ShutdownableOtelSdk | undefined,
+  timeoutMs: number,
+  logger?: OtelShutdownLogSink,
+): Promise<BoundedOtelOperationResult> {
+  if (!sdk?.shutdown) return completedOperation("shutdown");
+
+  const result = await runBoundedOtelOperation("shutdown", sdk.shutdown.bind(sdk), timeoutMs);
+  logBoundedOperationIssue(result, logger);
+  return result;
+}
+
+export async function runBoundedOtelOperation(
+  operation: "flush" | "shutdown",
+  action: () => Promise<void> | void,
+  timeoutMs: number,
+): Promise<BoundedOtelOperationResult> {
+  const normalizedTimeoutMs = normalizeTimeoutMs(timeoutMs);
+  const timeoutController = new AbortController();
+  const timeoutResult = timeoutOperation(operation, normalizedTimeoutMs, timeoutController.signal);
+
+  try {
+    const completed = completeOperation(operation, action);
+    return await Promise.race([completed, timeoutResult]);
+  } catch (error) {
+    return { operation, completed: false, timedOut: false, error };
+  } finally {
+    timeoutController.abort();
+  }
+}
+
+function normalizeTimeoutMs(timeoutMs: number): number {
+  if (!Number.isFinite(timeoutMs) || timeoutMs < 0) return 0;
+  return timeoutMs;
+}
+
+async function completeOperation(
+  operation: "flush" | "shutdown",
+  action: () => Promise<void> | void,
+): Promise<BoundedOtelOperationResult> {
+  await action();
+  return completedOperation(operation);
+}
+
+async function timeoutOperation(
+  operation: "flush" | "shutdown",
+  timeoutMs: number,
+  signal: AbortSignal,
+): Promise<BoundedOtelOperationResult> {
+  return delay(timeoutMs, { operation, completed: false, timedOut: true } as const, { signal });
+}
+
+function completedOperation(operation: "flush" | "shutdown"): BoundedOtelOperationResult {
+  return { operation, completed: true, timedOut: false };
+}
+
+function logBoundedOperationIssue(result: BoundedOtelOperationResult, logger: OtelShutdownLogSink | undefined): void {
+  if (result.timedOut) {
+    logger?.warn?.(`ObservMe OTEL ${result.operation} exceeded timeout and was abandoned.`);
+    return;
+  }
+
+  if (result.error) logger?.warn?.(`ObservMe OTEL ${result.operation} failed: ${formatError(result.error)}`);
+}
+
+function formatError(error: unknown): string {
+  return sanitizeDiagnosticText(readDiagnosticMessage(error));
+}

package/src/otel/traces.ts

@@ -0,0 +1,166 @@
+import type { Tracer } from "@opentelemetry/api";
+import type { Resource } from "@opentelemetry/resources";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
+import type { Sampler, SpanExporter, SpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { BatchSpanProcessor, ParentBasedSampler, TraceIdRatioBasedSampler } from "@opentelemetry/sdk-trace-base";
+import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
+import type { ObservMeConfig, TraceBatchConfig } from "../config/schema.ts";
+import { appendOtlpSignalPath } from "./otlp-endpoint.ts";
+import type { StartOtelSdkFactoryOptions } from "./sdk.ts";
+
+export const OBSERVME_TRACER_NAME = "@senad-d/observme";
+export const OTLP_TRACE_SIGNAL_PATH = "/v1/traces";
+
+export const DOCUMENTED_TRACE_BATCH_DEFAULTS = {
+  maxQueueSize: 2048,
+  maxExportBatchSize: 512,
+  scheduledDelayMillis: 1000,
+  exportTimeoutMillis: 3000,
+} satisfies TraceBatchConfig;
+
+export type TracePipelineState = "idle" | "disabled" | "started" | "shutdown";
+
+export interface OtlpTraceExporterOptions {
+  readonly url: string;
+  readonly headers: Record<string, string>;
+  readonly timeoutMillis: number;
+}
+
+export interface TraceProviderOptions {
+  readonly resource: Resource;
+  readonly sampler: Sampler;
+  readonly spanProcessors: SpanProcessor[];
+  readonly forceFlushTimeoutMillis: number;
+}
+
+export interface TraceProviderLike {
+  register?: () => void;
+  getTracer: (name: string) => Tracer;
+  forceFlush?: () => Promise<void> | void;
+  shutdown?: () => Promise<void> | void;
+}
+
+export type TraceExporterFactory = (options: OtlpTraceExporterOptions) => SpanExporter;
+export type TraceSpanProcessorFactory = (exporter: SpanExporter, options: TraceBatchConfig) => SpanProcessor;
+export type TraceProviderFactory = (options: TraceProviderOptions) => TraceProviderLike;
+
+export interface ObservMeTraceSdkOptions {
+  readonly config: ObservMeConfig;
+  readonly tracerName?: string;
+  readonly registerGlobal?: boolean;
+  readonly exporterFactory?: TraceExporterFactory;
+  readonly spanProcessorFactory?: TraceSpanProcessorFactory;
+  readonly tracerProviderFactory?: TraceProviderFactory;
+}
+
+export interface TraceExporterWiring {
+  readonly enabled: boolean;
+  readonly exporter: OtlpTraceExporterOptions;
+  readonly batch: TraceBatchConfig;
+}
+
+export class ObservMeTraceSdk {
+  readonly #config: ObservMeConfig;
+  readonly #tracerName: string;
+  readonly #registerGlobal: boolean;
+  readonly #exporterFactory: TraceExporterFactory;
+  readonly #spanProcessorFactory: TraceSpanProcessorFactory;
+  readonly #tracerProviderFactory: TraceProviderFactory;
+  #provider?: TraceProviderLike;
+  #tracer?: Tracer;
+  #state: TracePipelineState = "idle";
+
+  constructor(options: ObservMeTraceSdkOptions) {
+    this.#config = options.config;
+    this.#tracerName = options.tracerName ?? OBSERVME_TRACER_NAME;
+    this.#registerGlobal = options.registerGlobal ?? true;
+    this.#exporterFactory = options.exporterFactory ?? createOtlpTraceExporter;
+    this.#spanProcessorFactory = options.spanProcessorFactory ?? createBatchSpanProcessor;
+    this.#tracerProviderFactory = options.tracerProviderFactory ?? createNodeTraceProvider;
+  }
+
+  get state(): TracePipelineState {
+    return this.#state;
+  }
+
+  get tracer(): Tracer | undefined {
+    return this.#tracer;
+  }
+
+  start(): void {
+    if (this.#state === "started" || this.#state === "disabled") return;
+    if (!this.#config.traces.enabled) {
+      this.#state = "disabled";
+      return;
+    }
+
+    const wiring = buildTraceExporterWiring(this.#config);
+    const exporter = this.#exporterFactory(wiring.exporter);
+    const processor = this.#spanProcessorFactory(exporter, wiring.batch);
+    this.#provider = this.#tracerProviderFactory({
+      resource: createTraceResource(this.#config),
+      sampler: createTraceSampler(this.#config),
+      spanProcessors: [processor],
+      forceFlushTimeoutMillis: this.#config.shutdown.flushTimeoutMs,
+    });
+
+    if (this.#registerGlobal) this.#provider.register?.();
+    this.#tracer = this.#provider.getTracer(this.#tracerName);
+    this.#state = "started";
+  }
+
+  async forceFlush(): Promise<void> {
+    await this.#provider?.forceFlush?.();
+  }
+
+  async shutdown(): Promise<void> {
+    await this.#provider?.shutdown?.();
+    this.#state = "shutdown";
+    this.#tracer = undefined;
+  }
+}
+
+export function createTraceSessionScopedOtelSdk(options: StartOtelSdkFactoryOptions): ObservMeTraceSdk {
+  return new ObservMeTraceSdk({ config: options.config });
+}
+
+export function buildTraceExporterWiring(config: ObservMeConfig): TraceExporterWiring {
+  return {
+    enabled: config.traces.enabled,
+    exporter: buildOtlpTraceExporterOptions(config),
+    batch: { ...config.traces.batch },
+  };
+}
+
+export function buildOtlpTraceExporterOptions(config: ObservMeConfig): OtlpTraceExporterOptions {
+  return {
+    url: resolveTraceEndpoint(config),
+    headers: { ...config.otlp.headers },
+    timeoutMillis: config.otlp.timeoutMs,
+  };
+}
+
+export function resolveTraceEndpoint(config: ObservMeConfig): string {
+  return config.otlp.signalEndpoints?.traces ?? appendOtlpSignalPath(config.otlp.endpoint, OTLP_TRACE_SIGNAL_PATH);
+}
+
+function createOtlpTraceExporter(options: OtlpTraceExporterOptions): SpanExporter {
+  return new OTLPTraceExporter(options);
+}
+
+function createBatchSpanProcessor(exporter: SpanExporter, options: TraceBatchConfig): SpanProcessor {
+  return new BatchSpanProcessor(exporter, options);
+}
+
+function createNodeTraceProvider(options: TraceProviderOptions): TraceProviderLike {
+  return new NodeTracerProvider(options);
+}
+
+function createTraceResource(config: ObservMeConfig): Resource {
+  return resourceFromAttributes(config.resource.attributes);
+}
+
+function createTraceSampler(config: ObservMeConfig): Sampler {
+  return new ParentBasedSampler({ root: new TraceIdRatioBasedSampler(config.traces.sampleRatio) });
+}