@typokit/otel 0.1.4

package/src/log-bridge.test.ts

@@ -0,0 +1,511 @@
+import { describe, it, expect } from "@rstest/core";
+import { OtelLogSink, createOtelLogSink } from "./log-bridge.js";
+import { StructuredLogger } from "./logger.js";
+import type { LogEntry, LogSink } from "./types.js";
+
+/** Test sink that captures log entries */
+class TestSink implements LogSink {
+  entries: LogEntry[] = [];
+  write(entry: LogEntry): void {
+    this.entries.push(entry);
+  }
+}
+
+describe("OtelLogSink", () => {
+  it("should be constructable with default options", () => {
+    const sink = new OtelLogSink();
+    expect(sink).toBeDefined();
+    expect(typeof sink.write).toBe("function");
+  });
+
+  it("should be constructable with custom endpoint and serviceName", () => {
+    const sink = new OtelLogSink({
+      endpoint: "http://collector:4318/v1/logs",
+      serviceName: "my-service",
+    });
+    expect(sink).toBeDefined();
+  });
+
+  it("should forward log entries to OTel collector with correct OTLP format", () => {
+    const fetchCalls: Array<{ url: string; init: Record<string, unknown> }> =
+      [];
+    const originalFetch = (globalThis as unknown as Record<string, unknown>)[
+      "fetch"
+    ];
+    (globalThis as unknown as Record<string, unknown>)["fetch"] = (
+      url: string,
+      init: Record<string, unknown>,
+    ) => {
+      fetchCalls.push({ url, init });
+      return Promise.resolve({ ok: true });
+    };
+
+    try {
+      const sink = new OtelLogSink({
+        endpoint: "http://test:4318/v1/logs",
+        serviceName: "test-svc",
+      });
+      const entry: LogEntry = {
+        level: "info",
+        message: "test log message",
+        timestamp: "2026-01-01T00:00:00.000Z",
+        route: "GET /users",
+        phase: "handler",
+        requestId: "req-123",
+      };
+
+      sink.write(entry);
+
+      expect(fetchCalls).toHaveLength(1);
+      expect(fetchCalls[0].url).toBe("http://test:4318/v1/logs");
+
+      const body = JSON.parse(fetchCalls[0].init["body"] as string);
+      const resourceLogs = body.resourceLogs;
+      expect(resourceLogs).toHaveLength(1);
+
+      // Check resource service.name
+      const resource = resourceLogs[0].resource;
+      expect(resource.attributes[0].key).toBe("service.name");
+      expect(resource.attributes[0].value.stringValue).toBe("test-svc");
+
+      // Check scope
+      const scopeLogs = resourceLogs[0].scopeLogs;
+      expect(scopeLogs[0].scope.name).toBe("@typokit/otel");
+
+      // Check log record
+      const logRecord = scopeLogs[0].logRecords[0];
+      expect(logRecord.severityNumber).toBe(9); // INFO
+      expect(logRecord.severityText).toBe("INFO");
+      expect(logRecord.body.stringValue).toBe("test log message");
+      expect(logRecord.timeUnixNano).toBe(
+        new Date("2026-01-01T00:00:00.000Z").getTime() * 1_000_000,
+      );
+    } finally {
+      if (originalFetch !== undefined) {
+        (globalThis as unknown as Record<string, unknown>)["fetch"] =
+          originalFetch;
+      } else {
+        delete (globalThis as unknown as Record<string, unknown>)["fetch"];
+      }
+    }
+  });
+
+  it("should include traceId in log record for correlation", () => {
+    const fetchCalls: Array<{ url: string; init: Record<string, unknown> }> =
+      [];
+    const originalFetch = (globalThis as unknown as Record<string, unknown>)[
+      "fetch"
+    ];
+    (globalThis as unknown as Record<string, unknown>)["fetch"] = (
+      url: string,
+      init: Record<string, unknown>,
+    ) => {
+      fetchCalls.push({ url, init });
+      return Promise.resolve({ ok: true });
+    };
+
+    try {
+      const sink = new OtelLogSink();
+      const entry: LogEntry = {
+        level: "error",
+        message: "something failed",
+        timestamp: "2026-01-01T00:00:00.000Z",
+        traceId: "abcdef0123456789abcdef0123456789",
+      };
+
+      sink.write(entry);
+
+      const body = JSON.parse(fetchCalls[0].init["body"] as string);
+      const logRecord = body.resourceLogs[0].scopeLogs[0].logRecords[0];
+      expect(logRecord.traceId).toBe("abcdef0123456789abcdef0123456789");
+    } finally {
+      if (originalFetch !== undefined) {
+        (globalThis as unknown as Record<string, unknown>)["fetch"] =
+          originalFetch;
+      } else {
+        delete (globalThis as unknown as Record<string, unknown>)["fetch"];
+      }
+    }
+  });
+
+  it("should include spanId from data field for correlation", () => {
+    const fetchCalls: Array<{ url: string; init: Record<string, unknown> }> =
+      [];
+    const originalFetch = (globalThis as unknown as Record<string, unknown>)[
+      "fetch"
+    ];
+    (globalThis as unknown as Record<string, unknown>)["fetch"] = (
+      url: string,
+      init: Record<string, unknown>,
+    ) => {
+      fetchCalls.push({ url, init });
+      return Promise.resolve({ ok: true });
+    };
+
+    try {
+      const sink = new OtelLogSink();
+      const entry: LogEntry = {
+        level: "info",
+        message: "in span",
+        timestamp: "2026-01-01T00:00:00.000Z",
+        traceId: "trace123",
+        data: { spanId: "span456", userId: "u1" },
+      };
+
+      sink.write(entry);
+
+      const body = JSON.parse(fetchCalls[0].init["body"] as string);
+      const logRecord = body.resourceLogs[0].scopeLogs[0].logRecords[0];
+      expect(logRecord.traceId).toBe("trace123");
+      expect(logRecord.spanId).toBe("span456");
+
+      // spanId should NOT appear in attributes (used as top-level field)
+      const attrKeys = logRecord.attributes.map((a: { key: string }) => a.key);
+      expect(attrKeys.includes("data.spanId")).toBe(false);
+      // userId should appear in attributes
+      expect(attrKeys.includes("data.userId")).toBe(true);
+    } finally {
+      if (originalFetch !== undefined) {
+        (globalThis as unknown as Record<string, unknown>)["fetch"] =
+          originalFetch;
+      } else {
+        delete (globalThis as unknown as Record<string, unknown>)["fetch"];
+      }
+    }
+  });
+
+  it("should map all log levels to correct OTel severity numbers", () => {
+    const fetchCalls: Array<{ url: string; init: Record<string, unknown> }> =
+      [];
+    const originalFetch = (globalThis as unknown as Record<string, unknown>)[
+      "fetch"
+    ];
+    (globalThis as unknown as Record<string, unknown>)["fetch"] = (
+      url: string,
+      init: Record<string, unknown>,
+    ) => {
+      fetchCalls.push({ url, init });
+      return Promise.resolve({ ok: true });
+    };
+
+    try {
+      const sink = new OtelLogSink();
+      const levels = [
+        { level: "trace", num: 1, text: "TRACE" },
+        { level: "debug", num: 5, text: "DEBUG" },
+        { level: "info", num: 9, text: "INFO" },
+        { level: "warn", num: 13, text: "WARN" },
+        { level: "error", num: 17, text: "ERROR" },
+        { level: "fatal", num: 21, text: "FATAL" },
+      ] as const;
+
+      for (const l of levels) {
+        sink.write({
+          level: l.level,
+          message: `msg-${l.level}`,
+          timestamp: "2026-01-01T00:00:00.000Z",
+        });
+      }
+
+      expect(fetchCalls).toHaveLength(6);
+      for (let i = 0; i < levels.length; i++) {
+        const body = JSON.parse(fetchCalls[i].init["body"] as string);
+        const logRecord = body.resourceLogs[0].scopeLogs[0].logRecords[0];
+        expect(logRecord.severityNumber).toBe(levels[i].num);
+        expect(logRecord.severityText).toBe(levels[i].text);
+      }
+    } finally {
+      if (originalFetch !== undefined) {
+        (globalThis as unknown as Record<string, unknown>)["fetch"] =
+          originalFetch;
+      } else {
+        delete (globalThis as unknown as Record<string, unknown>)["fetch"];
+      }
+    }
+  });
+
+  it("should include route, phase, requestId, serverAdapter as OTLP attributes", () => {
+    const fetchCalls: Array<{ url: string; init: Record<string, unknown> }> =
+      [];
+    const originalFetch = (globalThis as unknown as Record<string, unknown>)[
+      "fetch"
+    ];
+    (globalThis as unknown as Record<string, unknown>)["fetch"] = (
+      url: string,
+      init: Record<string, unknown>,
+    ) => {
+      fetchCalls.push({ url, init });
+      return Promise.resolve({ ok: true });
+    };
+
+    try {
+      const sink = new OtelLogSink();
+      sink.write({
+        level: "info",
+        message: "test",
+        timestamp: "2026-01-01T00:00:00.000Z",
+        route: "POST /items",
+        phase: "validation",
+        requestId: "req-789",
+        serverAdapter: "native",
+      });
+
+      const body = JSON.parse(fetchCalls[0].init["body"] as string);
+      const attrs = body.resourceLogs[0].scopeLogs[0].logRecords[0].attributes;
+      const attrMap = new Map(
+        attrs.map((a: { key: string; value: { stringValue: string } }) => [
+          a.key,
+          a.value.stringValue,
+        ]),
+      );
+
+      expect(attrMap.get("route")).toBe("POST /items");
+      expect(attrMap.get("phase")).toBe("validation");
+      expect(attrMap.get("requestId")).toBe("req-789");
+      expect(attrMap.get("serverAdapter")).toBe("native");
+    } finally {
+      if (originalFetch !== undefined) {
+        (globalThis as unknown as Record<string, unknown>)["fetch"] =
+          originalFetch;
+      } else {
+        delete (globalThis as unknown as Record<string, unknown>)["fetch"];
+      }
+    }
+  });
+
+  it("should silently handle missing fetch", () => {
+    const originalFetch = (globalThis as unknown as Record<string, unknown>)[
+      "fetch"
+    ];
+    delete (globalThis as unknown as Record<string, unknown>)["fetch"];
+
+    try {
+      const sink = new OtelLogSink();
+      // Should not throw
+      sink.write({
+        level: "info",
+        message: "no fetch",
+        timestamp: "2026-01-01T00:00:00.000Z",
+      });
+    } finally {
+      if (originalFetch !== undefined) {
+        (globalThis as unknown as Record<string, unknown>)["fetch"] =
+          originalFetch;
+      }
+    }
+  });
+});
+
+describe("createOtelLogSink", () => {
+  it("should return undefined when no telemetry config", () => {
+    const sink = createOtelLogSink();
+    expect(sink).toBeUndefined();
+  });
+
+  it("should return undefined when tracing is disabled", () => {
+    const sink = createOtelLogSink({ tracing: false });
+    expect(sink).toBeUndefined();
+  });
+
+  it("should return undefined when tracing.enabled is false", () => {
+    const sink = createOtelLogSink({ tracing: { enabled: false } });
+    expect(sink).toBeUndefined();
+  });
+
+  it("should return OtelLogSink when tracing is true", () => {
+    const sink = createOtelLogSink({ tracing: true });
+    expect(sink).toBeDefined();
+    expect(sink).toBeInstanceOf(OtelLogSink);
+  });
+
+  it("should return OtelLogSink when tracing is configured as object", () => {
+    const sink = createOtelLogSink({
+      tracing: {
+        enabled: true,
+        exporter: "otlp",
+        endpoint: "http://collector:4318/v1/traces",
+      },
+    });
+    expect(sink).toBeDefined();
+    expect(sink).toBeInstanceOf(OtelLogSink);
+  });
+
+  it("should derive logs endpoint from traces endpoint", () => {
+    const fetchCalls: Array<{ url: string; init: Record<string, unknown> }> =
+      [];
+    const originalFetch = (globalThis as unknown as Record<string, unknown>)[
+      "fetch"
+    ];
+    (globalThis as unknown as Record<string, unknown>)["fetch"] = (
+      url: string,
+      init: Record<string, unknown>,
+    ) => {
+      fetchCalls.push({ url, init });
+      return Promise.resolve({ ok: true });
+    };
+
+    try {
+      const sink = createOtelLogSink({
+        tracing: { enabled: true, endpoint: "http://collector:4318/v1/traces" },
+      });
+      expect(sink).toBeDefined();
+
+      sink!.write({
+        level: "info",
+        message: "test endpoint",
+        timestamp: "2026-01-01T00:00:00.000Z",
+      });
+
+      expect(fetchCalls[0].url).toBe("http://collector:4318/v1/logs");
+    } finally {
+      if (originalFetch !== undefined) {
+        (globalThis as unknown as Record<string, unknown>)["fetch"] =
+          originalFetch;
+      } else {
+        delete (globalThis as unknown as Record<string, unknown>)["fetch"];
+      }
+    }
+  });
+
+  it("should use serviceName from telemetry config", () => {
+    const fetchCalls: Array<{ url: string; init: Record<string, unknown> }> =
+      [];
+    const originalFetch = (globalThis as unknown as Record<string, unknown>)[
+      "fetch"
+    ];
+    (globalThis as unknown as Record<string, unknown>)["fetch"] = (
+      url: string,
+      init: Record<string, unknown>,
+    ) => {
+      fetchCalls.push({ url, init });
+      return Promise.resolve({ ok: true });
+    };
+
+    try {
+      const sink = createOtelLogSink({ tracing: true, serviceName: "my-app" });
+      expect(sink).toBeDefined();
+
+      sink!.write({
+        level: "info",
+        message: "test svc",
+        timestamp: "2026-01-01T00:00:00.000Z",
+      });
+
+      const body = JSON.parse(fetchCalls[0].init["body"] as string);
+      const svcAttr = body.resourceLogs[0].resource.attributes[0];
+      expect(svcAttr.value.stringValue).toBe("my-app");
+    } finally {
+      if (originalFetch !== undefined) {
+        (globalThis as unknown as Record<string, unknown>)["fetch"] =
+          originalFetch;
+      } else {
+        delete (globalThis as unknown as Record<string, unknown>)["fetch"];
+      }
+    }
+  });
+});
+
+describe("OtelLogSink + StructuredLogger integration", () => {
+  it("should work alongside StdoutSink (both active simultaneously)", () => {
+    const testSink = new TestSink();
+    const otelCalls: Array<{ url: string; init: Record<string, unknown> }> = [];
+    const originalFetch = (globalThis as unknown as Record<string, unknown>)[
+      "fetch"
+    ];
+    (globalThis as unknown as Record<string, unknown>)["fetch"] = (
+      url: string,
+      init: Record<string, unknown>,
+    ) => {
+      otelCalls.push({ url, init });
+      return Promise.resolve({ ok: true });
+    };
+
+    try {
+      const otelSink = new OtelLogSink({ serviceName: "integration-test" });
+      // Both sinks active on the same logger
+      const logger = new StructuredLogger(
+        { level: "trace" },
+        { traceId: "trace-abc", route: "GET /health" },
+        [testSink, otelSink],
+      );
+
+      logger.info("health check", { status: "ok" });
+
+      // TestSink received the entry
+      expect(testSink.entries).toHaveLength(1);
+      expect(testSink.entries[0].message).toBe("health check");
+      expect(testSink.entries[0].traceId).toBe("trace-abc");
+
+      // OtelLogSink sent to collector
+      expect(otelCalls).toHaveLength(1);
+      const body = JSON.parse(otelCalls[0].init["body"] as string);
+      const logRecord = body.resourceLogs[0].scopeLogs[0].logRecords[0];
+      expect(logRecord.body.stringValue).toBe("health check");
+      expect(logRecord.traceId).toBe("trace-abc");
+      expect(logRecord.severityText).toBe("INFO");
+    } finally {
+      if (originalFetch !== undefined) {
+        (globalThis as unknown as Record<string, unknown>)["fetch"] =
+          originalFetch;
+      } else {
+        delete (globalThis as unknown as Record<string, unknown>)["fetch"];
+      }
+    }
+  });
+
+  it("should forward log entries with correct trace context from logger metadata", () => {
+    const otelCalls: Array<{ url: string; init: Record<string, unknown> }> = [];
+    const originalFetch = (globalThis as unknown as Record<string, unknown>)[
+      "fetch"
+    ];
+    (globalThis as unknown as Record<string, unknown>)["fetch"] = (
+      url: string,
+      init: Record<string, unknown>,
+    ) => {
+      otelCalls.push({ url, init });
+      return Promise.resolve({ ok: true });
+    };
+
+    try {
+      const otelSink = new OtelLogSink();
+      const logger = new StructuredLogger(
+        { level: "trace" },
+        {
+          traceId: "aaaa1111bbbb2222cccc3333dddd4444",
+          route: "POST /orders",
+          phase: "handler",
+        },
+        [otelSink],
+      );
+
+      logger.error("order failed", { orderId: "ord-1", spanId: "span-9876" });
+
+      const body = JSON.parse(otelCalls[0].init["body"] as string);
+      const logRecord = body.resourceLogs[0].scopeLogs[0].logRecords[0];
+
+      // Trace context for correlation
+      expect(logRecord.traceId).toBe("aaaa1111bbbb2222cccc3333dddd4444");
+      expect(logRecord.spanId).toBe("span-9876");
+      expect(logRecord.severityNumber).toBe(17); // ERROR
+
+      // Attributes should include route and phase
+      const attrs = logRecord.attributes;
+      const attrMap = new Map(
+        attrs.map((a: { key: string; value: { stringValue: string } }) => [
+          a.key,
+          a.value.stringValue,
+        ]),
+      );
+      expect(attrMap.get("route")).toBe("POST /orders");
+      expect(attrMap.get("phase")).toBe("handler");
+      expect(attrMap.get("data.orderId")).toBe("ord-1");
+    } finally {
+      if (originalFetch !== undefined) {
+        (globalThis as unknown as Record<string, unknown>)["fetch"] =
+          originalFetch;
+      } else {
+        delete (globalThis as unknown as Record<string, unknown>)["fetch"];
+      }
+    }
+  });
+});

package/src/log-bridge.ts

@@ -0,0 +1,150 @@
+import type { LogEntry, LogSink, TelemetryConfig } from "./types.js";
+import { resolveTracingConfig } from "./tracing.js";
+
+// OTel severity numbers per spec (https://opentelemetry.io/docs/specs/otel/logs/data-model/#severity-fields)
+const SEVERITY_NUMBER: Record<string, number> = {
+  trace: 1,
+  debug: 5,
+  info: 9,
+  warn: 13,
+  error: 17,
+  fatal: 21,
+};
+
+const SEVERITY_TEXT: Record<string, string> = {
+  trace: "TRACE",
+  debug: "DEBUG",
+  info: "INFO",
+  warn: "WARN",
+  error: "ERROR",
+  fatal: "FATAL",
+};
+
+/**
+ * OTel log sink that pushes structured log entries to an OTLP-compatible
+ * collector via HTTP POST. Includes trace context (traceId, spanId) for
+ * correlation with distributed traces.
+ */
+export class OtelLogSink implements LogSink {
+  private readonly endpoint: string;
+  private readonly serviceName: string;
+
+  constructor(options?: { endpoint?: string; serviceName?: string }) {
+    this.endpoint = options?.endpoint ?? "http://localhost:4318/v1/logs";
+    this.serviceName = options?.serviceName ?? "typokit";
+  }
+
+  write(entry: LogEntry): void {
+    const fetchFn = (
+      globalThis as unknown as {
+        fetch?: (url: string, init: unknown) => Promise<unknown>;
+      }
+    ).fetch;
+    if (!fetchFn) return;
+
+    const timeUnixNano = new Date(entry.timestamp).getTime() * 1_000_000;
+    const attributes = this.buildAttributes(entry);
+
+    const logRecord: Record<string, unknown> = {
+      timeUnixNano,
+      severityNumber: SEVERITY_NUMBER[entry.level] ?? 9,
+      severityText: SEVERITY_TEXT[entry.level] ?? "INFO",
+      body: { stringValue: entry.message },
+      attributes,
+    };
+
+    // Include trace context for correlation
+    if (entry.traceId) {
+      logRecord["traceId"] = entry.traceId;
+    }
+    if (entry.data?.["spanId"]) {
+      logRecord["spanId"] = String(entry.data["spanId"]);
+    }
+
+    const payload = {
+      resourceLogs: [
+        {
+          resource: {
+            attributes: [
+              { key: "service.name", value: { stringValue: this.serviceName } },
+            ],
+          },
+          scopeLogs: [
+            {
+              scope: { name: "@typokit/otel" },
+              logRecords: [logRecord],
+            },
+          ],
+        },
+      ],
+    };
+
+    // Fire-and-forget POST to OTLP endpoint
+    fetchFn(this.endpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+    }).catch(() => {
+      // Silently ignore export failures
+    });
+  }
+
+  private buildAttributes(
+    entry: LogEntry,
+  ): Array<{ key: string; value: { stringValue: string } }> {
+    const attrs: Array<{ key: string; value: { stringValue: string } }> = [];
+
+    if (entry.route) {
+      attrs.push({ key: "route", value: { stringValue: entry.route } });
+    }
+    if (entry.phase) {
+      attrs.push({ key: "phase", value: { stringValue: entry.phase } });
+    }
+    if (entry.requestId) {
+      attrs.push({ key: "requestId", value: { stringValue: entry.requestId } });
+    }
+    if (entry.serverAdapter) {
+      attrs.push({
+        key: "serverAdapter",
+        value: { stringValue: entry.serverAdapter },
+      });
+    }
+
+    // Include any extra data fields as attributes
+    if (entry.data) {
+      for (const [key, val] of Object.entries(entry.data)) {
+        if (key === "spanId") continue; // Already used as top-level field
+        if (val !== undefined && val !== null) {
+          attrs.push({
+            key: `data.${key}`,
+            value: { stringValue: String(val) },
+          });
+        }
+      }
+    }
+
+    return attrs;
+  }
+}
+
+/**
+ * Creates an OtelLogSink if tracing is configured and enabled.
+ * Returns undefined if tracing is not configured (opt-in behavior).
+ */
+export function createOtelLogSink(
+  telemetry?: TelemetryConfig,
+): OtelLogSink | undefined {
+  if (!telemetry) return undefined;
+
+  const tracingConfig = resolveTracingConfig(telemetry);
+  if (!tracingConfig.enabled) return undefined;
+
+  const endpoint = tracingConfig.endpoint
+    ? tracingConfig.endpoint.replace(/\/v1\/traces\/?$/, "/v1/logs")
+    : "http://localhost:4318/v1/logs";
+
+  return new OtelLogSink({
+    endpoint,
+    serviceName: tracingConfig.serviceName,
+  });
+}