@cloudbase/agent-observability 1.0.1-alpha.9

package/src/langchain/index.ts

@@ -0,0 +1,7 @@
+/**
+ * LangChain integration for observability.
+ *
+ * @module
+ */
+
+export { CallbackHandler } from "./CallbackHandler.js";

package/src/server/config.ts

@@ -0,0 +1,160 @@
+/**
+ * Observability configuration types for AG-Kit Server.
+ *
+ * Provides a unified configuration interface for trace exporters:
+ * - Console: Development/debugging output
+ * - OTLP: Production export to Langfuse, Jaeger, etc.
+ * - Custom: User-defined setup logic
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Trace exporter type constants.
+ *
+ * @example
+ * ```typescript
+ * import { ExporterType } from '@cloudbase/agent-observability/server';
+ *
+ * { type: ExporterType.Console }
+ * { type: ExporterType.OTLP }
+ * { type: ExporterType.Custom }
+ * ```
+ *
+ * @public
+ */
+export const ExporterType = {
+  /** Console exporter - outputs traces to stdout */
+  Console: 'console',
+  /** OTLP exporter - sends traces to OTLP-compatible backend */
+  OTLP: 'otlp',
+  /** Custom exporter - user-defined setup logic */
+  Custom: 'custom',
+} as const;
+
+/**
+ * Trace exporter type literal values.
+ *
+ * @public
+ */
+export type ExporterType = typeof ExporterType[keyof typeof ExporterType];
+
+/**
+ * Batch processing configuration for span exporters.
+ *
+ * Used by BatchSpanProcessor to optimize performance:
+ * - Collects spans in memory and exports them in batches
+ * - Reduces I/O operations (console) or network requests (OTLP)
+ * - Recommended for production environments
+ *
+ * @public
+ */
+export interface BatchConfig {
+  /** Maximum number of spans per export batch (default: 100) */
+  maxExportBatchSize?: number;
+  /** Maximum delay in milliseconds before exporting (default: 5000) */
+  scheduledDelayMillis?: number;
+  /** Maximum queue size (default: 2048) */
+  maxQueueSize?: number;
+  /** Export timeout in milliseconds (default: 30000) */
+  exportTimeoutMillis?: number;
+}
+
+/**
+ * Console trace exporter configuration.
+ *
+ * Outputs traces to stdout in JSON format using ConsoleSpanExporter.
+ * Useful for development and debugging.
+ *
+ * @example
+ * ```typescript
+ * import { ExporterType } from '@cloudbase/agent-observability/server';
+ *
+ * { type: ExporterType.Console }
+ * { type: ExporterType.Console, batch: { maxExportBatchSize: 200 } }
+ * ```
+ *
+ * @public
+ */
+export interface ConsoleTraceConfig {
+  /** Discriminator for console exporter */
+  type: typeof ExporterType.Console;
+  /** Optional batch processing configuration */
+  batch?: BatchConfig;
+}
+
+/**
+ * OTLP trace exporter configuration.
+ *
+ * Exports traces via OTLP protocol to any compatible backend:
+ * - Langfuse: https://cloud.langfuse.com/api/public/otlp/v1/traces
+ * - Jaeger: http://localhost:4318/v1/traces
+ * - OTel Collector: custom endpoint
+ *
+ * @example
+ * ```typescript
+ * import { ExporterType } from '@cloudbase/agent-observability/server';
+ *
+ * {
+ *   type: ExporterType.OTLP,
+ *   url: 'https://cloud.langfuse.com/api/public/otlp/v1/traces',
+ *   headers: {
+ *     'Authorization': 'Basic ' + btoa('pk-lf-xxx:sk-lf-xxx')
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+export interface OTLPTraceConfig {
+  /** Discriminator for OTLP exporter */
+  type: typeof ExporterType.OTLP;
+  /** OTLP endpoint URL (http/https) */
+  url: string;
+  /** Optional HTTP headers for authentication */
+  headers?: Record<string, string>;
+  /** Request timeout in milliseconds (default: 10000) */
+  timeout?: number;
+  /** Optional batch processing configuration */
+  batch?: BatchConfig;
+}
+
+/**
+ * Custom trace exporter configuration.
+ *
+ * Allows users to provide custom trace setup logic.
+ * Useful for integrations not covered by console/otlp.
+ *
+ * @example
+ * ```typescript
+ * import { ExporterType } from '@cloudbase/agent-observability/server';
+ *
+ * {
+ *   type: ExporterType.Custom,
+ *   setup: async () => {
+ *     const exporter = new MyCustomExporter();
+ *     const provider = new BasicTracerProvider();
+ *     provider.addSpanProcessor(new SimpleSpanProcessor(exporter));
+ *     provider.register();
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+export interface CustomTraceConfig {
+  /** Discriminator for custom setup */
+  type: typeof ExporterType.Custom;
+  /** User-defined setup function */
+  setup: () => Promise<void> | void;
+}
+
+/**
+ * Union type of all supported trace exporter configurations.
+ *
+ * @public
+ */
+export type ObservabilityConfig =
+  | ConsoleTraceConfig
+  | OTLPTraceConfig
+  | CustomTraceConfig;

package/src/server/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Server utilities for AG-Kit observability.
+ *
+ * Provides server-side observability features like AUTO_TRACES_STDOUT
+ * and unified trace exporter configuration.
+ *
+ * @packageDocumentation
+ */
+
+// Unified setup API
+export {
+  setupObservability,
+  type ObservabilityConfig,
+  type ConsoleTraceConfig,
+  type OTLPTraceConfig,
+  type CustomTraceConfig,
+  type BatchConfig,
+} from './setup.js';
+
+// Exporter type constants
+export { ExporterType } from './config.js';

package/src/server/setup.ts

@@ -0,0 +1,344 @@
+/**
+ * Observability setup implementation for AG-Kit Server.
+ *
+ * Merges configuration from environment variables and parameters,
+ * then applies each exporter configuration.
+ *
+ * @packageDocumentation
+ */
+
+import type {
+  BatchConfig,
+  ObservabilityConfig,
+  ConsoleTraceConfig,
+  OTLPTraceConfig,
+  CustomTraceConfig,
+} from './config';
+
+export type {
+  BatchConfig,
+  ObservabilityConfig,
+  ConsoleTraceConfig,
+  OTLPTraceConfig,
+  CustomTraceConfig,
+} from './config';
+
+/**
+ * Environment variable truthy values.
+ * Matches Python SDK implementation for consistency.
+ */
+const TRUTHY_ENV_VALUES = new Set(['true', '1', 'yes', 'on']);
+
+/**
+ * Merged configuration result.
+ * Console config allows merge (param overrides env),
+ * while OTLP and custom configs are arrays (additive).
+ */
+interface MergedConfig {
+  console?: ConsoleTraceConfig | null;
+  otlp: OTLPTraceConfig[];
+  custom: CustomTraceConfig[];
+}
+
+/**
+ * Default batch configuration.
+ */
+const DEFAULT_BATCH_CONFIG: Required<BatchConfig> = {
+  maxExportBatchSize: 100,
+  scheduledDelayMillis: 5000,
+  maxQueueSize: 2048,
+  exportTimeoutMillis: 30000,
+};
+
+/**
+ * Merge environment variable and parameter configurations.
+ *
+ * - AUTO_TRACES_STDOUT env adds a console config
+ * - Parameter configs override/extend env configs
+ */
+function mergeConfigs(paramConfigs: ObservabilityConfig[]): MergedConfig {
+  const result: MergedConfig = {
+    console: null,
+    otlp: [],
+    custom: [],
+  };
+
+  // 1. Check AUTO_TRACES_STDOUT env
+  const autoTracesStdout = process.env.AUTO_TRACES_STDOUT?.toLowerCase() || '';
+  if (TRUTHY_ENV_VALUES.has(autoTracesStdout)) {
+    result.console = { type: 'console' };
+    console.debug(
+      `[Observability] AUTO_TRACES_STDOUT=${autoTracesStdout}, console exporter enabled`
+    );
+  }
+
+  // 2. Process parameter configs
+  for (const config of paramConfigs) {
+    switch (config.type) {
+      case 'console':
+        // Parameter overrides env (merge batch config)
+        result.console = { ...result.console, ...config };
+        break;
+
+      case 'otlp':
+        result.otlp.push(config);
+        break;
+
+      case 'custom':
+        result.custom.push(config);
+        break;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Apply batch configuration with defaults.
+ */
+function resolveBatchConfig(batch?: BatchConfig): Required<BatchConfig> {
+  return { ...DEFAULT_BATCH_CONFIG, ...batch };
+}
+
+/**
+ * Safe wrapper for exporter setup functions.
+ * Ensures individual exporter failures don't crash the entire setup.
+ */
+async function safeSetup(
+  name: string,
+  setupFn: () => Promise<void>
+): Promise<void> {
+  try {
+    await setupFn();
+  } catch (error) {
+    console.warn(
+      `[Observability] ${name} setup failed (non-fatal): ${
+        error instanceof Error ? error.message : String(error)
+      }`
+    );
+    // Don't rethrow - allow other exporters to continue
+  }
+}
+
+/**
+ * Setup console exporter.
+ */
+async function setupConsoleExporter(config: ConsoleTraceConfig): Promise<void> {
+  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);
+
+  // Check if a real TracerProvider already exists
+  let provider = trace.getTracerProvider();
+  const isRealProvider = 'addSpanProcessor' in provider;
+
+  if (isRealProvider) {
+    // Add processor to existing provider
+    const exporter = new ConsoleSpanExporter();
+    const processor = new BatchSpanProcessor(exporter, batchConfig);
+    (provider as any).addSpanProcessor(processor);
+
+    console.info(
+      `[Observability] Console exporter configured (batch=${batchConfig.maxExportBatchSize}, ` +
+        `delay=${batchConfig.scheduledDelayMillis}ms)`
+    );
+  } else {
+    // Create new provider with console exporter
+    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)`
+    );
+  }
+}
+
+/**
+ * Setup OTLP exporter.
+ */
+async function setupOTLPExporter(config: OTLPTraceConfig): Promise<void> {
+  const { trace } = await import('@opentelemetry/api');
+  const { resourceFromAttributes } = await import('@opentelemetry/resources');
+  const { NodeTracerProvider } = await import('@opentelemetry/sdk-trace-node');
+  const { OTLPTraceExporter } = await import('@opentelemetry/exporter-trace-otlp-http');
+  const { BatchSpanProcessor } = await import('@opentelemetry/sdk-trace-base');
+
+  const batchConfig = resolveBatchConfig(config.batch);
+
+  // Check if a real TracerProvider already exists
+  let provider = trace.getTracerProvider();
+  const isRealProvider = 'addSpanProcessor' in provider;
+
+  if (isRealProvider) {
+    // Add processor to existing provider
+    const exporter = new OTLPTraceExporter({
+      url: config.url,
+      headers: config.headers,
+      timeoutMillis: config.timeout ?? 10000,
+    });
+
+    const processor = new BatchSpanProcessor(exporter, batchConfig);
+    (provider as any).addSpanProcessor(processor);
+
+    console.info(
+      `[Observability] OTLP exporter configured (url=${config.url}, ` +
+        `batch=${batchConfig.maxExportBatchSize}, delay=${batchConfig.scheduledDelayMillis}ms)`
+    );
+  } else {
+    // Create new provider with OTLP exporter
+    const resource = resourceFromAttributes({
+      'service.name': process.env.OTEL_SERVICE_NAME || 'ag-ui-server',
+      'service.version': '1.0.0',
+    });
+
+    const exporter = new OTLPTraceExporter({
+      url: config.url,
+      headers: config.headers,
+      timeoutMillis: config.timeout ?? 10000,
+    });
+
+    const processor = new BatchSpanProcessor(exporter, batchConfig);
+
+    const tracerProvider = new NodeTracerProvider({
+      resource,
+      spanProcessors: [processor],
+    });
+
+    tracerProvider.register();
+
+    console.info(
+      `[Observability] OTLP exporter configured (url=${config.url}, ` +
+        `batch=${batchConfig.maxExportBatchSize}, delay=${batchConfig.scheduledDelayMillis}ms)`
+    );
+  }
+}
+
+/**
+ * Setup custom exporter.
+ */
+async function setupCustomExporter(config: CustomTraceConfig): Promise<void> {
+  await config.setup();
+  console.info(`[Observability] Custom exporter setup completed`);
+}
+
+/**
+ * Setup observability from merged configuration.
+ *
+ * @internal
+ */
+async function applyMergedConfigs(merged: MergedConfig): Promise<void> {
+  const setupTasks: Promise<void>[] = [];
+
+  // Apply console (non-blocking)
+  if (merged.console) {
+    setupTasks.push(safeSetup('Console exporter', () => setupConsoleExporter(merged.console!)));
+  }
+
+  // Apply otlp (non-blocking)
+  for (const otlp of merged.otlp) {
+    setupTasks.push(safeSetup(`OTLP exporter (${otlp.url})`, () => setupOTLPExporter(otlp)));
+  }
+
+  // Apply custom (non-blocking)
+  for (const custom of merged.custom) {
+    setupTasks.push(safeSetup('Custom exporter', () => setupCustomExporter(custom)));
+  }
+
+  // Wait for all exporters to complete (or fail gracefully)
+  await Promise.all(setupTasks);
+
+  if (merged.console || merged.otlp.length > 0 || merged.custom.length > 0) {
+    console.info(`[Observability] Setup completed`);
+  }
+}
+
+/**
+ * Setup observability from configuration.
+ *
+ * Merges environment variable (AUTO_TRACES_STDOUT) with parameter configs,
+ * then applies each exporter configuration.
+ *
+ * Environment variables act as presets, parameter configs override or extend.
+ *
+ * Returns a promise that resolves when setup is complete. This allows callers
+ * to await initialization before proceeding, eliminating race conditions.
+ *
+ * The returned promise is cached - subsequent calls return the same promise
+ * to avoid duplicate initialization.
+ *
+ * @param configs - Observability configuration(s)
+ *
+ * @example
+ * ```typescript
+ * // Console only (from env)
+ * await setupObservability();
+ *
+ * // Console + OTLP
+ * await setupObservability([
+ *   { type: 'console' },
+ *   { type: 'otlp', url: 'http://localhost:4318/v1/traces' }
+ * ]);
+ *
+ * // OTLP only
+ * await setupObservability({
+ *   type: 'otlp',
+ *   url: 'https://cloud.langfuse.com/api/public/otlp/v1/traces',
+ *   headers: { 'Authorization': 'Basic xxx' }
+ * });
+ * ```
+ *
+ * @public
+ */
+
+let setupPromise: Promise<void> | null = null;
+
+export async function setupObservability(
+  configs?: ObservabilityConfig | ObservabilityConfig[]
+): Promise<void> {
+  // Return cached promise if setup is in progress or completed
+  if (setupPromise) {
+    return setupPromise;
+  }
+
+  // Create the setup promise
+  setupPromise = (async () => {
+    try {
+      // Normalize to array
+      const configsArray = configs
+        ? Array.isArray(configs)
+          ? configs
+          : [configs]
+        : [];
+
+      // Merge env and parameter configs
+      const merged = mergeConfigs(configsArray);
+
+      // Apply merged configs
+      await applyMergedConfigs(merged);
+    } catch (error) {
+      // Reset promise on error to allow retry
+      setupPromise = null;
+      throw error;
+    }
+  })();
+
+  return setupPromise;
+}