@cloudbase/agent-observability 0.0.16 → 0.0.18

package/src/index.ts

@@ -4,14 +4,13 @@
  * @packageDocumentation
  */
 
-import { trace, context, TimeInput, SpanStatusCode, Span, SpanContext } from "@opentelemetry/api";
+import { trace, context, TimeInput, SpanStatusCode, Span, SpanContext, Link } from "@opentelemetry/api";
 
 import {
   createObservationAttributes,
   createTraceAttributes,
-} from "./core/attributes.js";
+} from "./core/attributes";
 import {
-  ObservationSpan,
   ObservationLLM,
   ObservationEmbedding,
   ObservationAgent,
@@ -22,8 +21,8 @@ import {
   ObservationEvaluator,
   ObservationGuardrail,
   type Observation,
-} from "./core/spanWrapper.js";
-import { getTracer } from "./core/tracerProvider.js";
+} from "./core/spanWrapper";
+import { getTracer } from "./core/tracerProvider";
 import {
   ObservationType,
   ObservationLevel,
@@ -39,7 +38,10 @@ import {
   EmbeddingAttributes,
   ObservationAttributes,
   TraceAttributes,
-} from "./types.js";
+  LLMMessage,
+  ToolCall,
+  Document,
+} from "./types";
 
 // Export types
 export type {
@@ -57,11 +59,13 @@ export type {
   EmbeddingAttributes,
   ObservationAttributes,
   TraceAttributes,
+  LLMMessage,
+  ToolCall,
+  Document,
 };
 
 // Export observation classes
 export {
-  ObservationSpan,
   ObservationLLM,
   ObservationEmbedding,
   ObservationAgent,
@@ -80,12 +84,24 @@ export type { Observation };
 export {
   createTraceAttributes,
   createObservationAttributes,
-} from "./core/attributes.js";
+} from "./core/attributes";
 export {
   setTracerProvider,
   getTracerProvider,
   getTracer,
-} from "./core/tracerProvider.js";
+} from "./core/tracerProvider";
+
+// Export trace context utilities
+export {
+  validateTraceId,
+  validateSpanId,
+  validateTraceContext,
+  createSpanLinkFromContext,
+  extractTraceContextFromHeaders,
+  processTraceContextFromHeaders,
+  type TraceContextValidation,
+  type ProcessedTraceContext,
+} from "./core/trace-context";
 
 /**
  * Options for starting observations (spans).
@@ -97,6 +113,8 @@ export type StartObservationOptions = {
   startTime?: Date;
   /** Parent span context to attach this observation to */
   parentSpanContext?: SpanContext;
+  /** Optional links to external or related spans */
+  links?: Link[];
 };
 
 /**
@@ -105,12 +123,12 @@ export type StartObservationOptions = {
  * @public
  */
 export type StartObservationOpts = StartObservationOptions & {
-  /** Type of observation to create. Defaults to 'span' */
+  /** Type of observation to create. Defaults to 'chain' */
   asType?: ObservationType;
 };
 
 /**
- * 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
@@ -120,10 +138,14 @@ function createOtelSpan(params: {
   name: string;
   startTime?: TimeInput;
   parentSpanContext?: SpanContext;
+  links?: Link[];
 }): Span {
   return getTracer().startSpan(
     params.name,
-    { startTime: params.startTime },
+    {
+      startTime: params.startTime,
+      links: params.links || [],
+    },
     createParentContext(params.parentSpanContext),
   );
 }
@@ -199,19 +221,18 @@ export function startObservation(
 export function startObservation(
   name: string,
   attributes?: BaseSpanAttributes,
-  options?: StartObservationOpts & { asType?: "span" },
-): ObservationSpan;
+  options?: StartObservationOpts & { asType?: "chain" },
+): ObservationChain;
 
 /**
- * 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)
+ * - **chain**: Multi-step workflows (default for generic operations)
  * - **llm**: LLM calls and AI model interactions
  * - **embedding**: Text embedding and vector operations
  * - **agent**: AI agent workflows
  * - **tool**: Individual tool calls
- * - **chain**: Multi-step processes
  * - **retriever**: Document retrieval
  * - **reranker**: Result reranking
  * - **evaluator**: Quality assessment
@@ -261,7 +282,7 @@ export function startObservation(
     | GuardrailAttributes,
   options?: StartObservationOpts,
 ): Observation {
-  const { asType = "span", ...observationOptions } = options || {};
+  const { asType = "chain", ...observationOptions } = options || {};
 
   const otelSpan = createOtelSpan({
     name,
@@ -323,9 +344,8 @@ export function startObservation(
         attributes: attributes as GuardrailAttributes,
       });
 
-    case "span":
     default:
-      return new ObservationSpan({
+      return new ObservationChain({
         otelSpan,
         attributes: attributes as BaseSpanAttributes,
       });
@@ -434,9 +454,6 @@ function wrapPromise<T>(
 }
 
 // Function overloads for startActiveObservation
-export function startActiveObservation<
-  F extends (observation: ObservationSpan) => unknown,
->(name: string, fn: F, options?: StartActiveObservationOpts): ReturnType<F>;
 export function startActiveObservation<
   F extends (observation: ObservationLLM) => unknown,
 >(name: string, fn: F, options?: StartActiveObservationOpts): ReturnType<F>;
@@ -484,12 +501,12 @@ export function startActiveObservation<
  * import { startActiveObservation } from './observability';
  *
  * // Synchronous function
- * const result = startActiveObservation('data-processing', (span) => {
- *   span.update({ input: { data: [1, 2, 3] } });
+ * const result = startActiveObservation('data-processing', (chain) => {
+ *   chain.update({ input: { data: [1, 2, 3] } });
  *   const processed = data.map(x => x * 2);
- *   span.update({ output: { result: processed } });
+ *   chain.update({ output: { result: processed } });
  *   return processed;
- * }, { asType: 'span' });
+ * }, { asType: 'chain' });
  *
  * // Asynchronous function
  * const embeddings = await startActiveObservation(
@@ -511,12 +528,12 @@ export function startActiveObservation<
  * // Disable automatic ending (for long-running operations)
  * startActiveObservation(
  *   'background-task',
- *   (span) => {
- *     span.update({ input: { taskId: '123' } });
- *     startBackgroundProcess(span);
+ *   (chain) => {
+ *     chain.update({ input: { taskId: '123' } });
+ *     startBackgroundProcess(chain);
  *     return 'started';
  *   },
- *   { asType: 'span', endOnExit: false }
+ *   { asType: 'chain', endOnExit: false }
  * );
  * ```
  *
@@ -528,7 +545,7 @@ export function startActiveObservation<
 export function startActiveObservation<
   F extends (observation: Observation) => unknown,
 >(name: string, fn: F, options?: StartActiveObservationOpts): ReturnType<F> {
-  const { asType = "span", endOnExit, ...observationOptions } = options || {};
+  const { asType = "chain", endOnExit, ...observationOptions } = options || {};
 
   return getTracer().startActiveSpan(
     name,
@@ -552,9 +569,6 @@ export function startActiveObservation<
           case "tool":
             observation = new ObservationTool({ otelSpan: span });
             break;
-          case "chain":
-            observation = new ObservationChain({ otelSpan: span });
-            break;
           case "retriever":
             observation = new ObservationRetriever({ otelSpan: span });
             break;
@@ -567,9 +581,9 @@ export function startActiveObservation<
           case "guardrail":
             observation = new ObservationGuardrail({ otelSpan: span });
             break;
-          case "span":
+          case "chain":
           default:
-            observation = new ObservationSpan({ otelSpan: span });
+            observation = new ObservationChain({ otelSpan: span });
         }
 
         const result = fn(observation as Parameters<F>[0]);
@@ -629,7 +643,7 @@ export function updateActiveObservation(
     return;
   }
 
-  span.setAttributes(createObservationAttributes("span", attributes));
+  span.setAttributes(createObservationAttributes("chain", attributes));
 }
 
 // ============================================================================
@@ -706,7 +720,7 @@ export function observe<T extends (...args: any[]) => any>(
   options: ObserveOptions = {},
 ): T {
   const {
-    asType = "span",
+    asType = "chain",
     captureInput = true,
     captureOutput = true,
     ...observationOptions
@@ -727,7 +741,7 @@ export function observe<T extends (...args: any[]) => any>(
       inputData ? { input: inputData } : {},
       {
         ...observationOptions,
-        asType: asType as "span",
+        asType: asType as "chain",
       },
     );
 

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";
@@ -22,11 +22,10 @@ import type { ChainValues } from "@langchain/core/utils/types";
 import {
   startObservation,
   type ObservationLLM,
-  type ObservationSpan,
   type ObservationTool,
   type Observation,
   type ObservationAttributes,
-} from "../index.js";
+} from "../index";
 import type { SpanContext } from "@opentelemetry/api";
 import { type Logger, noopLogger } from "@cloudbase/agent-shared";
 
@@ -79,10 +78,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
  */
@@ -104,6 +103,9 @@ export class CallbackHandler extends BaseCallbackHandler {
   // External parent context from AG-UI.Server span
   private externalParentSpanContext?: SpanContext;
 
+  // External metadata from AG-UI.Server (e.g., threadId, runId)
+  private externalMetadata?: Record<string, string>;
+
   // Adapter name for ROOT span prefix
   private adapterName?: string;
 
@@ -130,10 +132,12 @@ export class CallbackHandler extends BaseCallbackHandler {
    * to the server-level span, creating a unified trace hierarchy.
    *
    * @param spanContext - SpanContext from the AG-UI.Server span
+   * @param metadata - Optional metadata from server (e.g., threadId, runId)
    * @public
    */
-  setExternalParentContext(spanContext: SpanContext): void {
+  setExternalParentContext(spanContext: SpanContext, metadata?: Record<string, string>): void {
     this.externalParentSpanContext = spanContext;
+    this.externalMetadata = metadata;
   }
 
   async handleLLMNewToken(
@@ -161,8 +165,6 @@ export class CallbackHandler extends BaseCallbackHandler {
     name?: string
   ): Promise<void> {
     try {
-      this.logger.debug?.(`Chain start with Id: ${runId}`);
-
       const runName = name ?? chain.id.at(-1)?.toString() ?? "Langchain Run";
 
       this.registerPromptInfo(parentRunId, metadata);
@@ -199,11 +201,11 @@ export class CallbackHandler extends BaseCallbackHandler {
         parentRunId,
         runId,
         tags,
-        metadata,
+        metadata: this.joinTagsAndMetaData(tags, metadata),
         attributes: {
           input: finalInput,
         },
-        asType: "span",
+        asType: "chain",
       });
 
       const traceTags = [...new Set([...(tags ?? []), ...this.tags])];
@@ -328,6 +330,8 @@ export class CallbackHandler extends BaseCallbackHandler {
     }
 
     let extractedModelName: string | undefined;
+    let extractedSystem: string | undefined;
+    let extractedProvider: string | undefined;
     if (extraParams) {
       const invocationParamsModelName = (
         extraParams.invocation_params as InvocationParams
@@ -338,6 +342,11 @@ export class CallbackHandler extends BaseCallbackHandler {
           : undefined;
 
       extractedModelName = invocationParamsModelName ?? metadataModelName;
+      
+      // Extract provider from metadata (e.g., "ls_provider" from LangChain)
+      if (metadata && "ls_provider" in metadata) {
+        extractedProvider = metadata["ls_provider"] as string;
+      }
     }
 
     const registeredPrompt = this.promptToParentRunMap.get(
@@ -479,7 +488,7 @@ export class CallbackHandler extends BaseCallbackHandler {
         attributes: {
           input,
         },
-        metadata,
+        metadata: this.joinTagsAndMetaData(tags, metadata),
         tags,
         asType: "tool",
       });
@@ -507,8 +516,8 @@ export class CallbackHandler extends BaseCallbackHandler {
           input: query,
         },
         tags,
-        metadata,
-        asType: "span",
+        metadata: this.joinTagsAndMetaData(tags, metadata),
+        asType: "retriever",
       });
     } catch (e) {
       this.logger.debug?.(e instanceof Error ? e.message : String(e));
@@ -710,7 +719,7 @@ export class CallbackHandler extends BaseCallbackHandler {
     attributes: Record<string, unknown>;
     metadata?: Record<string, unknown>;
     tags?: string[];
-    asType?: "span" | "llm" | "tool";
+    asType?: "llm" | "tool" | "chain" | "retriever" | "agent";
   }): Observation {
     const { runName, runId, parentRunId, attributes, metadata, tags, asType } =
       params;
@@ -736,15 +745,22 @@ export class CallbackHandler extends BaseCallbackHandler {
       finalRunName = `Adapter.${this.adapterName}`;
     }
 
+    // Add agui.thread_id and agui.run_id to ALL spans if external metadata available
+    // This ensures consistent tagging across the entire trace hierarchy
+    const serverMetadata = this.externalMetadata
+      ? { "agui.thread_id": this.externalMetadata.threadId, "agui.run_id": this.externalMetadata.runId }
+      : {};
+
     const observation = startObservation(
       finalRunName,
       {
         version: this.version,
         metadata: this.joinTagsAndMetaData(tags, metadata),
         ...attributes,
+        ...serverMetadata,
       },
       {
-        asType: asType ?? "span",
+        asType: asType ?? "chain",
         parentSpanContext,
       }
     );
@@ -765,6 +781,17 @@ export class CallbackHandler extends BaseCallbackHandler {
       return;
     }
 
+    // Check if this is an error and set span status accordingly
+    const level = attributes.level as string | undefined;
+    const statusMessage = attributes.statusMessage as string | undefined;
+    if (level === "ERROR") {
+      try {
+        observation.setErrorStatus(statusMessage || "Unknown error");
+      } catch (e) {
+        this.logger.debug?.("Failed to set span error status:", e);
+      }
+    }
+
     // Type-safe update: cast to ObservationAttributes which is the union of all observation attribute types
     observation.update(attributes as ObservationAttributes).end();
 
@@ -797,7 +824,10 @@ export class CallbackHandler extends BaseCallbackHandler {
       return;
     }
 
-    const reservedKeys = ["promptInfo", "userId", "sessionId"];
+    // Filter out keys that should not be in metadata:
+    // - thread_id, run_id: Become agui.thread_id, agui.run_id at span level
+    // - promptInfo, userId, sessionId: Reserved for internal use
+    const reservedKeys = ["promptInfo", "userId", "sessionId", "thread_id", "runId", "run_id"];
 
     return Object.fromEntries(
       Object.entries(metadata).filter(([key, _]) => !reservedKeys.includes(key))
@@ -893,4 +923,5 @@ export class CallbackHandler extends BaseCallbackHandler {
 
     return response;
   }
+
 }

package/src/langchain/index.ts

@@ -4,4 +4,4 @@
  * @module
  */
 
-export { CallbackHandler } from "./CallbackHandler.js";
+export { CallbackHandler } from "./CallbackHandler";

package/src/server/SingleLineConsoleSpanExporter.ts

@@ -0,0 +1,141 @@
+/**
+ * Custom console exporter that outputs single-line JSON.
+ *
+ * This exporter outputs spans as single-line JSON for easier parsing
+ * with line-based tools (grep, jq, etc.).
+ *
+ * To switch back to standard multi-line output, use ConsoleSpanExporter instead.
+ *
+ * @example
+ * ```typescript
+ * // Single-line (current default)
+ * const exporter = new SingleLineConsoleSpanExporter();
+ *
+ * // Multi-line (standard OTel)
+ * import { ConsoleSpanExporter } from '@opentelemetry/sdk-trace-base';
+ * const exporter = new ConsoleSpanExporter();
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+import type { SpanExporter, ReadableSpan } from '@opentelemetry/sdk-trace-base';
+import { OBSERVABILITY_TRACER_NAME } from '../core/constants';
+
+/**
+ * Export result codes.
+ */
+export enum ExportResultCode {
+  SUCCESS = 0,
+  FAILED = 1,
+}
+
+/**
+ * Export result interface.
+ */
+export interface ExportResult {
+  code: ExportResultCode;
+  error?: Error;
+}
+
+/**
+ * Custom console exporter that outputs single-line JSON.
+ *
+ * This exporter outputs spans as single-line JSON for easier parsing
+ * with line-based tools (grep, jq, etc.).
+ */
+export class SingleLineConsoleSpanExporter implements SpanExporter {
+  /**
+   * Export spans as single-line JSON.
+   */
+  export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void {
+    try {
+      for (const span of spans) {
+        const spanDict = this.spanToDict(span);
+        // Single-line JSON output
+        const jsonLine = JSON.stringify(spanDict);
+        console.log(jsonLine);
+      }
+      resultCallback({ code: ExportResultCode.SUCCESS });
+    } catch (error) {
+      resultCallback({ code: ExportResultCode.FAILED, error: error as Error });
+    }
+  }
+
+  /**
+   * Shutdown the exporter.
+   */
+  shutdown(): Promise<void> {
+    return Promise.resolve();
+  }
+
+  /**
+   * Force flush the exporter.
+   */
+  forceFlush?(): Promise<void> {
+    return Promise.resolve();
+  }
+
+  /**
+   * Convert a ReadableSpan to a dictionary for JSON serialization.
+   */
+  private spanToDict(span: ReadableSpan): Record<string, unknown> {
+    try {
+      const context = span.spanContext();
+
+      // Get parent span ID from parentSpanContext if available
+      // Some versions use parentSpanId directly, others use parentSpanContext.spanId
+      const parentId = (span as any).parentSpanId || span.parentSpanContext?.spanId;
+
+      const result: Record<string, unknown> = {
+        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,
+        },
+      };
+
+      // Add log source identifier for console output
+      result['_log_from'] = OBSERVABILITY_TRACER_NAME;
+
+      return result;
+    } catch {
+      return {};
+    }
+  }
+}
+
+/**
+ * Check if single-line console exporter should be used.
+ *
+ * Set CONSOLE_EXPORTER_SINGLE_LINE=false to use standard multi-line output.
+ */
+export function isSingleLineConsoleExporterEnabled(): boolean {
+  const value = process.env.CONSOLE_EXPORTER_SINGLE_LINE?.toLowerCase() || 'true';
+  return ['true', '1', 'yes', 'on'].includes(value);
+}

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
@@ -64,6 +64,7 @@ export interface BatchConfig {
  * Console trace exporter configuration.
  *
  * Outputs traces to stdout in JSON format using ConsoleSpanExporter.
+ * Uses SimpleSpanProcessor for immediate export (no batching).
  * Useful for development and debugging.
  *
  * @example
@@ -71,7 +72,6 @@ export interface BatchConfig {
  * import { ExporterType } from '@cloudbase/agent-observability/server';
  *
  * { type: ExporterType.Console }
- * { type: ExporterType.Console, batch: { maxExportBatchSize: 200 } }
  * ```
  *
  * @public
@@ -79,8 +79,6 @@ export interface BatchConfig {
 export interface ConsoleTraceConfig {
   /** Discriminator for console exporter */
   type: typeof ExporterType.Console;
-  /** Optional batch processing configuration */
-  batch?: BatchConfig;
 }
 
 /**

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.
@@ -15,7 +15,13 @@ export {
   type OTLPTraceConfig,
   type CustomTraceConfig,
   type BatchConfig,
-} from './setup.js';
+} from './setup';
 
 // Exporter type constants
-export { ExporterType } from './config.js';
+export { ExporterType } from './config';
+
+// Single-line console exporter for easier parsing
+export {
+  SingleLineConsoleSpanExporter,
+  isSingleLineConsoleExporterEnabled,
+} from './SingleLineConsoleSpanExporter';