@cloudbase/agent-observability 1.0.1-alpha.19 → 1.0.1-alpha.23

package/dist/server.mjs

@@ -1,4 +1,4 @@
-import "./chunk-WMJKH4XE.mjs";
+import "./chunk-NFEGQTCC.mjs";
 
 // src/server/SingleLineConsoleSpanExporter.ts
 var SingleLineConsoleSpanExporter = class {
@@ -159,7 +159,7 @@ async function setupOTLPExporter(config) {
   const { trace } = await import("@opentelemetry/api");
   const { resourceFromAttributes } = await import("@opentelemetry/resources");
   const { NodeTracerProvider } = await import("@opentelemetry/sdk-trace-node");
-  const { OTLPTraceExporter } = await import("./esm-M4BB7YBD.mjs");
+  const { OTLPTraceExporter } = await import("./esm-PGEDANAI.mjs");
   const { BatchSpanProcessor } = await import("@opentelemetry/sdk-trace-base");
   const batchConfig = resolveBatchConfig(config.batch);
   let provider = trace.getTracerProvider();

package/dist/server.mjs.map

@@ -1 +1 @@
-{"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';\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    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    return {\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}\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 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';\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.\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 *\n * Uses SingleLineConsoleSpanExporter by default for easier parsing with line-based tools.\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, BatchSpanProcessor } = await import(\n    '@opentelemetry/sdk-trace-base'\n  );\n\n  const batchConfig = resolveBatchConfig(config.batch);\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  if (isRealProvider) {\n    // Add processor to existing provider\n    const processor = new BatchSpanProcessor(exporter, batchConfig);\n    (provider as any).addSpanProcessor(processor);\n\n    console.info(\n      `[Observability] Console exporter configured (${exporterType}, 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 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 (${exporterType}, 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';\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    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    return {\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}\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.\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 *\n * Uses SingleLineConsoleSpanExporter by default for easier parsing with line-based tools.\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, BatchSpanProcessor } = await import(\n    '@opentelemetry/sdk-trace-base'\n  );\n\n  const batchConfig = resolveBatchConfig(config.batch);\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  if (isRealProvider) {\n    // Add processor to existing provider\n    const processor = new BatchSpanProcessor(exporter, batchConfig);\n    (provider as any).addSpanProcessor(processor);\n\n    console.info(\n      `[Observability] Console exporter configured (${exporterType}, 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 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 (${exporterType}, 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 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 * 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":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudbase/agent-observability",
-  "version": "1.0.1-alpha.19",
+  "version": "1.0.1-alpha.23",
   "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": "^1.0.1-alpha.19"
+    "@cloudbase/agent-shared": "^1.0.1-alpha.23"
   },
   "optionalDependencies": {
     "@opentelemetry/exporter-trace-otlp-http": "^0.210.0",

package/src/core/attributes.ts

@@ -1,4 +1,4 @@
-import { OBSERVABILITY_TRACER_NAME, OtelSpanAttributes } from "./constants";
+import { OBSERVABILITY_TRACER_NAME, OtelSpanAttributes, OpenInferenceSpanKind } from "./constants";
 import { SemanticConventions } from "@arizeai/openinference-semantic-conventions";
 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 UNKNOWN for unknown types (consistent with Python SDK)
+  const spanKind = (OpenInferenceSpanKind as Record<string, string>)[type.toUpperCase()] || "UNKNOWN";
+
   // 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),
   };
 
@@ -128,7 +132,7 @@ export function createObservationAttributes(
     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);
     }
@@ -149,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);
     }
@@ -238,7 +242,7 @@ 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
@@ -281,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
  */

package/src/core/constants.ts

@@ -1,10 +1,10 @@
 /**
- * OTEL attribute constants for AG-Kit observability.
+ * OTEL attribute constants for observability.
  *
  * Uses OpenInference semantic conventions where applicable:
  * https://github.com/Arize-ai/openinference/tree/main/spec
  *
- * Falls back to AG-Kit specific attributes where OpenInference
+ * Falls back to non-standard attributes where OpenInference
  * doesn't define a standard.
  *
  * @module
@@ -21,21 +21,23 @@ export { OpenInferenceSpanKind };
 /**
  * SDK information
  */
-export const OBSERVABILITY_TRACER_NAME = "agkit-tracer";
-export const OBSERVABILITY_SDK_NAME = "@agkit/observability";
-// Version will be injected from package.json
+// Brandless defaults: avoid emitting project-specific identifiers into traces.
+// Users can still override service.name via OTEL_SERVICE_NAME.
+export const OBSERVABILITY_TRACER_NAME = "agui-tracer";
+export const OBSERVABILITY_SDK_NAME = "observability";
+export const OBSERVABILITY_SDK_VERSION = "0.1.0";
 
 /**
  * Combined attribute namespace for internal use
- * Provides a single namespace for all OTEL attributes used by AG-Kit
+ * Provides a single namespace for all OTEL attributes used internally.
  *
- * Combines OpenInference SemanticConventions with AG-Kit specific attributes
+ * Combines OpenInference SemanticConventions with non-standard attributes
  */
 export const OtelSpanAttributes = {
   // OpenInference - re-export all standard conventions
   ...SemanticConventions,
 
-  // AG-Kit Trace attributes (non-standard)
+  // Trace attributes (non-standard)
   TRACE_NAME: "trace.name",
   TRACE_TAGS: "trace.tags",
   TRACE_PUBLIC: "trace.public",
@@ -43,7 +45,7 @@ export const OtelSpanAttributes = {
   TRACE_INPUT: "trace.input",
   TRACE_OUTPUT: "trace.output",
 
-  // AG-Kit Observation attributes (non-standard)
+  // Observation attributes (non-standard)
   OBSERVATION_TYPE: "observation.type",
   OBSERVATION_LEVEL: "observation.level",
   OBSERVATION_STATUS_MESSAGE: "observation.status_message",
@@ -51,25 +53,21 @@ export const OtelSpanAttributes = {
   OBSERVATION_OUTPUT: "observation.output",
   OBSERVATION_METADATA: "observation.metadata",
 
-  // AG-Kit LLM-specific (non-standard)
+  // LLM-specific (non-standard)
   LLM_COMPLETION_START_TIME: "llm.completion_start_time",
   LLM_MODEL_PARAMETERS: "llm.model_parameters",
   LLM_USAGE_DETAILS: "llm.usage_details",
   LLM_COST_DETAILS: "llm.cost_details",
 
-  // AG-Kit Retriever-specific (non-standard)
+  // Retriever-specific (non-standard)
   RETRIEVER_NAME: "retriever.name",
   RETRIEVER_QUERY: "retriever.query",
   RETRIEVER_INDEX_ID: "retriever.index_id",
   RETRIEVER_TOP_K: "retriever.top_k",
 
-  // AG-Kit General (non-standard)
+  // General (non-standard)
   ENVIRONMENT: "environment",
   RELEASE: "release",
   VERSION: "version",
 } as const;
 
-/**
- * Type for the OtelSpanAttributes object values
- */
-export type OtelSpanAttributeValues = typeof OtelSpanAttributes[keyof typeof OtelSpanAttributes];

package/src/core/spanWrapper.ts

@@ -1,4 +1,4 @@
-import { Span, TimeInput } from "@opentelemetry/api";
+import { Span, TimeInput, SpanStatus, SpanStatusCode } from "@opentelemetry/api";
 
 import { createObservationAttributes, createTraceAttributes } from "./attributes";
 import { getTracer } from "./tracerProvider";
@@ -83,7 +83,7 @@ abstract class BaseObservation {
     }
   }
 
-  /** Gets the AG-Kit OpenTelemetry tracer instance */
+  /** Gets the OpenTelemetry tracer instance */
   protected get tracer() {
     return getTracer();
   }
@@ -97,6 +97,29 @@ abstract class BaseObservation {
     this.otelSpan.end(endTime);
   }
 
+  /**
+   * Sets the span status.
+   *
+   * @param status - The status to set on the span
+   */
+  public setStatus(status: SpanStatus) {
+    this.otelSpan.setStatus(status);
+  }
+
+  /**
+   * Sets the span status to ERROR.
+   *
+   * Convenience method for marking the span as failed.
+   *
+   * @param message - Error description message
+   */
+  public setErrorStatus(message: string) {
+    this.otelSpan.setStatus({
+      code: SpanStatusCode.ERROR,
+      message,
+    });
+  }
+
   /**
    * Updates the OTEL span attributes.
    *

package/src/core/tracerProvider.ts

@@ -1,4 +1,5 @@
 import { TracerProvider, trace, context } from "@opentelemetry/api";
+import { OBSERVABILITY_SDK_NAME, OBSERVABILITY_SDK_VERSION } from "./constants";
 
 const OBSERVABILITY_GLOBAL_SYMBOL = Symbol.for("observability");
 
@@ -130,7 +131,3 @@ export function getTracer() {
     OBSERVABILITY_SDK_VERSION
   );
 }
-
-// SDK version - could be read from package.json in production
-const OBSERVABILITY_SDK_NAME = "ag-kit-observability";
-const OBSERVABILITY_SDK_VERSION = "0.1.0";

package/src/index.ts

@@ -24,6 +24,11 @@ import {
   type Observation,
 } from "./core/spanWrapper";
 import { getTracer } from "./core/tracerProvider";
+import {
+  OBSERVABILITY_TRACER_NAME,
+  OBSERVABILITY_SDK_NAME,
+  OBSERVABILITY_SDK_VERSION,
+} from "./core/constants";
 import {
   ObservationType,
   ObservationLevel,
@@ -93,6 +98,13 @@ export {
   getTracer,
 } from "./core/tracerProvider";
 
+// Export constants
+export {
+  OBSERVABILITY_TRACER_NAME,
+  OBSERVABILITY_SDK_NAME,
+  OBSERVABILITY_SDK_VERSION,
+} from "./core/constants";
+
 /**
  * Options for starting observations (spans).
  *
@@ -116,7 +128,7 @@ export type StartObservationOpts = StartObservationOptions & {
 };
 
 /**
- * Creates an OpenTelemetry span with the AG-Kit tracer.
+ * Creates an OpenTelemetry span with the tracer.
  *
  * @param params - Parameters for span creation
  * @returns The created OpenTelemetry span
@@ -209,7 +221,7 @@ export function startObservation(
 ): ObservationSpan;
 
 /**
- * Creates and starts a new AG-Kit observation.
+ * Creates and starts a new observation.
  *
  * Supports multiple observation types with full TypeScript type safety:
  * - **span**: General-purpose operations (default)

package/src/langchain/CallbackHandler.ts

@@ -1,7 +1,7 @@
 /**
- * LangChain Callback Handler for AG-Kit Observability
+ * LangChain Callback Handler for Observability
  *
- * Converts LangChain callback events into AG-Kit observations with OpenInference semantics.
+ * Converts LangChain callback events into observations with OpenInference semantics.
  */
 
 import type { AgentAction, AgentFinish } from "@langchain/core/agents";
@@ -79,10 +79,10 @@ type PromptInfo = {
 };
 
 /**
- * LangChain Callback Handler for AG-Kit Observability.
+ * LangChain Callback Handler for Observability.
  *
  * This handler intercepts LangChain callbacks and converts them into
- * AG-Kit observations following OpenInference semantic conventions.
+ * Observations following OpenInference semantic conventions.
  *
  * @public
  */
@@ -789,11 +789,7 @@ export class CallbackHandler extends BaseCallbackHandler {
     const statusMessage = attributes.statusMessage as string | undefined;
     if (level === "ERROR") {
       try {
-        const { SpanStatusCode } = require("@opentelemetry/api");
-        observation.otelSpan.setStatus({
-          code: SpanStatusCode.ERROR,
-          message: statusMessage || "Unknown error",
-        });
+        observation.setErrorStatus(statusMessage || "Unknown error");
       } catch (e) {
         this.logger.debug?.("Failed to set span error status:", e);
       }

package/src/server/config.ts

@@ -1,5 +1,5 @@
 /**
- * Observability configuration types for AG-Kit Server.
+ * Observability configuration types for the server.
  *
  * Provides a unified configuration interface for trace exporters:
  * - Console: Development/debugging output

package/src/server/index.ts

@@ -1,5 +1,5 @@
 /**
- * Server utilities for AG-Kit observability.
+ * Server utilities for observability.
  *
  * Provides server-side observability features like AUTO_TRACES_STDOUT
  * and unified trace exporter configuration.

package/src/server/setup.ts

@@ -1,5 +1,5 @@
 /**
- * Observability setup implementation for AG-Kit Server.
+ * Observability setup implementation for the server.
  *
  * Merges configuration from environment variables and parameters,
  * then applies each exporter configuration.

package/src/types.ts

@@ -1,5 +1,5 @@
 /**
- * Types of observations (spans) supported by AG-Kit observability.
+ * Types of observations (spans) supported by observability.
  *
  * These types align with OpenInference semantic conventions:
  * https://github.com/Arize-ai/openinference/tree/main/spec