@struktur/telemetry 2.1.1

package/tests/adapters/langfuse.test.ts

@@ -0,0 +1,118 @@
+/**
+ * Unit tests for LangfuseAdapter
+ */
+
+import { test, expect, describe } from "bun:test";
+import { 
+  LangfuseAdapter,
+  createLangfuseAdapter,
+} from "../../src/adapters/langfuse/index.js";
+import type {
+  SpanContext,
+  LangfuseConfig,
+} from "../../src/types.js";
+
+describe("LangfuseAdapter", () => {
+  test("should have correct name and version", () => {
+    const adapter = new LangfuseAdapter({
+      publicKey: "pk-test",
+      secretKey: "sk-test",
+    });
+    
+    expect(adapter.name).toBe("langfuse");
+    expect(adapter.version).toBe("1.0.0");
+  });
+
+  test("should apply default baseUrl", () => {
+    const adapter = new LangfuseAdapter({
+      publicKey: "pk-test",
+      secretKey: "sk-test",
+    });
+    
+    expect(adapter).toBeDefined();
+  });
+
+  test("createLangfuseAdapter should create adapter", () => {
+    const config: LangfuseConfig = {
+      publicKey: "pk-test",
+      secretKey: "sk-test",
+      baseUrl: "https://cloud.langfuse.com",
+      projectName: "my-project",
+    };
+    
+    const adapter = createLangfuseAdapter(config);
+    
+    expect(adapter).toBeDefined();
+    expect(adapter.name).toBe("langfuse");
+  });
+
+  test("should throw when startSpan called before initialize", () => {
+    const adapter = new LangfuseAdapter({
+      publicKey: "pk-test",
+      secretKey: "sk-test",
+    });
+    
+    const context: SpanContext = {
+      name: "test-span",
+      kind: "CHAIN",
+    };
+    
+    expect(() => adapter.startSpan(context)).toThrow("not initialized");
+  });
+
+  test("should accept all span kinds", () => {
+    const adapter = new LangfuseAdapter({
+      publicKey: "pk-test",
+      secretKey: "sk-test",
+    });
+    
+    const kinds = ["CHAIN", "LLM", "TOOL", "AGENT", "RETRIEVER"] as const;
+    
+    for (const _kind of kinds) {
+      expect(adapter).toBeDefined();
+    }
+  });
+});
+
+describe("LangfuseAdapter config", () => {
+  test("should require public and secret keys", () => {
+    const config: LangfuseConfig = {
+      publicKey: "pk-lf-123",
+      secretKey: "sk-lf-456",
+    };
+    
+    const adapter = createLangfuseAdapter(config);
+    
+    expect(adapter).toBeDefined();
+  });
+
+  test("should accept all config options", () => {
+    const config: LangfuseConfig = {
+      publicKey: "pk-test",
+      secretKey: "sk-test",
+      baseUrl: "https://us.cloud.langfuse.com",
+      projectName: "test-project",
+    };
+    
+    const adapter = createLangfuseAdapter(config);
+    
+    expect(adapter).toBeDefined();
+  });
+});
+
+describe("LangfuseAdapter interface", () => {
+  test("should expose required methods", () => {
+    const adapter = new LangfuseAdapter({
+      publicKey: "pk-test",
+      secretKey: "sk-test",
+    });
+    
+    expect(typeof adapter.initialize).toBe("function");
+    expect(typeof adapter.shutdown).toBe("function");
+    expect(typeof adapter.startSpan).toBe("function");
+    expect(typeof adapter.endSpan).toBe("function");
+    expect(typeof adapter.recordEvent).toBe("function");
+    expect(typeof adapter.setAttributes).toBe("function");
+    expect(typeof adapter.setContext).toBe("function");
+  });
+});

package/tests/adapters/phoenix.test.ts

@@ -0,0 +1,132 @@
+/**
+ * Unit tests for PhoenixAdapter
+ * 
+ * These tests verify that the PhoenixAdapter correctly implements
+ * the TelemetryAdapter interface. Since we don't have the actual
+ * dependencies installed, these tests focus on the adapter's logic.
+ */
+
+import { test, expect, describe } from "bun:test";
+import { 
+  PhoenixAdapter,
+  createPhoenixAdapter,
+} from "../../src/adapters/phoenix/index.js";
+import type {
+  SpanContext,
+  SpanResult,
+  LLMCallEvent,
+  ValidationEvent,
+  ChunkEvent,
+  ToolCallEvent,
+  MergeEvent,
+  ParseEvent,
+  PhoenixConfig,
+} from "../../src/types.js";
+
+describe("PhoenixAdapter", () => {
+  test("should have correct name and version", () => {
+    const adapter = new PhoenixAdapter({ projectName: "test" });
+    
+    expect(adapter.name).toBe("phoenix");
+    expect(adapter.version).toBe("1.0.0");
+  });
+
+  test("should apply default config values", () => {
+    const adapter = new PhoenixAdapter({ projectName: "test" });
+    
+    // Default values should be set
+    expect(adapter).toBeDefined();
+  });
+
+  test("createPhoenixAdapter should create adapter", () => {
+    const config: PhoenixConfig = {
+      projectName: "my-project",
+      url: "http://localhost:6006",
+      apiKey: "test-key",
+    };
+    
+    const adapter = createPhoenixAdapter(config);
+    
+    expect(adapter).toBeDefined();
+    expect(adapter.name).toBe("phoenix");
+  });
+
+  test("should throw when startSpan called before initialize", () => {
+    const adapter = new PhoenixAdapter({ projectName: "test" });
+    
+    const context: SpanContext = {
+      name: "test-span",
+      kind: "CHAIN",
+    };
+    
+    // Should throw because OTel API isn't loaded yet
+    expect(() => adapter.startSpan(context)).toThrow("not initialized");
+  });
+
+  test("should accept all span kinds", () => {
+    const adapter = new PhoenixAdapter({ projectName: "test" });
+    
+    // Verify adapter is created for all span kinds
+    const kinds = ["CHAIN", "LLM", "TOOL", "AGENT", "RETRIEVER", "EMBEDDING", "RERANKER"] as const;
+    
+    for (const kind of kinds) {
+      expect(adapter).toBeDefined();
+    }
+  });
+});
+
+describe("PhoenixAdapter config", () => {
+  test("should merge config with defaults", () => {
+    const config: PhoenixConfig = {
+      projectName: "test-project",
+      url: "https://app.phoenix.arize.com",
+      apiKey: "phx-api-key",
+      batch: false,
+    };
+    
+    const adapter = createPhoenixAdapter(config);
+    
+    expect(adapter).toBeDefined();
+    expect(adapter.name).toBe("phoenix");
+  });
+
+  test("should work with minimal config", () => {
+    const config: PhoenixConfig = {
+      projectName: "minimal",
+    };
+    
+    const adapter = createPhoenixAdapter(config);
+    
+    expect(adapter).toBeDefined();
+  });
+
+  test("should handle all optional config fields", () => {
+    const config: PhoenixConfig = {
+      projectName: "full-config",
+      url: "http://localhost:6006",
+      apiKey: "secret-key",
+      batch: true,
+      headers: {
+        "X-Custom-Header": "value",
+      },
+    };
+    
+    const adapter = createPhoenixAdapter(config);
+    
+    expect(adapter).toBeDefined();
+  });
+});
+
+describe("PhoenixAdapter interface", () => {
+  test("should expose required methods", () => {
+    const adapter = new PhoenixAdapter({ projectName: "test" });
+    
+    expect(typeof adapter.initialize).toBe("function");
+    expect(typeof adapter.shutdown).toBe("function");
+    expect(typeof adapter.startSpan).toBe("function");
+    expect(typeof adapter.endSpan).toBe("function");
+    expect(typeof adapter.recordEvent).toBe("function");
+    expect(typeof adapter.setAttributes).toBe("function");
+    expect(typeof adapter.setContext).toBe("function");
+  });
+});

package/tests/factory.test.ts

@@ -0,0 +1,93 @@
+/**
+ * Unit tests for telemetry factory functions
+ */
+
+import { test, expect, describe } from "bun:test";
+import { 
+  createTelemetry, 
+  createPhoenixTelemetry, 
+  createLangfuseTelemetry,
+  createNoopTelemetry 
+} from "../src/factory.js";
+import type { TelemetryOptions, PhoenixConfig, LangfuseConfig } from "../src/types.js";
+
+describe("createTelemetry", () => {
+  test("should return null when disabled", async () => {
+    const options: TelemetryOptions = {
+      provider: "phoenix",
+      config: { projectName: "test" },
+      enabled: false,
+    };
+    
+    const telemetry = await createTelemetry(options);
+    expect(telemetry).toBeNull();
+  });
+
+  test("should throw error for unknown provider", async () => {
+    const options: TelemetryOptions = {
+      provider: "unknown" as any,
+      config: {},
+    };
+    
+    await expect(createTelemetry(options)).rejects.toThrow("Unknown telemetry provider");
+  });
+});
+
+describe("createNoopTelemetry", () => {
+  test("should create noop adapter", () => {
+    const adapter = createNoopTelemetry();
+    
+    expect(adapter).toBeDefined();
+    expect(adapter.name).toBe("noop");
+    expect(adapter.version).toBe("1.0.0");
+  });
+
+  test("should work without initialization", async () => {
+    const adapter = createNoopTelemetry();
+    
+    // Should not require initialize
+    const span = adapter.startSpan({
+      name: "test",
+      kind: "CHAIN",
+    });
+    
+    expect(span).toBeDefined();
+    expect(span.name).toBe("test");
+  });
+});
+
+describe("createPhoenixTelemetry", () => {
+  test("should create Phoenix adapter when dependencies available", async () => {
+    const config: PhoenixConfig = {
+      projectName: "test",
+      url: "http://localhost:6006",
+    };
+    
+    try {
+      const adapter = await createPhoenixTelemetry(config);
+      expect(adapter).toBeDefined();
+      expect(adapter.name).toBe("phoenix");
+    } catch (error) {
+      // Expected if dependencies not installed
+      expect(error).toBeInstanceOf(Error);
+    }
+  });
+});
+
+describe("createLangfuseTelemetry", () => {
+  test("should create Langfuse adapter when dependencies available", async () => {
+    const config: LangfuseConfig = {
+      publicKey: "pk-test",
+      secretKey: "sk-test",
+    };
+    
+    try {
+      const adapter = await createLangfuseTelemetry(config);
+      expect(adapter).toBeDefined();
+      expect(adapter.name).toBe("langfuse");
+    } catch (error) {
+      // Expected if dependencies not installed
+      expect(error).toBeInstanceOf(Error);
+    }
+  });
+});

package/tests/types.test.ts

@@ -0,0 +1,248 @@
+/**
+ * Unit tests for core telemetry types
+ */
+
+import { test, expect, describe } from "bun:test";
+import { 
+  NoopTelemetryAdapter,
+  type SpanContext,
+  type SpanResult,
+  type LLMCallEvent,
+  type ValidationEvent,
+  type ChunkEvent,
+  type ToolCallEvent,
+  type MergeEvent,
+  type ParseEvent,
+} from "../src/types.js";
+
+describe("NoopTelemetryAdapter", () => {
+  test("should create noop adapter", () => {
+    const adapter = new NoopTelemetryAdapter();
+    
+    expect(adapter.name).toBe("noop");
+    expect(adapter.version).toBe("1.0.0");
+  });
+
+  test("should initialize without error", async () => {
+    const adapter = new NoopTelemetryAdapter();
+    await expect(adapter.initialize()).resolves.toBeUndefined();
+  });
+
+  test("should shutdown without error", async () => {
+    const adapter = new NoopTelemetryAdapter();
+    await expect(adapter.shutdown()).resolves.toBeUndefined();
+  });
+
+  test("should create spans", () => {
+    const adapter = new NoopTelemetryAdapter();
+    
+    const context: SpanContext = {
+      name: "test-span",
+      kind: "CHAIN",
+      attributes: { test: true },
+    };
+    
+    const span = adapter.startSpan(context);
+    
+    expect(span.id).toBeDefined();
+    expect(span.name).toBe("test-span");
+    expect(span.kind).toBe("CHAIN");
+    expect(span.traceId).toBeDefined();
+    expect(span.startTime).toBeGreaterThan(0);
+  });
+
+  test("should create child spans", () => {
+    const adapter = new NoopTelemetryAdapter();
+    
+    const parentContext: SpanContext = {
+      name: "parent",
+      kind: "CHAIN",
+    };
+    
+    const parentSpan = adapter.startSpan(parentContext);
+    
+    const childContext: SpanContext = {
+      name: "child",
+      kind: "LLM",
+      parentSpan,
+    };
+    
+    const childSpan = adapter.startSpan(childContext);
+    
+    expect(childSpan.parentId).toBe(parentSpan.id);
+    // Noop adapter creates new traceIds for each span
+    expect(childSpan).toBeDefined();
+    expect(parentSpan).toBeDefined();
+  });
+
+  test("should end spans without error", () => {
+    const adapter = new NoopTelemetryAdapter();
+    
+    const span = adapter.startSpan({
+      name: "test",
+      kind: "CHAIN",
+    });
+    
+    const result: SpanResult = {
+      status: "ok",
+      output: { data: "test" },
+      latencyMs: 100,
+    };
+    
+    expect(() => adapter.endSpan(span, result)).not.toThrow();
+  });
+
+  test("should record events without error", () => {
+    const adapter = new NoopTelemetryAdapter();
+    
+    const span = adapter.startSpan({
+      name: "test",
+      kind: "LLM",
+    });
+    
+    const event: LLMCallEvent = {
+      type: "llm_call",
+      model: "gpt-4o",
+      provider: "openai",
+      input: {
+        messages: [{ role: "user", content: "Hello" }],
+        temperature: 0.5,
+        maxTokens: 100,
+      },
+      output: {
+        content: "Hi there!",
+        usage: { input: 10, output: 5, total: 15 },
+      },
+      latencyMs: 250,
+    };
+    
+    expect(() => adapter.recordEvent(span, event)).not.toThrow();
+  });
+
+  test("should set attributes without error", () => {
+    const adapter = new NoopTelemetryAdapter();
+    
+    const span = adapter.startSpan({
+      name: "test",
+      kind: "CHAIN",
+    });
+    
+    expect(() => 
+      adapter.setAttributes(span, { key: "value", num: 42 })
+    ).not.toThrow();
+  });
+
+  test("should set context without error", () => {
+    const adapter = new NoopTelemetryAdapter();
+    
+    expect(() => 
+      adapter.setContext({
+        sessionId: "session-123",
+        userId: "user-456",
+        metadata: { source: "test" },
+        tags: ["test", "unit"],
+      })
+    ).not.toThrow();
+  });
+
+  test("should handle error results", () => {
+    const adapter = new NoopTelemetryAdapter();
+    
+    const span = adapter.startSpan({
+      name: "test",
+      kind: "LLM",
+    });
+    
+    const result: SpanResult = {
+      status: "error",
+      error: new Error("Test error"),
+    };
+    
+    expect(() => adapter.endSpan(span, result)).not.toThrow();
+  });
+
+  test("should handle all event types", () => {
+    const adapter = new NoopTelemetryAdapter();
+    
+    const span = adapter.startSpan({
+      name: "test",
+      kind: "CHAIN",
+    });
+    
+    // LLM call event
+    const llmEvent: LLMCallEvent = {
+      type: "llm_call",
+      model: "gpt-4o",
+      provider: "openai",
+      input: {
+        messages: [{ role: "user", content: "Hello" }],
+      },
+      output: {
+        content: "Hi",
+        usage: { input: 5, output: 2, total: 7 },
+      },
+      latencyMs: 100,
+    };
+    
+    expect(() => adapter.recordEvent(span, llmEvent)).not.toThrow();
+    
+    // Validation event
+    const validationEvent: ValidationEvent = {
+      type: "validation",
+      attempt: 1,
+      maxAttempts: 3,
+      schema: { type: "object" },
+      input: { data: "test" },
+      success: true,
+      latencyMs: 50,
+    };
+    
+    expect(() => adapter.recordEvent(span, validationEvent)).not.toThrow();
+    
+    // Chunk event
+    const chunkEvent: ChunkEvent = {
+      type: "chunk",
+      chunkIndex: 0,
+      totalChunks: 5,
+      tokens: 1000,
+      images: 2,
+    };
+    
+    expect(() => adapter.recordEvent(span, chunkEvent)).not.toThrow();
+    
+    // Tool call event
+    const toolEvent: ToolCallEvent = {
+      type: "tool_call",
+      toolName: "read",
+      args: { file_path: "/test.txt" },
+      result: "file contents",
+      latencyMs: 25,
+    };
+    
+    expect(() => adapter.recordEvent(span, toolEvent)).not.toThrow();
+    
+    // Merge event
+    const mergeEvent: MergeEvent = {
+      type: "merge",
+      strategy: "parallel",
+      inputCount: 5,
+      outputCount: 4,
+      deduped: 1,
+    };
+    
+    expect(() => adapter.recordEvent(span, mergeEvent)).not.toThrow();
+    
+    // Parse event
+    const parseEvent: ParseEvent = {
+      type: "parse",
+      mimeType: "application/pdf",
+      parser: "pdf-parse",
+      inputSize: 1024,
+      outputTokens: 500,
+      outputImages: 0,
+      latencyMs: 200,
+    };
+    
+    expect(() => adapter.recordEvent(span, parseEvent)).not.toThrow();
+  });
+});