@cloudbase/agent-observability 1.0.1-alpha.9

package/dist/server.d.mts

@@ -0,0 +1,163 @@
+/**
+ * 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
+ */
+declare const ExporterType: {
+    /** Console exporter - outputs traces to stdout */
+    readonly Console: "console";
+    /** OTLP exporter - sends traces to OTLP-compatible backend */
+    readonly OTLP: "otlp";
+    /** Custom exporter - user-defined setup logic */
+    readonly Custom: "custom";
+};
+/**
+ * Trace exporter type literal values.
+ *
+ * @public
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+type ObservabilityConfig = ConsoleTraceConfig | OTLPTraceConfig | CustomTraceConfig;
+
+/**
+ * Observability setup implementation for AG-Kit Server.
+ *
+ * Merges configuration from environment variables and parameters,
+ * then applies each exporter configuration.
+ *
+ * @packageDocumentation
+ */
+
+declare function setupObservability(configs?: ObservabilityConfig | ObservabilityConfig[]): Promise<void>;
+
+export { type BatchConfig, type ConsoleTraceConfig, type CustomTraceConfig, ExporterType, type OTLPTraceConfig, type ObservabilityConfig, setupObservability };

package/dist/server.d.ts

@@ -0,0 +1,163 @@
+/**
+ * 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
+ */
+declare const ExporterType: {
+    /** Console exporter - outputs traces to stdout */
+    readonly Console: "console";
+    /** OTLP exporter - sends traces to OTLP-compatible backend */
+    readonly OTLP: "otlp";
+    /** Custom exporter - user-defined setup logic */
+    readonly Custom: "custom";
+};
+/**
+ * Trace exporter type literal values.
+ *
+ * @public
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+type ObservabilityConfig = ConsoleTraceConfig | OTLPTraceConfig | CustomTraceConfig;
+
+/**
+ * Observability setup implementation for AG-Kit Server.
+ *
+ * Merges configuration from environment variables and parameters,
+ * then applies each exporter configuration.
+ *
+ * @packageDocumentation
+ */
+
+declare function setupObservability(configs?: ObservabilityConfig | ObservabilityConfig[]): Promise<void>;
+
+export { type BatchConfig, type ConsoleTraceConfig, type CustomTraceConfig, ExporterType, type OTLPTraceConfig, type ObservabilityConfig, setupObservability };