langwatch 1.19.0 → 1.20.0

package/dist/observability-sdk/setup/node/index.d.ts

@@ -1,231 +1,112 @@
-import { L as Logger } from '../../../index-D7rKIGrO.js';
-import { Instrumentation } from '@opentelemetry/instrumentation';
-import { SpanExporter, SpanProcessor, SpanLimits, Sampler, IdGenerator } from '@opentelemetry/sdk-trace-base';
 import { TracerProvider, ContextManager, TextMapPropagator } from '@opentelemetry/api';
+import { Instrumentation } from '@opentelemetry/instrumentation';
+import { ResourceDetector, Resource } from '@opentelemetry/resources';
 import { LogRecordProcessor } from '@opentelemetry/sdk-logs';
 import { IMetricReader, ViewOptions } from '@opentelemetry/sdk-metrics';
-import { ResourceDetector, Resource } from '@opentelemetry/resources';
-import { a as SemConvAttributes } from '../../../types-VOZv9LYO.js';
-import { c as DataCaptureOptions } from '../../../types-DLfhJb38.js';
+import { SpanExporter, SpanProcessor, SpanLimits, Sampler, IdGenerator } from '@opentelemetry/sdk-trace-base';
+import { L as Logger } from '../../../index-D7rKIGrO.js';
+import { c as DataCaptureOptions } from '../../../types-RkiBQZ9j.js';
+import { a as SemConvAttributes } from '../../../types-CoS5PmeU.js';
 import '@opentelemetry/api-logs';
-import '@opentelemetry/semantic-conventions';
-import '@opentelemetry/semantic-conventions/incubating';
 
 /**
  * Configuration options for setting up LangWatch observability.
- *
- * This interface provides comprehensive configuration for initializing
- * LangWatch tracing with a familiar flat structure for main options
- * and grouped sections for debug and advanced configuration.
- *
- * @example
- * ```typescript
- * const options: SetupObservabilityOptions = {
- *   langwatch: {
- *     apiKey: "sk-lw-1234567890abcdef"
- *   },
- *   serviceName: "my-service",
- *   attributes: {
- *     "service.version": "1.0.0",
- *     "deployment.environment": "production"
- *   },
- *   spanProcessors: [new BatchSpanProcessor(new JaegerExporter())],
- *   debug: {
- *     consoleTracing: true,
- *     logLevel: 'debug'
- *   }
- * };
- * ```
+ * See the docs for example configuration and field-by-field details.
  */
 interface SetupObservabilityOptions {
     /**
-     * LangWatch configuration for sending observability data to LangWatch.
-     *
-     * Set to 'disabled' to completely disable LangWatch integration.
-     * API key and endpoint can also be set via LANGWATCH_API_KEY and
-     * LANGWATCH_ENDPOINT environment variables.
+     * LangWatch config for sending data; 'disabled' turns it off. apiKey/
+     * endpoint default from LANGWATCH_API_KEY / LANGWATCH_ENDPOINT.
      */
     langwatch?: {
         /**
          * LangWatch API key for authentication.
-         * Defaults to LANGWATCH_API_KEY environment variable.
-         *
-         * @example "sk-lw-1234567890abcdef"
          * @default LANGWATCH_API_KEY environment variable
          */
         apiKey?: string;
         /**
-         * LangWatch endpoint URL for sending traces and logs.
-         * Defaults to LANGWATCH_ENDPOINT environment variable or production endpoint.
-         *
-         * @default "https://app.langwatch.ai"
-         * @default LANGWATCH_ENDPOINT environment variable
+         * LangWatch endpoint for traces and logs.
+         * @default LANGWATCH_ENDPOINT env var, else "https://app.langwatch.ai"
          */
         endpoint?: string;
         /**
-         * Type of span processor to use for LangWatch exporter.
-         *
-         * - 'simple': Exports spans immediately (good for debugging)
-         * - 'batch': Batches spans for better performance (recommended for production)
-         *
+         * Span processor type: 'simple' exports immediately (debugging),
+         * 'batch' batches for throughput (recommended for production).
          * @default 'batch'
          */
         processorType?: "simple" | "batch";
     } | "disabled";
     /**
-     * Name of the service being instrumented.
-     * Used to identify your service in traces, logs, and metrics.
-     *
-     * @example "user-service"
+     * Name of the service being instrumented, for identification in
+     * traces, logs, and metrics.
      */
     serviceName?: string;
     /**
-     * Global attributes added to all telemetry data.
-     * Useful for adding service-level metadata like version, environment, etc.
-     *
-     * @example { "service.version": "1.0.0", "deployment.environment": "production" }
+     * Global attributes added to all telemetry data (e.g. service version,
+     * deployment environment).
      */
     attributes?: SemConvAttributes;
     /**
-     * Configuration for automatic data capture.
-     *
-     * This provides control over input/output data capture by LangWatch instrumentations.
-     * You can use a simple string mode, a configuration object, or a predicate function
-     * for dynamic control based on the operation context.
-     *
-     * @example
-     * ```typescript
-     * // Simple mode - capture everything
-     * dataCapture: "all"
-     *
-     * // Simple mode - capture only input data
-     * dataCapture: "input"
-     *
-     * // Simple mode - capture only output data
-     * dataCapture: "output"
-     *
-     * // Simple mode - capture nothing
-     * dataCapture: "none"
-     *
-     * // Configuration object
-     * dataCapture: {
-     *   mode: "all"
-     * }
-     *
-     * // Dynamic predicate function
-     * dataCapture: (context) => {
-     *   // Don't capture sensitive data in production
-     *   if (context.environment === "production" &&
-     *       context.operationName.includes("password")) {
-     *     return "none";
-     *   }
-     *   // Capture everything else
-     *   return "all";
-     * }
-     * ```
-     *
+     * Automatic input/output data capture: a mode string ("all" | "input" |
+     * "output" | "none"), a config object, or a context-based predicate.
      * @default "all"
      */
     dataCapture?: DataCaptureOptions;
     /**
-     * Dedicated TracerProvider for complete trace isolation from other OTel SDKs.
-     *
-     * When provided, LangWatch attaches its trace exporter to this provider
-     * and does NOT touch the global provider. Spans created through this
-     * provider's tracers go only to LangWatch. The other SDK keeps the
-     * global provider and never sees LLM traces.
-     *
-     * Pass any instrumentations you want on this provider via the
-     * `instrumentations` option — they will be registered against this
-     * provider instead of the global one.
-     *
-     * @remarks Trace-only mode. Log export (`logRecordProcessors`,
-     * `debug.consoleLogging`) is not supported when using a dedicated
-     * TracerProvider — use the default setup for full log+trace support.
-     *
-     * @example
-     * ```typescript
-     * import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
-     *
-     * const lwProvider = new NodeTracerProvider();
-     * setupObservability({
-     *   tracerProvider: lwProvider,
-     *   langwatch: { apiKey: "..." },
-     * });
-     *
-     * // Use lwProvider.getTracer() for LLM calls
-     * const tracer = lwProvider.getTracer("my-llm-service");
-     * ```
+     * Dedicated TracerProvider for isolation from other OTel SDKs: LangWatch
+     * attaches its exporter here without touching the global provider, so
+     * another SDK sharing the process never sees LLM traces (trace-only).
      */
     tracerProvider?: TracerProvider;
     /**
-     * Custom trace exporter for sending spans to external systems.
-     * If not provided, LangWatch will create its own exporter.
-     * This is a simpler alternative to spanProcessors for single exporter use cases.
-     *
-     * @example new OTLPTraceExporter({ url: "https://custom-collector.com/v1/traces" })
+     * Custom trace exporter for external systems; LangWatch creates its own
+     * if omitted. Simpler than spanProcessors for a single exporter.
      */
     traceExporter?: SpanExporter;
     /**
-     * Custom span processors for advanced trace processing.
-     * Use this when you need full control over batching, filtering, or
-     * custom processing logic.
-     *
-     * @example [new SimpleSpanProcessor(new LangWatchExporter())]
-     * @example [new BatchSpanProcessor(exporter, { maxExportBatchSize: 100 })]
+     * Custom span processors for full control over batching, filtering,
+     * or processing logic.
      */
     spanProcessors?: SpanProcessor[];
     /**
-     * Span limits configuration.
-     * Controls the maximum number of attributes, events, and links per span.
-     *
-     * @example { attributeCountLimit: 128, eventCountLimit: 128 }
+     * OTLP protocol this process exports spans with (default "http"). "grpc"
+     * refuses to start without a traceExporter or spanProcessors built from
+     * the optional peer `@opentelemetry/exporter-trace-otlp-grpc`.
+     */
+    otlpProtocol?: "http" | "grpc";
+    /**
+     * Span limits: max attributes, events, and links per span.
      */
     spanLimits?: SpanLimits;
     /**
      * Sampling strategy for controlling which traces to collect.
-     *
-     * @example new TraceIdRatioBasedSampler(0.1) // Sample 10% of traces
      */
     sampler?: Sampler;
     /**
      * Custom ID generator for span and trace IDs.
-     *
-     * @example new RandomIdGenerator()
      */
     idGenerator?: IdGenerator;
     /**
-     * Custom log record processors for advanced log processing.
-     * Use this when you need full control over batching, filtering, or
-     * custom processing logic.
-     *
-     * @example [new BatchLogRecordProcessor({ exporter, maxExportBatchSize: 100 })]
+     * Custom log record processors for full control over batching,
+     * filtering, or processing logic.
      */
     logRecordProcessors?: LogRecordProcessor[];
     /**
      * Custom metric reader for collecting and exporting metrics.
-     *
-     * @example new PeriodicExportingMetricReader({ exporter: new PrometheusExporter() })
      */
     metricReader?: IMetricReader;
     /**
-     * Metric views for controlling aggregation and filtering.
-     * Views determine which metrics are collected and how they are processed.
-     *
-     * @example [{ instrumentName: 'http.server.duration', aggregation: Aggregation.Histogram() }]
+     * Metric views: control which metrics are collected and how they're
+     * aggregated/filtered.
      */
     views?: ViewOptions[];
     /**
-     * Auto-instrumentation libraries to enable.
-     * These automatically capture telemetry from common libraries and frameworks.
-     *
-     * @example [new HttpInstrumentation(), new ExpressInstrumentation()]
+     * Auto-instrumentation libraries to enable, capturing telemetry from
+     * common libraries and frameworks.
      */
     instrumentations?: (Instrumentation | Instrumentation[])[];
     /**
-     * Whether to automatically detect and configure resource attributes.
-     * When enabled, OpenTelemetry automatically detects host, process, and environment info.
-     *
+     * Auto-detect resource attributes (host, process, environment info).
      * @default true
      */
     autoDetectResources?: boolean;
@@ -234,24 +115,18 @@ interface SetupObservabilityOptions {
      */
     contextManager?: ContextManager;
     /**
-     * Text map propagator for trace context propagation across service boundaries.
-     * Controls how trace context is serialized in HTTP headers and other carriers.
-     *
-     * @example new W3CTraceContextPropagator()
+     * Text map propagator: controls how trace context is serialized in
+     * HTTP headers and other carriers across service boundaries.
      */
     textMapPropagator?: TextMapPropagator;
     /**
-     * Resource detectors for automatic resource attribute detection.
-     * These detect information about the runtime environment.
-     *
-     * @example [envDetector, processDetector, hostDetector]
+     * Resource detectors for automatic detection of runtime environment
+     * attributes.
      */
-    resourceDetectors?: Array<ResourceDetector>;
+    resourceDetectors?: ResourceDetector[];
     /**
-     * Custom resource configuration representing the entity being monitored.
-     * Includes service, host, and deployment metadata.
-     *
-     * @example new Resource({ "service.name": "my-service", "service.version": "1.0.0" })
+     * Custom resource configuration for the entity being monitored
+     * (service, host, deployment metadata).
      */
     resource?: Resource;
     /**
@@ -260,25 +135,17 @@ interface SetupObservabilityOptions {
      */
     debug?: {
         /**
-         * Enable console output for traces (debugging).
-         * When true, spans will be logged to the console in addition
-         * to any other configured exporters.
-         *
+         * Log spans to the console in addition to configured exporters.
          * @default false
          */
         consoleTracing?: boolean;
         /**
-         * Enable console output for logs (debugging).
-         * When true, log records will be logged to the console in addition
-         * to any other configured exporters.
-         *
+         * Log records to the console in addition to configured exporters.
          * @default false
          */
         consoleLogging?: boolean;
         /**
-         * Log level for LangWatch SDK internal logging.
-         * Controls verbosity of SDK diagnostic messages.
-         *
+         * Log level for LangWatch SDK internal diagnostic messages.
          * @default 'warn'
          */
         logLevel?: "debug" | "info" | "warn" | "error";
@@ -294,175 +161,68 @@ interface SetupObservabilityOptions {
      */
     advanced?: {
         /**
-         * Whether to throw errors during setup or return no-op handles.
-         *
-         * When false (default), setup errors are logged but the function
-         * returns no-op handles to prevent breaking your application.
-         * When true, setup errors will be thrown.
-         *
+         * Throw during setup instead of returning no-op handles; false means
+         * a setup failure is logged but never breaks your application.
          * @default false
          */
         throwOnSetupError?: boolean;
         /**
-         * Skip OpenTelemetry setup entirely and return no-op handles.
-         * Useful when you want to handle OpenTelemetry setup yourself.
-         *
+         * Skip OpenTelemetry setup and return no-op handles, for when you
+         * set up OpenTelemetry yourself.
          * @default false
          */
         skipOpenTelemetrySetup?: boolean;
         /**
-         * Force reinitialization of OpenTelemetry even if already set up.
-         *
-         * WARNING: This can cause conflicts and is primarily intended for testing.
-         * Use with extreme caution in production.
-         *
+         * Force OpenTelemetry reinitialization even if already set up.
+         * WARNING: can cause conflicts; testing only, avoid in production.
          * @default false
          */
         UNSAFE_forceOpenTelemetryReinitialization?: boolean;
         /**
          * Attach LangWatch processors to an existing global TracerProvider
-         * instead of returning a no-op when another OTel-based SDK has already
-         * initialized.
-         *
-         * Use this when running LangWatch alongside another OTel-based SDK.
-         * LangWatch will add its span processors to the
-         * existing provider so both SDKs receive spans. Combine with
-         * LangWatchTraceExporter filter options to scope LangWatch to only
-         * LLM-related spans.
-         *
+         * instead of no-op'ing when another OTel SDK already initialized one.
          * @default false
          */
         attachToExistingProvider?: boolean;
         /**
-         * Disable all observability setup and return no-op handles.
-         *
-         * When true, no OpenTelemetry setup will occur and all operations
-         * will be no-ops. Useful for testing or when you want to completely
-         * disable observability without changing your code.
-         *
+         * Disable all observability setup and return no-op handles, for
+         * testing or disabling without code changes.
          * @default false
          */
         disabled?: boolean;
         /**
-         * Disable the automatic shutdown of the observability system when the application
-         * terminates.
-         *
-         * When enabled (default), the SDK registers handlers for `beforeExit` (event loop
-         * drains), `SIGINT` (Ctrl+C), and `SIGTERM` (external kill / Docker stop) to flush
-         * pending traces before the process exits.
-         *
-         * The SDK never terminates your process. Node runs every listener registered for a
-         * signal, so once the flush is done the SDK stands aside and lets your own shutdown
-         * logic decide when the process ends. The one exception keeps one-shot scripts
-         * working: if the SDK's handler turns out to be the only listener for that signal,
-         * it removes itself and re-raises the signal, so the process ends on the signal
-         * exactly as it would have if the SDK were not installed.
-         *
-         * Note: `process.exit()` calls (e.g. from test runners like vitest) bypass these
-         * handlers. In those environments, call `shutdown()` explicitly in your teardown.
-         *
-         * @default false
+         * Disable auto shutdown on `beforeExit`/`SIGINT`/`SIGTERM` (off by
+         * default). The SDK flushes then stands aside, re-raising the signal
+         * only if it was the sole listener; `process.exit()` bypasses this.
          */
         disableAutoShutdown?: boolean;
         /**
-         * Exit the process with status 0 as soon as the automatic shutdown has flushed.
-         *
-         * WARNING: this terminates your application from inside the observability SDK. Any
-         * other `SIGINT` / `SIGTERM` listener that has not finished — a queue drain, in-flight
-         * database writes, connection teardown — is cut off mid-flight, and the process
-         * reports success even though it was signalled. This is what the SDK used to do
-         * unconditionally; the option exists only so an application that depended on it can
-         * keep the old behaviour while it moves the exit into its own signal handler, where
-         * it belongs.
-         *
-         * Leave this off unless your process now fails to exit on a signal, which happens
-         * only when you register a signal handler of your own that never terminates the
-         * process. Ignored when `disableAutoShutdown` is set.
-         *
-         * @default false
+         * Exit with status 0 once shutdown flushes (off by default). WARNING:
+         * cuts off any other in-flight signal listener and reports success
+         * regardless; ignored when `disableAutoShutdown` is set.
          */
         UNSAFE_exitProcessAfterAutoShutdown?: boolean;
     };
 }
 /**
- * Handle returned from observability setup. If you disable the automatic shutdown,
- * or are running in an environment where process signals are not available (e.g.
- * test runners that call `process.exit()`), you can use the shutdown function to
- * manually shut down the observability system and ensure that no data is lost.
- *
- * @example
- * ```typescript
- * const { shutdown } = setupObservability({
- *   advanced: { disableAutoShutdown: true }
- * });
- *
- * // Manual shutdown in test teardown
- * afterAll(async () => {
- *   await shutdown();
- * });
- * ```
+ * Handle returned from observability setup. Call `shutdown` yourself when
+ * automatic shutdown is disabled, or signals aren't available (e.g. test
+ * runners that call `process.exit()`).
  */
 interface ObservabilityHandle {
     /**
-     * Gracefully shuts down the observability system.
-     *
-     * This method should be called when the application is terminating
-     * to ensure all pending traces are exported before shutdown.
-     *
-     * The shutdown process:
-     * 1. Flushes any pending traces to the exporter
-     * 2. Closes the trace exporter
-     * 3. Shuts down the tracer provider
-     * 4. Cleans up any registered instrumentations
-     *
+     * Gracefully shuts down: flushes pending traces, closes the exporter,
+     * and cleans up instrumentations. Call when the application terminates.
      * @returns Promise that resolves when shutdown is complete
-     *
-     * @example
-     * ```typescript
-     * // Graceful shutdown
-     * process.on('SIGTERM', async () => {
-     *   console.log('Shutting down observability...');
-     *   await shutdown();
-     *   console.log('Observability shutdown complete');
-     *   process.exit(0);
-     * });
-     *
-     * // Force shutdown with timeout
-     * process.on('SIGINT', async () => {
-     *   console.log('Force shutdown...');
-     *   await Promise.race([
-     *     shutdown(),
-     *     new Promise(resolve => setTimeout(resolve, 5000))
-     *   ]);
-     *   process.exit(1);
-     * });
-     * ```
      */
     shutdown: () => Promise<void>;
 }
 
 declare function setupObservability(options?: SetupObservabilityOptions): ObservabilityHandle;
 /**
- * Ensure observability is set up, but only if not already configured.
- *
- * This is an idempotent function that:
- * - Does nothing if OpenTelemetry is already configured (by you or another library)
- * - Sets up LangWatch observability if no tracer provider exists
- * - Does nothing if LANGWATCH_API_KEY is not set
- *
- * This is useful for libraries/SDKs that want to ensure tracing is available
- * without conflicting with user's existing observability setup.
- *
- * @example
- * ```typescript
- * import { ensureSetup } from "langwatch/observability/node";
- *
- * // Safe to call - won't conflict with existing setup
- * ensureSetup();
- *
- * // Now you can use tracing
- * const tracer = trace.getTracer("my-app");
- * ```
+ * Ensures observability is set up, only if not already configured:
+ * idempotent, sets up a tracer provider if none exists, does nothing if
+ * LANGWATCH_API_KEY is unset.
  */
 declare const ensureSetup: () => ObservabilityHandle;
 

package/dist/observability-sdk/setup/node/index.js

@@ -1,11 +1,13 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true});
 
 
-var _chunkWGLVIV4Jjs = require('../../../chunk-WGLVIV4J.js');
-require('../../../chunk-CSV7B7B5.js');
-require('../../../chunk-LCG5Y2EG.js');
+var _chunkEQ5CFQGJjs = require('../../../chunk-EQ5CFQGJ.js');
+require('../../../chunk-HCK7TCSK.js');
+require('../../../chunk-BL3GHEKF.js');
+require('../../../chunk-5VYEG3RS.js');
+require('../../../chunk-N76BG37W.js');
 
 
 
-exports.ensureSetup = _chunkWGLVIV4Jjs.ensureSetup; exports.setupObservability = _chunkWGLVIV4Jjs.setupObservability;
+exports.ensureSetup = _chunkEQ5CFQGJjs.ensureSetup; exports.setupObservability = _chunkEQ5CFQGJjs.setupObservability;
 //# sourceMappingURL=index.js.map

package/dist/observability-sdk/setup/node/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["/home/runner/work/langwatch/langwatch/sdks/typescript/dist/observability-sdk/setup/node/index.js"],"names":[],"mappings":"AAAA;AACE;AACA;AACF,6DAAmC;AACnC,sCAAmC;AACnC,sCAAmC;AACnC;AACE;AACA;AACF,qHAAC","file":"/home/runner/work/langwatch/langwatch/sdks/typescript/dist/observability-sdk/setup/node/index.js"}
+{"version":3,"sources":["/home/runner/work/langwatch/langwatch/sdks/typescript/dist/observability-sdk/setup/node/index.js"],"names":[],"mappings":"AAAA;AACE;AACA;AACF,6DAAmC;AACnC,sCAAmC;AACnC,sCAAmC;AACnC,sCAAmC;AACnC,sCAAmC;AACnC;AACE;AACA;AACF,qHAAC","file":"/home/runner/work/langwatch/langwatch/sdks/typescript/dist/observability-sdk/setup/node/index.js"}

package/dist/observability-sdk/setup/node/index.mjs

@@ -1,9 +1,11 @@
 import {
   ensureSetup,
   setupObservability
-} from "../../../chunk-PIYOJF6V.mjs";
-import "../../../chunk-SY5HSL5G.mjs";
-import "../../../chunk-WMDQVWA6.mjs";
+} from "../../../chunk-BDQ2RG7R.mjs";
+import "../../../chunk-FKYYEGJ7.mjs";
+import "../../../chunk-C7IWJ2GJ.mjs";
+import "../../../chunk-SERULD4Z.mjs";
+import "../../../chunk-WSGVZ3J2.mjs";
 export {
   ensureSetup,
   setupObservability