@cloudbase/agent-observability 0.0.16 → 0.0.18

package/dist/server.mjs

@@ -1,10 +1,95 @@
+import {
+  OBSERVABILITY_TRACER_NAME,
+  init_constants
+} from "./chunk-5EXUNUGP.mjs";
 import "./chunk-NFEGQTCC.mjs";
 
+// src/server/SingleLineConsoleSpanExporter.ts
+init_constants();
+var SingleLineConsoleSpanExporter = class {
+  /**
+   * Export spans as single-line JSON.
+   */
+  export(spans, resultCallback) {
+    try {
+      for (const span of spans) {
+        const spanDict = this.spanToDict(span);
+        const jsonLine = JSON.stringify(spanDict);
+        console.log(jsonLine);
+      }
+      resultCallback({ code: 0 /* SUCCESS */ });
+    } catch (error) {
+      resultCallback({ code: 1 /* FAILED */, error });
+    }
+  }
+  /**
+   * Shutdown the exporter.
+   */
+  shutdown() {
+    return Promise.resolve();
+  }
+  /**
+   * Force flush the exporter.
+   */
+  forceFlush() {
+    return Promise.resolve();
+  }
+  /**
+   * Convert a ReadableSpan to a dictionary for JSON serialization.
+   */
+  spanToDict(span) {
+    try {
+      const context = span.spanContext();
+      const parentId = span.parentSpanId || span.parentSpanContext?.spanId;
+      const result = {
+        name: span.name,
+        context: {
+          trace_id: context.traceId,
+          span_id: context.spanId,
+          trace_flags: context.traceFlags
+        },
+        kind: span.kind,
+        parent_id: parentId,
+        start_time: span.startTime,
+        end_time: span.endTime,
+        status: {
+          status_code: span.status.code,
+          description: span.status.message
+        },
+        attributes: span.attributes,
+        events: span.events.map((event) => ({
+          name: event.name,
+          timestamp: event.time,
+          attributes: event.attributes
+        })),
+        links: span.links.map((link) => ({
+          context: {
+            trace_id: link.context.traceId,
+            span_id: link.context.spanId
+          },
+          attributes: link.attributes
+        })),
+        resource: {
+          attributes: span.resource.attributes
+        }
+      };
+      result["_log_from"] = OBSERVABILITY_TRACER_NAME;
+      return result;
+    } catch {
+      return {};
+    }
+  }
+};
+function isSingleLineConsoleExporterEnabled() {
+  const value = process.env.CONSOLE_EXPORTER_SINGLE_LINE?.toLowerCase() || "true";
+  return ["true", "1", "yes", "on"].includes(value);
+}
+
 // src/server/setup.ts
 var TRUTHY_ENV_VALUES = /* @__PURE__ */ new Set(["true", "1", "yes", "on"]);
 var DEFAULT_BATCH_CONFIG = {
   maxExportBatchSize: 100,
-  scheduledDelayMillis: 5e3,
+  scheduledDelayMillis: 1e3,
   maxQueueSize: 2048,
   exportTimeoutMillis: 3e4
 };
@@ -52,33 +137,29 @@ async function setupConsoleExporter(config) {
   const { trace } = await import("@opentelemetry/api");
   const { resourceFromAttributes } = await import("@opentelemetry/resources");
   const { NodeTracerProvider } = await import("@opentelemetry/sdk-trace-node");
-  const { ConsoleSpanExporter, BatchSpanProcessor } = await import("@opentelemetry/sdk-trace-base");
-  const batchConfig = resolveBatchConfig(config.batch);
+  const { ConsoleSpanExporter, SimpleSpanProcessor } = await import("@opentelemetry/sdk-trace-base");
+  const useSingleLine = isSingleLineConsoleExporterEnabled();
+  const exporter = useSingleLine ? new SingleLineConsoleSpanExporter() : new ConsoleSpanExporter();
+  const exporterType = useSingleLine ? "single-line" : "multi-line";
   let provider = trace.getTracerProvider();
   const isRealProvider = "addSpanProcessor" in provider;
+  const processor = new SimpleSpanProcessor(exporter);
   if (isRealProvider) {
-    const exporter = new ConsoleSpanExporter();
-    const processor = new BatchSpanProcessor(exporter, batchConfig);
     provider.addSpanProcessor(processor);
-    console.info(
-      `[Observability] Console exporter configured (batch=${batchConfig.maxExportBatchSize}, delay=${batchConfig.scheduledDelayMillis}ms)`
-    );
   } else {
     const resource = resourceFromAttributes({
       "service.name": process.env.OTEL_SERVICE_NAME || "ag-ui-server",
       "service.version": "1.0.0"
     });
-    const exporter = new ConsoleSpanExporter();
-    const processor = new BatchSpanProcessor(exporter, batchConfig);
     const tracerProvider = new NodeTracerProvider({
       resource,
       spanProcessors: [processor]
     });
     tracerProvider.register();
-    console.info(
-      `[Observability] Console exporter configured (batch=${batchConfig.maxExportBatchSize}, delay=${batchConfig.scheduledDelayMillis}ms)`
-    );
   }
+  console.info(
+    `[Observability] Console exporter configured (${exporterType}, simple processor)`
+  );
 }
 async function setupOTLPExporter(config) {
   const { trace } = await import("@opentelemetry/api");
@@ -172,6 +253,8 @@ var ExporterType = {
 };
 export {
   ExporterType,
+  SingleLineConsoleSpanExporter,
+  isSingleLineConsoleExporterEnabled,
   setupObservability
 };
 //# sourceMappingURL=server.mjs.map

package/dist/server.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/server/setup.ts","../src/server/config.ts"],"sourcesContent":["/**\n * Observability setup implementation for AG-Kit Server.\n *\n * Merges configuration from environment variables and parameters,\n * then applies each exporter configuration.\n *\n * @packageDocumentation\n */\n\nimport type {\n  BatchConfig,\n  ObservabilityConfig,\n  ConsoleTraceConfig,\n  OTLPTraceConfig,\n  CustomTraceConfig,\n} from './config';\n\nexport type {\n  BatchConfig,\n  ObservabilityConfig,\n  ConsoleTraceConfig,\n  OTLPTraceConfig,\n  CustomTraceConfig,\n} from './config';\n\n/**\n * Environment variable truthy values.\n * Matches Python SDK implementation for consistency.\n */\nconst TRUTHY_ENV_VALUES = new Set(['true', '1', 'yes', 'on']);\n\n/**\n * Merged configuration result.\n * Console config allows merge (param overrides env),\n * while OTLP and custom configs are arrays (additive).\n */\ninterface MergedConfig {\n  console?: ConsoleTraceConfig | null;\n  otlp: OTLPTraceConfig[];\n  custom: CustomTraceConfig[];\n}\n\n/**\n * Default batch configuration.\n */\nconst DEFAULT_BATCH_CONFIG: Required<BatchConfig> = {\n  maxExportBatchSize: 100,\n  scheduledDelayMillis: 5000,\n  maxQueueSize: 2048,\n  exportTimeoutMillis: 30000,\n};\n\n/**\n * Merge environment variable and parameter configurations.\n *\n * - AUTO_TRACES_STDOUT env adds a console config\n * - Parameter configs override/extend env configs\n */\nfunction mergeConfigs(paramConfigs: ObservabilityConfig[]): MergedConfig {\n  const result: MergedConfig = {\n    console: null,\n    otlp: [],\n    custom: [],\n  };\n\n  // 1. Check AUTO_TRACES_STDOUT env\n  const autoTracesStdout = process.env.AUTO_TRACES_STDOUT?.toLowerCase() || '';\n  if (TRUTHY_ENV_VALUES.has(autoTracesStdout)) {\n    result.console = { type: 'console' };\n    console.debug(\n      `[Observability] AUTO_TRACES_STDOUT=${autoTracesStdout}, console exporter enabled`\n    );\n  }\n\n  // 2. Process parameter configs\n  for (const config of paramConfigs) {\n    switch (config.type) {\n      case 'console':\n        // Parameter overrides env (merge batch config)\n        result.console = { ...result.console, ...config };\n        break;\n\n      case 'otlp':\n        result.otlp.push(config);\n        break;\n\n      case 'custom':\n        result.custom.push(config);\n        break;\n    }\n  }\n\n  return result;\n}\n\n/**\n * Apply batch configuration with defaults.\n */\nfunction resolveBatchConfig(batch?: BatchConfig): Required<BatchConfig> {\n  return { ...DEFAULT_BATCH_CONFIG, ...batch };\n}\n\n/**\n * Safe wrapper for exporter setup functions.\n * Ensures individual exporter failures don't crash the entire setup.\n */\nasync function safeSetup(\n  name: string,\n  setupFn: () => Promise<void>\n): Promise<void> {\n  try {\n    await setupFn();\n  } catch (error) {\n    console.warn(\n      `[Observability] ${name} setup failed (non-fatal): ${\n        error instanceof Error ? error.message : String(error)\n      }`\n    );\n    // Don't rethrow - allow other exporters to continue\n  }\n}\n\n/**\n * Setup console exporter.\n */\nasync function setupConsoleExporter(config: ConsoleTraceConfig): Promise<void> {\n  const { trace } = await import('@opentelemetry/api');\n  const { resourceFromAttributes } = await import('@opentelemetry/resources');\n  const { NodeTracerProvider } = await import('@opentelemetry/sdk-trace-node');\n  const { ConsoleSpanExporter, BatchSpanProcessor } = await import(\n    '@opentelemetry/sdk-trace-base'\n  );\n\n  const batchConfig = resolveBatchConfig(config.batch);\n\n  // Check if a real TracerProvider already exists\n  let provider = trace.getTracerProvider();\n  const isRealProvider = 'addSpanProcessor' in provider;\n\n  if (isRealProvider) {\n    // Add processor to existing provider\n    const exporter = new ConsoleSpanExporter();\n    const processor = new BatchSpanProcessor(exporter, batchConfig);\n    (provider as any).addSpanProcessor(processor);\n\n    console.info(\n      `[Observability] Console exporter configured (batch=${batchConfig.maxExportBatchSize}, ` +\n        `delay=${batchConfig.scheduledDelayMillis}ms)`\n    );\n  } else {\n    // Create new provider with console exporter\n    const resource = resourceFromAttributes({\n      'service.name': process.env.OTEL_SERVICE_NAME || 'ag-ui-server',\n      'service.version': '1.0.0',\n    });\n\n    const exporter = new ConsoleSpanExporter();\n    const processor = new BatchSpanProcessor(exporter, batchConfig);\n\n    const tracerProvider = new NodeTracerProvider({\n      resource,\n      spanProcessors: [processor],\n    });\n\n    tracerProvider.register();\n\n    console.info(\n      `[Observability] Console exporter configured (batch=${batchConfig.maxExportBatchSize}, ` +\n        `delay=${batchConfig.scheduledDelayMillis}ms)`\n    );\n  }\n}\n\n/**\n * Setup OTLP exporter.\n */\nasync function setupOTLPExporter(config: OTLPTraceConfig): Promise<void> {\n  const { trace } = await import('@opentelemetry/api');\n  const { resourceFromAttributes } = await import('@opentelemetry/resources');\n  const { NodeTracerProvider } = await import('@opentelemetry/sdk-trace-node');\n  const { OTLPTraceExporter } = await import('@opentelemetry/exporter-trace-otlp-http');\n  const { BatchSpanProcessor } = await import('@opentelemetry/sdk-trace-base');\n\n  const batchConfig = resolveBatchConfig(config.batch);\n\n  // Check if a real TracerProvider already exists\n  let provider = trace.getTracerProvider();\n  const isRealProvider = 'addSpanProcessor' in provider;\n\n  if (isRealProvider) {\n    // Add processor to existing provider\n    const exporter = new OTLPTraceExporter({\n      url: config.url,\n      headers: config.headers,\n      timeoutMillis: config.timeout ?? 10000,\n    });\n\n    const processor = new BatchSpanProcessor(exporter, batchConfig);\n    (provider as any).addSpanProcessor(processor);\n\n    console.info(\n      `[Observability] OTLP exporter configured (url=${config.url}, ` +\n        `batch=${batchConfig.maxExportBatchSize}, delay=${batchConfig.scheduledDelayMillis}ms)`\n    );\n  } else {\n    // Create new provider with OTLP exporter\n    const resource = resourceFromAttributes({\n      'service.name': process.env.OTEL_SERVICE_NAME || 'ag-ui-server',\n      'service.version': '1.0.0',\n    });\n\n    const exporter = new OTLPTraceExporter({\n      url: config.url,\n      headers: config.headers,\n      timeoutMillis: config.timeout ?? 10000,\n    });\n\n    const processor = new BatchSpanProcessor(exporter, batchConfig);\n\n    const tracerProvider = new NodeTracerProvider({\n      resource,\n      spanProcessors: [processor],\n    });\n\n    tracerProvider.register();\n\n    console.info(\n      `[Observability] OTLP exporter configured (url=${config.url}, ` +\n        `batch=${batchConfig.maxExportBatchSize}, delay=${batchConfig.scheduledDelayMillis}ms)`\n    );\n  }\n}\n\n/**\n * Setup custom exporter.\n */\nasync function setupCustomExporter(config: CustomTraceConfig): Promise<void> {\n  await config.setup();\n  console.info(`[Observability] Custom exporter setup completed`);\n}\n\n/**\n * Setup observability from merged configuration.\n *\n * @internal\n */\nasync function applyMergedConfigs(merged: MergedConfig): Promise<void> {\n  const setupTasks: Promise<void>[] = [];\n\n  // Apply console (non-blocking)\n  if (merged.console) {\n    setupTasks.push(safeSetup('Console exporter', () => setupConsoleExporter(merged.console!)));\n  }\n\n  // Apply otlp (non-blocking)\n  for (const otlp of merged.otlp) {\n    setupTasks.push(safeSetup(`OTLP exporter (${otlp.url})`, () => setupOTLPExporter(otlp)));\n  }\n\n  // Apply custom (non-blocking)\n  for (const custom of merged.custom) {\n    setupTasks.push(safeSetup('Custom exporter', () => setupCustomExporter(custom)));\n  }\n\n  // Wait for all exporters to complete (or fail gracefully)\n  await Promise.all(setupTasks);\n\n  if (merged.console || merged.otlp.length > 0 || merged.custom.length > 0) {\n    console.info(`[Observability] Setup completed`);\n  }\n}\n\n/**\n * Setup observability from configuration.\n *\n * Merges environment variable (AUTO_TRACES_STDOUT) with parameter configs,\n * then applies each exporter configuration.\n *\n * Environment variables act as presets, parameter configs override or extend.\n *\n * Returns a promise that resolves when setup is complete. This allows callers\n * to await initialization before proceeding, eliminating race conditions.\n *\n * The returned promise is cached - subsequent calls return the same promise\n * to avoid duplicate initialization.\n *\n * @param configs - Observability configuration(s)\n *\n * @example\n * ```typescript\n * // Console only (from env)\n * await setupObservability();\n *\n * // Console + OTLP\n * await setupObservability([\n *   { type: 'console' },\n *   { type: 'otlp', url: 'http://localhost:4318/v1/traces' }\n * ]);\n *\n * // OTLP only\n * await setupObservability({\n *   type: 'otlp',\n *   url: 'https://cloud.langfuse.com/api/public/otlp/v1/traces',\n *   headers: { 'Authorization': 'Basic xxx' }\n * });\n * ```\n *\n * @public\n */\n\nlet setupPromise: Promise<void> | null = null;\n\nexport async function setupObservability(\n  configs?: ObservabilityConfig | ObservabilityConfig[]\n): Promise<void> {\n  // Return cached promise if setup is in progress or completed\n  if (setupPromise) {\n    return setupPromise;\n  }\n\n  // Create the setup promise\n  setupPromise = (async () => {\n    try {\n      // Normalize to array\n      const configsArray = configs\n        ? Array.isArray(configs)\n          ? configs\n          : [configs]\n        : [];\n\n      // Merge env and parameter configs\n      const merged = mergeConfigs(configsArray);\n\n      // Apply merged configs\n      await applyMergedConfigs(merged);\n    } catch (error) {\n      // Reset promise on error to allow retry\n      setupPromise = null;\n      // Silent failure - observability should never block main flow\n      console.warn(\n        `[Observability] Setup failed: ${\n          error instanceof Error ? error.message : String(error)\n        }`\n      );\n    }\n  })();\n\n  return setupPromise;\n}\n","/**\n * Observability configuration types for AG-Kit Server.\n *\n * Provides a unified configuration interface for trace exporters:\n * - Console: Development/debugging output\n * - OTLP: Production export to Langfuse, Jaeger, etc.\n * - Custom: User-defined setup logic\n *\n * @packageDocumentation\n */\n\n/**\n * Trace exporter type constants.\n *\n * @example\n * ```typescript\n * import { ExporterType } from '@cloudbase/agent-observability/server';\n *\n * { type: ExporterType.Console }\n * { type: ExporterType.OTLP }\n * { type: ExporterType.Custom }\n * ```\n *\n * @public\n */\nexport const ExporterType = {\n  /** Console exporter - outputs traces to stdout */\n  Console: 'console',\n  /** OTLP exporter - sends traces to OTLP-compatible backend */\n  OTLP: 'otlp',\n  /** Custom exporter - user-defined setup logic */\n  Custom: 'custom',\n} as const;\n\n/**\n * Trace exporter type literal values.\n *\n * @public\n */\nexport type ExporterType = typeof ExporterType[keyof typeof ExporterType];\n\n/**\n * Batch processing configuration for span exporters.\n *\n * Used by BatchSpanProcessor to optimize performance:\n * - Collects spans in memory and exports them in batches\n * - Reduces I/O operations (console) or network requests (OTLP)\n * - Recommended for production environments\n *\n * @public\n */\nexport interface BatchConfig {\n  /** Maximum number of spans per export batch (default: 100) */\n  maxExportBatchSize?: number;\n  /** Maximum delay in milliseconds before exporting (default: 5000) */\n  scheduledDelayMillis?: number;\n  /** Maximum queue size (default: 2048) */\n  maxQueueSize?: number;\n  /** Export timeout in milliseconds (default: 30000) */\n  exportTimeoutMillis?: number;\n}\n\n/**\n * Console trace exporter configuration.\n *\n * Outputs traces to stdout in JSON format using ConsoleSpanExporter.\n * Useful for development and debugging.\n *\n * @example\n * ```typescript\n * import { ExporterType } from '@cloudbase/agent-observability/server';\n *\n * { type: ExporterType.Console }\n * { type: ExporterType.Console, batch: { maxExportBatchSize: 200 } }\n * ```\n *\n * @public\n */\nexport interface ConsoleTraceConfig {\n  /** Discriminator for console exporter */\n  type: typeof ExporterType.Console;\n  /** Optional batch processing configuration */\n  batch?: BatchConfig;\n}\n\n/**\n * OTLP trace exporter configuration.\n *\n * Exports traces via OTLP protocol to any compatible backend:\n * - Langfuse: https://cloud.langfuse.com/api/public/otlp/v1/traces\n * - Jaeger: http://localhost:4318/v1/traces\n * - OTel Collector: custom endpoint\n *\n * @example\n * ```typescript\n * import { ExporterType } from '@cloudbase/agent-observability/server';\n *\n * {\n *   type: ExporterType.OTLP,\n *   url: 'https://cloud.langfuse.com/api/public/otlp/v1/traces',\n *   headers: {\n *     'Authorization': 'Basic ' + btoa('pk-lf-xxx:sk-lf-xxx')\n *   }\n * }\n * ```\n *\n * @public\n */\nexport interface OTLPTraceConfig {\n  /** Discriminator for OTLP exporter */\n  type: typeof ExporterType.OTLP;\n  /** OTLP endpoint URL (http/https) */\n  url: string;\n  /** Optional HTTP headers for authentication */\n  headers?: Record<string, string>;\n  /** Request timeout in milliseconds (default: 10000) */\n  timeout?: number;\n  /** Optional batch processing configuration */\n  batch?: BatchConfig;\n}\n\n/**\n * Custom trace exporter configuration.\n *\n * Allows users to provide custom trace setup logic.\n * Useful for integrations not covered by console/otlp.\n *\n * @example\n * ```typescript\n * import { ExporterType } from '@cloudbase/agent-observability/server';\n *\n * {\n *   type: ExporterType.Custom,\n *   setup: async () => {\n *     const exporter = new MyCustomExporter();\n *     const provider = new BasicTracerProvider();\n *     provider.addSpanProcessor(new SimpleSpanProcessor(exporter));\n *     provider.register();\n *   }\n * }\n * ```\n *\n * @public\n */\nexport interface CustomTraceConfig {\n  /** Discriminator for custom setup */\n  type: typeof ExporterType.Custom;\n  /** User-defined setup function */\n  setup: () => Promise<void> | void;\n}\n\n/**\n * Union type of all supported trace exporter configurations.\n *\n * @public\n */\nexport type ObservabilityConfig =\n  | ConsoleTraceConfig\n  | OTLPTraceConfig\n  | CustomTraceConfig;\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/server/SingleLineConsoleSpanExporter.ts","../src/server/setup.ts","../src/server/config.ts"],"sourcesContent":["/**\n * Custom console exporter that outputs single-line JSON.\n *\n * This exporter outputs spans as single-line JSON for easier parsing\n * with line-based tools (grep, jq, etc.).\n *\n * To switch back to standard multi-line output, use ConsoleSpanExporter instead.\n *\n * @example\n * ```typescript\n * // Single-line (current default)\n * const exporter = new SingleLineConsoleSpanExporter();\n *\n * // Multi-line (standard OTel)\n * import { ConsoleSpanExporter } from '@opentelemetry/sdk-trace-base';\n * const exporter = new ConsoleSpanExporter();\n * ```\n *\n * @packageDocumentation\n */\n\nimport type { SpanExporter, ReadableSpan } from '@opentelemetry/sdk-trace-base';\nimport { OBSERVABILITY_TRACER_NAME } from '../core/constants';\n\n/**\n * Export result codes.\n */\nexport enum ExportResultCode {\n  SUCCESS = 0,\n  FAILED = 1,\n}\n\n/**\n * Export result interface.\n */\nexport interface ExportResult {\n  code: ExportResultCode;\n  error?: Error;\n}\n\n/**\n * Custom console exporter that outputs single-line JSON.\n *\n * This exporter outputs spans as single-line JSON for easier parsing\n * with line-based tools (grep, jq, etc.).\n */\nexport class SingleLineConsoleSpanExporter implements SpanExporter {\n  /**\n   * Export spans as single-line JSON.\n   */\n  export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void {\n    try {\n      for (const span of spans) {\n        const spanDict = this.spanToDict(span);\n        // Single-line JSON output\n        const jsonLine = JSON.stringify(spanDict);\n        console.log(jsonLine);\n      }\n      resultCallback({ code: ExportResultCode.SUCCESS });\n    } catch (error) {\n      resultCallback({ code: ExportResultCode.FAILED, error: error as Error });\n    }\n  }\n\n  /**\n   * Shutdown the exporter.\n   */\n  shutdown(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Force flush the exporter.\n   */\n  forceFlush?(): Promise<void> {\n    return Promise.resolve();\n  }\n\n  /**\n   * Convert a ReadableSpan to a dictionary for JSON serialization.\n   */\n  private spanToDict(span: ReadableSpan): Record<string, unknown> {\n    try {\n      const context = span.spanContext();\n\n      // Get parent span ID from parentSpanContext if available\n      // Some versions use parentSpanId directly, others use parentSpanContext.spanId\n      const parentId = (span as any).parentSpanId || span.parentSpanContext?.spanId;\n\n      const result: Record<string, unknown> = {\n        name: span.name,\n        context: {\n          trace_id: context.traceId,\n          span_id: context.spanId,\n          trace_flags: context.traceFlags,\n        },\n        kind: span.kind,\n        parent_id: parentId,\n        start_time: span.startTime,\n        end_time: span.endTime,\n        status: {\n          status_code: span.status.code,\n          description: span.status.message,\n        },\n        attributes: span.attributes,\n        events: span.events.map((event) => ({\n          name: event.name,\n          timestamp: event.time,\n          attributes: event.attributes,\n        })),\n        links: span.links.map((link) => ({\n          context: {\n            trace_id: link.context.traceId,\n            span_id: link.context.spanId,\n          },\n          attributes: link.attributes,\n        })),\n        resource: {\n          attributes: span.resource.attributes,\n        },\n      };\n\n      // Add log source identifier for console output\n      result['_log_from'] = OBSERVABILITY_TRACER_NAME;\n\n      return result;\n    } catch {\n      return {};\n    }\n  }\n}\n\n/**\n * Check if single-line console exporter should be used.\n *\n * Set CONSOLE_EXPORTER_SINGLE_LINE=false to use standard multi-line output.\n */\nexport function isSingleLineConsoleExporterEnabled(): boolean {\n  const value = process.env.CONSOLE_EXPORTER_SINGLE_LINE?.toLowerCase() || 'true';\n  return ['true', '1', 'yes', 'on'].includes(value);\n}\n","/**\n * Observability setup implementation for the server.\n *\n * Merges configuration from environment variables and parameters,\n * then applies each exporter configuration.\n *\n * @packageDocumentation\n */\n\nimport type {\n  BatchConfig,\n  ObservabilityConfig,\n  ConsoleTraceConfig,\n  OTLPTraceConfig,\n  CustomTraceConfig,\n} from './config';\nimport {\n  SingleLineConsoleSpanExporter,\n  isSingleLineConsoleExporterEnabled,\n} from './SingleLineConsoleSpanExporter';\n\nexport type {\n  BatchConfig,\n  ObservabilityConfig,\n  ConsoleTraceConfig,\n  OTLPTraceConfig,\n  CustomTraceConfig,\n} from './config';\nexport { SingleLineConsoleSpanExporter } from './SingleLineConsoleSpanExporter';\n\n/**\n * Environment variable truthy values.\n * Matches Python SDK implementation for consistency.\n */\nconst TRUTHY_ENV_VALUES = new Set(['true', '1', 'yes', 'on']);\n\n/**\n * Merged configuration result.\n * Console config allows merge (param overrides env),\n * while OTLP and custom configs are arrays (additive).\n */\ninterface MergedConfig {\n  console?: ConsoleTraceConfig | null;\n  otlp: OTLPTraceConfig[];\n  custom: CustomTraceConfig[];\n}\n\n/**\n * Default batch configuration (used by OTLP exporter).\n */\nconst DEFAULT_BATCH_CONFIG: Required<BatchConfig> = {\n  maxExportBatchSize: 100,\n  scheduledDelayMillis: 1000,\n  maxQueueSize: 2048,\n  exportTimeoutMillis: 30000,\n};\n\n/**\n * Merge environment variable and parameter configurations.\n *\n * - AUTO_TRACES_STDOUT env adds a console config\n * - Parameter configs override/extend env configs\n */\nfunction mergeConfigs(paramConfigs: ObservabilityConfig[]): MergedConfig {\n  const result: MergedConfig = {\n    console: null,\n    otlp: [],\n    custom: [],\n  };\n\n  // 1. Check AUTO_TRACES_STDOUT env\n  const autoTracesStdout = process.env.AUTO_TRACES_STDOUT?.toLowerCase() || '';\n  if (TRUTHY_ENV_VALUES.has(autoTracesStdout)) {\n    result.console = { type: 'console' };\n    console.debug(\n      `[Observability] AUTO_TRACES_STDOUT=${autoTracesStdout}, console exporter enabled`\n    );\n  }\n\n  // 2. Process parameter configs\n  for (const config of paramConfigs) {\n    switch (config.type) {\n      case 'console':\n        // Parameter overrides env (merge batch config)\n        result.console = { ...result.console, ...config };\n        break;\n\n      case 'otlp':\n        result.otlp.push(config);\n        break;\n\n      case 'custom':\n        result.custom.push(config);\n        break;\n    }\n  }\n\n  return result;\n}\n\n/**\n * Apply batch configuration with defaults.\n */\nfunction resolveBatchConfig(batch?: BatchConfig): Required<BatchConfig> {\n  return { ...DEFAULT_BATCH_CONFIG, ...batch };\n}\n\n/**\n * Safe wrapper for exporter setup functions.\n * Ensures individual exporter failures don't crash the entire setup.\n */\nasync function safeSetup(\n  name: string,\n  setupFn: () => Promise<void>\n): Promise<void> {\n  try {\n    await setupFn();\n  } catch (error) {\n    console.warn(\n      `[Observability] ${name} setup failed (non-fatal): ${\n        error instanceof Error ? error.message : String(error)\n      }`\n    );\n    // Don't rethrow - allow other exporters to continue\n  }\n}\n\n/**\n * Setup console exporter.\n *\n * Uses SimpleSpanProcessor for immediate export without batching.\n * This is optimal for console output (stdout.write is microsecond-level)\n * and ensures reliable data export in serverless environments (e.g., SCF)\n * where batch background threads may be frozen.\n *\n * Set CONSOLE_EXPORTER_SINGLE_LINE=false to use standard multi-line output.\n */\nasync function setupConsoleExporter(config: ConsoleTraceConfig): Promise<void> {\n  const { trace } = await import('@opentelemetry/api');\n  const { resourceFromAttributes } = await import('@opentelemetry/resources');\n  const { NodeTracerProvider } = await import('@opentelemetry/sdk-trace-node');\n  const { ConsoleSpanExporter, SimpleSpanProcessor } = await import(\n    '@opentelemetry/sdk-trace-base'\n  );\n\n  // Choose exporter type based on CONSOLE_EXPORTER_SINGLE_LINE env var\n  // Single-line: easier for parsing with line-based tools (grep, jq, etc.)\n  // Multi-line: more human-readable for debugging\n  const useSingleLine = isSingleLineConsoleExporterEnabled();\n  const exporter = useSingleLine\n    ? new SingleLineConsoleSpanExporter()\n    : new ConsoleSpanExporter();\n  const exporterType = useSingleLine ? 'single-line' : 'multi-line';\n\n  // Check if a real TracerProvider already exists\n  let provider = trace.getTracerProvider();\n  const isRealProvider = 'addSpanProcessor' in provider;\n\n  const processor = new SimpleSpanProcessor(exporter);\n\n  if (isRealProvider) {\n    // Add processor to existing provider\n    (provider as any).addSpanProcessor(processor);\n  } else {\n    // Create new provider with console exporter\n    const resource = resourceFromAttributes({\n      'service.name': process.env.OTEL_SERVICE_NAME || 'ag-ui-server',\n      'service.version': '1.0.0',\n    });\n\n    const tracerProvider = new NodeTracerProvider({\n      resource,\n      spanProcessors: [processor],\n    });\n\n    tracerProvider.register();\n  }\n\n  console.info(\n    `[Observability] Console exporter configured (${exporterType}, simple processor)`\n  );\n}\n\n/**\n * Setup OTLP exporter.\n */\nasync function setupOTLPExporter(config: OTLPTraceConfig): Promise<void> {\n  const { trace } = await import('@opentelemetry/api');\n  const { resourceFromAttributes } = await import('@opentelemetry/resources');\n  const { NodeTracerProvider } = await import('@opentelemetry/sdk-trace-node');\n  const { OTLPTraceExporter } = await import('@opentelemetry/exporter-trace-otlp-http');\n  const { BatchSpanProcessor } = await import('@opentelemetry/sdk-trace-base');\n\n  const batchConfig = resolveBatchConfig(config.batch);\n\n  // Check if a real TracerProvider already exists\n  let provider = trace.getTracerProvider();\n  const isRealProvider = 'addSpanProcessor' in provider;\n\n  if (isRealProvider) {\n    // Add processor to existing provider\n    const exporter = new OTLPTraceExporter({\n      url: config.url,\n      headers: config.headers,\n      timeoutMillis: config.timeout ?? 10000,\n    });\n\n    const processor = new BatchSpanProcessor(exporter, batchConfig);\n    (provider as any).addSpanProcessor(processor);\n\n    console.info(\n      `[Observability] OTLP exporter configured (url=${config.url}, ` +\n        `batch=${batchConfig.maxExportBatchSize}, delay=${batchConfig.scheduledDelayMillis}ms)`\n    );\n  } else {\n    // Create new provider with OTLP exporter\n    const resource = resourceFromAttributes({\n      'service.name': process.env.OTEL_SERVICE_NAME || 'ag-ui-server',\n      'service.version': '1.0.0',\n    });\n\n    const exporter = new OTLPTraceExporter({\n      url: config.url,\n      headers: config.headers,\n      timeoutMillis: config.timeout ?? 10000,\n    });\n\n    const processor = new BatchSpanProcessor(exporter, batchConfig);\n\n    const tracerProvider = new NodeTracerProvider({\n      resource,\n      spanProcessors: [processor],\n    });\n\n    tracerProvider.register();\n\n    console.info(\n      `[Observability] OTLP exporter configured (url=${config.url}, ` +\n        `batch=${batchConfig.maxExportBatchSize}, delay=${batchConfig.scheduledDelayMillis}ms)`\n    );\n  }\n}\n\n/**\n * Setup custom exporter.\n */\nasync function setupCustomExporter(config: CustomTraceConfig): Promise<void> {\n  await config.setup();\n  console.info(`[Observability] Custom exporter setup completed`);\n}\n\n/**\n * Setup observability from merged configuration.\n *\n * @internal\n */\nasync function applyMergedConfigs(merged: MergedConfig): Promise<void> {\n  const setupTasks: Promise<void>[] = [];\n\n  // Apply console (non-blocking)\n  if (merged.console) {\n    setupTasks.push(safeSetup('Console exporter', () => setupConsoleExporter(merged.console!)));\n  }\n\n  // Apply otlp (non-blocking)\n  for (const otlp of merged.otlp) {\n    setupTasks.push(safeSetup(`OTLP exporter (${otlp.url})`, () => setupOTLPExporter(otlp)));\n  }\n\n  // Apply custom (non-blocking)\n  for (const custom of merged.custom) {\n    setupTasks.push(safeSetup('Custom exporter', () => setupCustomExporter(custom)));\n  }\n\n  // Wait for all exporters to complete (or fail gracefully)\n  await Promise.all(setupTasks);\n\n  if (merged.console || merged.otlp.length > 0 || merged.custom.length > 0) {\n    console.info(`[Observability] Setup completed`);\n  }\n}\n\n/**\n * Setup observability from configuration.\n *\n * Merges environment variable (AUTO_TRACES_STDOUT) with parameter configs,\n * then applies each exporter configuration.\n *\n * Environment variables act as presets, parameter configs override or extend.\n *\n * Returns a promise that resolves when setup is complete. This allows callers\n * to await initialization before proceeding, eliminating race conditions.\n *\n * The returned promise is cached - subsequent calls return the same promise\n * to avoid duplicate initialization.\n *\n * @param configs - Observability configuration(s)\n *\n * @example\n * ```typescript\n * // Console only (from env)\n * await setupObservability();\n *\n * // Console + OTLP\n * await setupObservability([\n *   { type: 'console' },\n *   { type: 'otlp', url: 'http://localhost:4318/v1/traces' }\n * ]);\n *\n * // OTLP only\n * await setupObservability({\n *   type: 'otlp',\n *   url: 'https://cloud.langfuse.com/api/public/otlp/v1/traces',\n *   headers: { 'Authorization': 'Basic xxx' }\n * });\n * ```\n *\n * @public\n */\n\nlet setupPromise: Promise<void> | null = null;\n\nexport async function setupObservability(\n  configs?: ObservabilityConfig | ObservabilityConfig[]\n): Promise<void> {\n  // Return cached promise if setup is in progress or completed\n  if (setupPromise) {\n    return setupPromise;\n  }\n\n  // Create the setup promise\n  setupPromise = (async () => {\n    try {\n      // Normalize to array\n      const configsArray = configs\n        ? Array.isArray(configs)\n          ? configs\n          : [configs]\n        : [];\n\n      // Merge env and parameter configs\n      const merged = mergeConfigs(configsArray);\n\n      // Apply merged configs\n      await applyMergedConfigs(merged);\n    } catch (error) {\n      // Reset promise on error to allow retry\n      setupPromise = null;\n      // Silent failure - observability should never block main flow\n      console.warn(\n        `[Observability] Setup failed: ${\n          error instanceof Error ? error.message : String(error)\n        }`\n      );\n    }\n  })();\n\n  return setupPromise;\n}\n","/**\n * Observability configuration types for the server.\n *\n * Provides a unified configuration interface for trace exporters:\n * - Console: Development/debugging output\n * - OTLP: Production export to Langfuse, Jaeger, etc.\n * - Custom: User-defined setup logic\n *\n * @packageDocumentation\n */\n\n/**\n * Trace exporter type constants.\n *\n * @example\n * ```typescript\n * import { ExporterType } from '@cloudbase/agent-observability/server';\n *\n * { type: ExporterType.Console }\n * { type: ExporterType.OTLP }\n * { type: ExporterType.Custom }\n * ```\n *\n * @public\n */\nexport const ExporterType = {\n  /** Console exporter - outputs traces to stdout */\n  Console: 'console',\n  /** OTLP exporter - sends traces to OTLP-compatible backend */\n  OTLP: 'otlp',\n  /** Custom exporter - user-defined setup logic */\n  Custom: 'custom',\n} as const;\n\n/**\n * Trace exporter type literal values.\n *\n * @public\n */\nexport type ExporterType = typeof ExporterType[keyof typeof ExporterType];\n\n/**\n * Batch processing configuration for span exporters.\n *\n * Used by BatchSpanProcessor to optimize performance:\n * - Collects spans in memory and exports them in batches\n * - Reduces I/O operations (console) or network requests (OTLP)\n * - Recommended for production environments\n *\n * @public\n */\nexport interface BatchConfig {\n  /** Maximum number of spans per export batch (default: 100) */\n  maxExportBatchSize?: number;\n  /** Maximum delay in milliseconds before exporting (default: 5000) */\n  scheduledDelayMillis?: number;\n  /** Maximum queue size (default: 2048) */\n  maxQueueSize?: number;\n  /** Export timeout in milliseconds (default: 30000) */\n  exportTimeoutMillis?: number;\n}\n\n/**\n * Console trace exporter configuration.\n *\n * Outputs traces to stdout in JSON format using ConsoleSpanExporter.\n * Uses SimpleSpanProcessor for immediate export (no batching).\n * Useful for development and debugging.\n *\n * @example\n * ```typescript\n * import { ExporterType } from '@cloudbase/agent-observability/server';\n *\n * { type: ExporterType.Console }\n * ```\n *\n * @public\n */\nexport interface ConsoleTraceConfig {\n  /** Discriminator for console exporter */\n  type: typeof ExporterType.Console;\n}\n\n/**\n * OTLP trace exporter configuration.\n *\n * Exports traces via OTLP protocol to any compatible backend:\n * - Langfuse: https://cloud.langfuse.com/api/public/otlp/v1/traces\n * - Jaeger: http://localhost:4318/v1/traces\n * - OTel Collector: custom endpoint\n *\n * @example\n * ```typescript\n * import { ExporterType } from '@cloudbase/agent-observability/server';\n *\n * {\n *   type: ExporterType.OTLP,\n *   url: 'https://cloud.langfuse.com/api/public/otlp/v1/traces',\n *   headers: {\n *     'Authorization': 'Basic ' + btoa('pk-lf-xxx:sk-lf-xxx')\n *   }\n * }\n * ```\n *\n * @public\n */\nexport interface OTLPTraceConfig {\n  /** Discriminator for OTLP exporter */\n  type: typeof ExporterType.OTLP;\n  /** OTLP endpoint URL (http/https) */\n  url: string;\n  /** Optional HTTP headers for authentication */\n  headers?: Record<string, string>;\n  /** Request timeout in milliseconds (default: 10000) */\n  timeout?: number;\n  /** Optional batch processing configuration */\n  batch?: BatchConfig;\n}\n\n/**\n * Custom trace exporter configuration.\n *\n * Allows users to provide custom trace setup logic.\n * Useful for integrations not covered by console/otlp.\n *\n * @example\n * ```typescript\n * import { ExporterType } from '@cloudbase/agent-observability/server';\n *\n * {\n *   type: ExporterType.Custom,\n *   setup: async () => {\n *     const exporter = new MyCustomExporter();\n *     const provider = new BasicTracerProvider();\n *     provider.addSpanProcessor(new SimpleSpanProcessor(exporter));\n *     provider.register();\n *   }\n * }\n * ```\n *\n * @public\n */\nexport interface CustomTraceConfig {\n  /** Discriminator for custom setup */\n  type: typeof ExporterType.Custom;\n  /** User-defined setup function */\n  setup: () => Promise<void> | void;\n}\n\n/**\n * Union type of all supported trace exporter configurations.\n *\n * @public\n */\nexport type ObservabilityConfig =\n  | ConsoleTraceConfig\n  | OTLPTraceConfig\n  | CustomTraceConfig;\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudbase/agent-observability",
-  "version": "0.0.16",
+  "version": "0.0.18",
   "description": "OpenInference-compatible observability for AG-Kit",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -65,7 +65,7 @@
     "@arizeai/openinference-semantic-conventions": "^2.1.7",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/semantic-conventions": "^1.39.0",
-    "@cloudbase/agent-shared": "^0.0.16"
+    "@cloudbase/agent-shared": "^0.0.18"
   },
   "optionalDependencies": {
     "@opentelemetry/exporter-trace-otlp-http": "^0.210.0",

package/src/core/attributes.ts

@@ -1,6 +1,6 @@
-import { OBSERVABILITY_TRACER_NAME, OtelSpanAttributes } from "./constants.js";
+import { OtelSpanAttributes, OpenInferenceSpanKind } from "./constants";
 import { SemanticConventions } from "@arizeai/openinference-semantic-conventions";
-import { ObservationAttributes, TraceAttributes, ObservationType } from "../types.js";
+import { ObservationAttributes, TraceAttributes, ObservationType, LLMMessage, Document, ToolCall } from "../types";
 import { type Attributes } from "@opentelemetry/api";
 
 /**
@@ -64,7 +64,7 @@ export function createTraceAttributes({
  * - Uses `openinference.span.kind` for span type
  * - Uses `llm.*` for LLM-specific attributes
  * - Uses `tool.*` for tool-specific attributes
- * - Falls back to `agkit.observation.*` for non-standard attributes
+ * - Uses `observation.*` for non-standard attributes
  *
  * @param type - Observation type (llm, tool, chain, etc.)
  * @param attributes - Observation attributes to convert
@@ -89,20 +89,24 @@ export function createObservationAttributes(
     usageDetails,
   } = attributes;
 
+  // Map observation type to OpenInference span kind
+  // Falls back to CHAIN for unknown types (CHAIN is the generic catch-all in OpenInference)
+  const spanKind = (OpenInferenceSpanKind as Record<string, string>)[type.toUpperCase()] || "CHAIN";
+
   // Base attributes for all observation types
   const otelAttributes: Attributes = {
-    [SemanticConventions.OPENINFERENCE_SPAN_KIND]: type.toUpperCase(),
+    [SemanticConventions.OPENINFERENCE_SPAN_KIND]: spanKind,
     [OtelSpanAttributes.OBSERVATION_TYPE]: type,
     [OtelSpanAttributes.OBSERVATION_LEVEL]: level,
     [OtelSpanAttributes.OBSERVATION_STATUS_MESSAGE]: statusMessage,
     [OtelSpanAttributes.VERSION]: version,
     // Use OpenInference input.value convention
     [SemanticConventions.INPUT_VALUE]: _serialize(input),
-    // Also set legacy agkit.observation.input for compatibility
+    // Also set observation.input for compatibility
     [OtelSpanAttributes.OBSERVATION_INPUT]: _serialize(input),
     // Use OpenInference output.value convention
     [SemanticConventions.OUTPUT_VALUE]: _serialize(output),
-    // Also set legacy agkit.observation.output for compatibility
+    // Also set observation.output for compatibility
     [OtelSpanAttributes.OBSERVATION_OUTPUT]: _serialize(output),
   };
 
@@ -111,10 +115,24 @@ export function createObservationAttributes(
     if (model) {
       otelAttributes[SemanticConventions.LLM_MODEL_NAME] = model;
     }
+    // Extract system and provider safely
+    const system = (attributes as Record<string, unknown>)?.system;
+    const provider = (attributes as Record<string, unknown>)?.provider;
+    const inputMessages = (attributes as Record<string, unknown>)?.inputMessages;
+    const outputMessages = (attributes as Record<string, unknown>)?.outputMessages;
+    const inputMimeType = (attributes as Record<string, unknown>)?.inputMimeType;
+    const outputMimeType = (attributes as Record<string, unknown>)?.outputMimeType;
+
+    if (system !== undefined) {
+      otelAttributes[SemanticConventions.LLM_SYSTEM] = String(system);
+    }
+    if (provider !== undefined) {
+      otelAttributes[SemanticConventions.LLM_PROVIDER] = String(provider);
+    }
     if (modelParameters) {
       otelAttributes[SemanticConventions.LLM_INVOCATION_PARAMETERS] =
         _serialize(modelParameters);
-      // Also set agkit.llm.model_parameters for compatibility
+      // Also set llm.model_parameters for compatibility
       otelAttributes[OtelSpanAttributes.LLM_MODEL_PARAMETERS] =
         _serialize(modelParameters);
     }
@@ -135,7 +153,7 @@ export function createObservationAttributes(
             usage.totalTokens;
         }
       }
-      // Also set legacy agkit.llm.usage_details for compatibility
+      // Also set llm.usage_details for compatibility
       otelAttributes[OtelSpanAttributes.LLM_USAGE_DETAILS] =
         _serialize(usageDetails);
     }
@@ -143,6 +161,22 @@ export function createObservationAttributes(
       otelAttributes[OtelSpanAttributes.LLM_COMPLETION_START_TIME] =
         _serialize(completionStartTime);
     }
+    // Flatten LLM messages
+    if (inputMessages !== undefined && Array.isArray(inputMessages)) {
+      const messageAttrs = _flattenLLMMessages(inputMessages as LLMMessage[], "llm.input_messages");
+      Object.assign(otelAttributes, messageAttrs);
+    }
+    if (outputMessages !== undefined && Array.isArray(outputMessages)) {
+      const messageAttrs = _flattenLLMMessages(outputMessages as LLMMessage[], "llm.output_messages");
+      Object.assign(otelAttributes, messageAttrs);
+    }
+    // Add MIME types
+    if (inputMimeType !== undefined) {
+      otelAttributes[SemanticConventions.INPUT_MIME_TYPE] = String(inputMimeType);
+    }
+    if (outputMimeType !== undefined) {
+      otelAttributes[SemanticConventions.OUTPUT_MIME_TYPE] = String(outputMimeType);
+    }
   }
 
   // Embedding-specific attributes
@@ -156,6 +190,51 @@ export function createObservationAttributes(
     }
   }
 
+  // Tool-specific attributes
+  if (type === "tool") {
+    const toolName = (attributes as Record<string, unknown>)?.toolName ?? (attributes as Record<string, unknown>)?.tool_name;
+    const toolDescription = (attributes as Record<string, unknown>)?.toolDescription;
+    const toolParameters = (attributes as Record<string, unknown>)?.toolParameters;
+    const toolCall = (attributes as Record<string, unknown>)?.toolCall;
+
+    if (toolName !== undefined) {
+      otelAttributes[SemanticConventions.TOOL_NAME] = String(toolName);
+    }
+    if (toolDescription !== undefined) {
+      otelAttributes[SemanticConventions.TOOL_DESCRIPTION] = String(toolDescription);
+    }
+    if (toolParameters !== undefined) {
+      otelAttributes[SemanticConventions.TOOL_PARAMETERS] = _serialize(toolParameters);
+    }
+    // Flatten tool call if present
+    if (toolCall !== undefined && typeof toolCall === "object") {
+      const toolCallAttrs = _flattenToolCall(toolCall as ToolCall);
+      Object.assign(otelAttributes, toolCallAttrs);
+    }
+  }
+
+  // Agent-specific attributes
+  if (type === "agent") {
+    const agentName = (attributes as Record<string, unknown>)?.agentName;
+    if (agentName !== undefined) {
+      otelAttributes[SemanticConventions.AGENT_NAME] = String(agentName);
+    }
+  }
+
+  // Retriever-specific attributes
+  if (type === "retriever") {
+    const documents = (attributes as Record<string, unknown>)?.documents;
+    const query = (attributes as Record<string, unknown>)?.query;
+
+    if (documents !== undefined && Array.isArray(documents)) {
+      const docAttrs = _flattenDocuments(documents as Document[]);
+      Object.assign(otelAttributes, docAttrs);
+    }
+    if (query !== undefined) {
+      otelAttributes["retriever.query"] = String(query);
+    }
+  }
+
   // Add metadata (use OpenInference metadata convention)
   const metadataAttrs = _flattenAndSerializeMetadata(
     metadata,
@@ -163,13 +242,21 @@ export function createObservationAttributes(
   );
   Object.assign(otelAttributes, metadataAttrs);
 
-  // Also add agkit.observation.metadata for compatibility
+  // Also add observation.metadata for compatibility
   const obsetvabilityMetadataAttrs = _flattenAndSerializeMetadata(
     metadata,
     OtelSpanAttributes.OBSERVATION_METADATA
   );
   Object.assign(otelAttributes, obsetvabilityMetadataAttrs);
 
+  // Pass through any additional custom attributes (e.g., agui.thread_id, agui.run_id)
+  // Only pass through attributes that haven't been set yet to avoid overwriting internal ones
+  for (const [key, value] of Object.entries(attributes)) {
+    if (!(key in otelAttributes) && value !== undefined && value !== null) {
+      otelAttributes[key] = typeof value === 'string' ? value : _serialize(value);
+    }
+  }
+
   // Filter out null/undefined values
   return Object.fromEntries(
     Object.entries(otelAttributes).filter(([_, v]) => v != null),
@@ -198,10 +285,10 @@ function _serialize(obj: unknown): string | undefined {
  *
  * Converts nested metadata objects into dot-notation attribute keys.
  * For example, `{ database: { host: 'localhost' } }` becomes
- * `{ 'metadata.database.host': 'localhost' }` (or 'agkit.observation.metadata.database.host').
+ * `{ 'metadata.database.host': 'localhost' }` (or 'observation.metadata.database.host').
  *
  * @param metadata - Metadata object to flatten
- * @param prefix - Attribute prefix (e.g., 'metadata' or 'agkit.observation.metadata')
+ * @param prefix - Attribute prefix (e.g., 'metadata' or 'observation.metadata')
  * @returns Flattened metadata attributes
  * @internal
  */
@@ -231,3 +318,161 @@ function _flattenAndSerializeMetadata(
 
   return metadataAttributes;
 }
+
+/**
+ * Flattens LLM messages into OpenTelemetry attributes.
+ *
+ * Follows OpenInference convention:
+ * - llm.input_messages.{i}.message.role
+ * - llm.input_messages.{i}.message.content
+ * - llm.input_messages.{i}.message.tool_calls
+ *
+ * @param messages - Array of LLM messages
+ * @param prefix - Attribute prefix ('llm.input_messages' or 'llm.output_messages')
+ * @returns Flattened message attributes
+ * @internal
+ */
+function _flattenLLMMessages(
+  messages: LLMMessage[] | undefined,
+  prefix: string,
+): Record<string, string> {
+  const attributes: Record<string, string> = {};
+
+  if (!messages || !Array.isArray(messages)) {
+    return attributes;
+  }
+
+  try {
+    messages.forEach((msg, index) => {
+      if (!msg || typeof msg !== "object") return;
+
+      const baseKey = `${prefix}.${index}.message`;
+
+      if (msg.role !== undefined) {
+        attributes[`${baseKey}.role`] = String(msg.role);
+      }
+      if (msg.content !== undefined) {
+        attributes[`${baseKey}.content`] = String(msg.content);
+      }
+      if (msg.toolCallId !== undefined) {
+        attributes[`${baseKey}.tool_call_id`] = String(msg.toolCallId);
+      }
+
+      // Flatten tool calls if present
+      if (msg.toolCalls && Array.isArray(msg.toolCalls)) {
+        msg.toolCalls.forEach((toolCall, tcIndex) => {
+          if (!toolCall || typeof toolCall !== "object") return;
+
+          const tcKey = `${baseKey}.tool_calls.${tcIndex}`;
+
+          if (toolCall.id !== undefined) {
+            attributes[`${tcKey}.id`] = String(toolCall.id);
+          }
+          if (toolCall.function !== undefined) {
+            if (toolCall.function.name !== undefined) {
+              attributes[`${tcKey}.function.name`] = String(toolCall.function.name);
+            }
+            if (toolCall.function.arguments !== undefined) {
+              attributes[`${tcKey}.function.arguments`] = String(toolCall.function.arguments);
+            }
+          }
+        });
+      }
+    });
+  } catch (e) {
+    // Silent fail - don't block business logic for observability
+  }
+
+  return attributes;
+}
+
+/**
+ * Flattens documents into OpenTelemetry attributes.
+ *
+ * Follows OpenInference convention:
+ * - retrieval.documents.{i}.document.id
+ * - retrieval.documents.{i}.document.content
+ * - retrieval.documents.{i}.document.score
+ * - retrieval.documents.{i}.document.metadata
+ *
+ * @param documents - Array of documents
+ * @returns Flattened document attributes
+ * @internal
+ */
+function _flattenDocuments(
+  documents: Document[] | undefined,
+): Record<string, string> {
+  const attributes: Record<string, string> = {};
+
+  if (!documents || !Array.isArray(documents)) {
+    return attributes;
+  }
+
+  try {
+    documents.forEach((doc, index) => {
+      if (!doc || typeof doc !== "object") return;
+
+      const baseKey = `retrieval.documents.${index}.document`;
+
+      if (doc.id !== undefined) {
+        attributes[`${baseKey}.id`] = String(doc.id);
+      }
+      if (doc.content !== undefined) {
+        attributes[`${baseKey}.content`] = String(doc.content);
+      }
+      if (doc.score !== undefined) {
+        attributes[`${baseKey}.score`] = String(doc.score);
+      }
+      if (doc.metadata !== undefined && typeof doc.metadata === "object") {
+        const metadataSerialized = _serialize(doc.metadata);
+        if (metadataSerialized) {
+          attributes[`${baseKey}.metadata`] = metadataSerialized;
+        }
+      }
+    });
+  } catch (e) {
+    // Silent fail - don't block business logic for observability
+  }
+
+  return attributes;
+}
+
+/**
+ * Flattens tool call into OpenTelemetry attributes.
+ *
+ * Follows OpenInference convention:
+ * - tool_call.id
+ * - tool_call.function.name
+ * - tool_call.function.arguments
+ *
+ * @param toolCall - Tool call object
+ * @returns Flattened tool call attributes
+ * @internal
+ */
+function _flattenToolCall(
+  toolCall: ToolCall | undefined,
+): Record<string, string> {
+  const attributes: Record<string, string> = {};
+
+  if (!toolCall || typeof toolCall !== "object") {
+    return attributes;
+  }
+
+  try {
+    if (toolCall.id !== undefined) {
+      attributes["tool_call.id"] = String(toolCall.id);
+    }
+    if (toolCall.function !== undefined) {
+      if (toolCall.function.name !== undefined) {
+        attributes["tool_call.function.name"] = String(toolCall.function.name);
+      }
+      if (toolCall.function.arguments !== undefined) {
+        attributes["tool_call.function.arguments"] = String(toolCall.function.arguments);
+      }
+    }
+  } catch (e) {
+    // Silent fail - don't block business logic for observability
+  }
+
+  return attributes;
+}