langwatch 0.1.7 → 0.3.0-prerelease.1

package/src/observability/processors/filterable-batch-span-processor.ts

@@ -0,0 +1,99 @@
+/**
+ * Filterable Batch Span Exporter for OpenTelemetry
+ *
+ * This module provides a BatchSpanProcessor subclass that allows filtering of spans before export
+ * based on configurable rules. Spans matching any exclude rule are dropped and not exported.
+ *
+ * @module filterable-batch-span-exporter
+ */
+
+import {
+  BatchSpanProcessor,
+  ReadableSpan,
+  SpanExporter,
+} from '@opentelemetry/sdk-trace-base';
+
+/**
+ * A rule for excluding spans from export based on their name or instrumentation scope name.
+ *
+ * @property fieldName - The span field to match against ('span_name' or 'instrumentation_scope_name').
+ * @property matchValue - The value to match against the field.
+ * @property matchOperation - The operation to use for matching ('includes', 'exact_match', 'starts_with', 'ends_with').
+ *
+ * @example
+ * const rule: SpanProcessingExcludeRule = {
+ *   fieldName: 'span_name',
+ *   matchValue: 'heartbeat',
+ *   matchOperation: 'exact_match',
+ * };
+ */
+export interface SpanProcessingExcludeRule {
+  fieldName: "span_name" | "instrumentation_scope_name";
+  matchValue: string;
+  matchOperation: "includes" | "exact_match" | "starts_with" | "ends_with";
+}
+
+/**
+ * A BatchSpanProcessor that filters out spans matching any of the provided exclude rules before export.
+ *
+ * This is useful for dropping noisy or irrelevant spans (e.g., health checks, heartbeats) from being exported to your tracing backend.
+ *
+ * @example
+ * import { FilterableBatchSpanProcessor } from './filterable-batch-span-exporter';
+ * import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+ *
+ * const exporter = new OTLPTraceExporter({ url: '...' });
+ * const filters = [
+ *   { fieldName: 'span_name', matchValue: 'heartbeat', matchOperation: 'exact_match' },
+ *   { fieldName: 'instrumentation_scope_name', matchValue: 'internal', matchOperation: 'starts_with' },
+ * ];
+ * provider.addSpanProcessor(new FilterableBatchSpanProcessor(exporter, filters));
+ */
+export class FilterableBatchSpanProcessor extends BatchSpanProcessor {
+  private readonly _filters: SpanProcessingExcludeRule[];
+
+  /**
+   * Create a new FilterableBatchSpanProcessor.
+   *
+   * @param exporter - The underlying SpanExporter to use for exporting spans.
+   * @param filters - An array of rules for excluding spans from export.
+   */
+  constructor(exporter: SpanExporter, filters: SpanProcessingExcludeRule[]) {
+    super(exporter);
+    this._filters = filters;
+  }
+
+  /**
+   * Called when a span ends. If the span matches any exclude rule, it is dropped and not exported.
+   *
+   * @param span - The ReadableSpan that has ended.
+   */
+  override onEnd(span: ReadableSpan): void {
+    for (const filter of this._filters) {
+      let sourceValue: string;
+
+      if (filter.fieldName === "span_name") {
+        sourceValue = span.name;
+      } else if (filter.fieldName === "instrumentation_scope_name") {
+        sourceValue = span.instrumentationScope.name;
+      } else {
+        continue;
+      }
+
+      const matchValue = filter.matchValue;
+      const matchOperation = filter.matchOperation;
+
+      switch (true) {
+        case matchOperation === "exact_match" && sourceValue === matchValue:
+        case matchOperation === "includes" && sourceValue.includes(matchValue):
+        case matchOperation === "starts_with" && sourceValue.startsWith(matchValue):
+        case matchOperation === "ends_with" && sourceValue.endsWith(matchValue):
+          return;
+
+        default: break;
+      }
+    }
+
+    super.onEnd(span);
+  }
+}

package/src/observability/processors/index.ts

@@ -0,0 +1 @@
+export * from "./filterable-batch-span-processor";

package/src/observability/semconv/attributes.ts

@@ -0,0 +1,185 @@
+/*
+  This file contains the semantic conventions for attributes either owned by LangWatch, or
+  which are no yet part of the OpenTelemetry semantic conventions for Gen AI.
+
+  Any that are not yet part of the OpenTelemetry semantic conventions for Gen AI are
+  marked with an UNSTABLE_ prefix.
+*/
+
+/**
+ * LangWatch input data attribute key
+ * Used to store the input data for a span or event
+ */
+export const ATTR_LANGWATCH_INPUT = "langwatch.input";
+
+/**
+ * LangWatch output data attribute key
+ * Used to store the output data for a span or event
+ */
+export const ATTR_LANGWATCH_OUTPUT = "langwatch.output";
+
+/**
+ * LangWatch span type attribute key
+ * Used to identify the type of span being traced
+ */
+export const ATTR_LANGWATCH_SPAN_TYPE = "langwatch.span.type";
+
+/**
+ * LangWatch RAG contexts attribute key
+ * Used to store retrieval-augmented generation contexts
+ */
+export const ATTR_LANGWATCH_RAG_CONTEXTS = "langwatch.contexts";
+
+/**
+ * LangWatch metrics attribute key
+ * Used to store custom metrics data
+ */
+export const ATTR_LANGWATCH_METRICS = "langwatch.metrics";
+
+/**
+ * LangWatch SDK version attribute key
+ * Used to track the version of the LangWatch SDK being used
+ */
+export const ATTR_LANGWATCH_SDK_VERSION = "langwatch.sdk.version";
+
+/**
+ * LangWatch SDK name attribute key
+ * Used to identify the LangWatch SDK implementation
+ */
+export const ATTR_LANGWATCH_SDK_NAME = "langwatch.sdk.name";
+
+/**
+ * LangWatch SDK language attribute key
+ * Used to identify the programming language of the SDK
+ */
+export const ATTR_LANGWATCH_SDK_LANGUAGE = "langwatch.sdk.language";
+
+/**
+ * LangWatch timestamps attribute key
+ * Used to store timing information for events
+ */
+export const ATTR_LANGWATCH_TIMESTAMPS = "langwatch.timestamps";
+
+/**
+ * LangWatch custom evaluation attribute key
+ * Used to store custom evaluation data
+ */
+export const ATTR_LANGWATCH_EVALUATION_CUSTOM = "langwatch.evaluation.custom";
+
+/**
+ * LangWatch parameters attribute key
+ * Used to store parameter data for operations
+ */
+export const ATTR_LANGWATCH_PARAMS = "langwatch.params";
+
+/**
+ * LangWatch customer ID attribute key
+ * Used to identify the customer associated with the trace
+ */
+export const ATTR_LANGWATCH_CUSTOMER_ID = "langwatch.customer.id";
+
+/**
+ * LangWatch thread ID attribute key
+ * Used to group related operations within a conversation thread
+ */
+export const ATTR_LANGWATCH_THREAD_ID = "langwatch.thread.id";
+
+/**
+ * LangWatch streaming attribute key
+ * Used to indicate if the operation involves streaming
+ */
+export const ATTR_LANGWATCH_STREAMING = "langwatch.gen_ai.streaming";
+
+/**
+ * LangWatch prompt ID attribute key
+ * Used to identify the specific prompt being used
+ */
+export const ATTR_LANGWATCH_PROMPT_ID = "langwatch.prompt.id";
+
+/**
+ * LangWatch prompt version ID attribute key
+ * Used to identify the specific version of a prompt
+ */
+export const ATTR_LANGWATCH_PROMPT_VERSION_ID = "langwatch.prompt.version.id";
+
+/**
+ * LangWatch prompt variables attribute key
+ * Used to store variables used in prompt templates
+ */
+export const ATTR_LANGWATCH_PROMPT_VARIABLES = "langwatch.prompt.variables";
+
+/**
+ * LangWatch prompt selected ID attribute key
+ * Used to identify which prompt was selected from a set
+ */
+export const ATTR_LANGWATCH_PROMPT_SELECTED_ID = "langwatch.prompt.selected.id";
+
+/**
+ * LangWatch prompt version number attribute key
+ * Used to track the version number of a prompt
+ */
+export const ATTR_LANGWATCH_PROMPT_VERSION_NUMBER =
+  "langwatch.prompt.version.number";
+
+/**
+ * LangWatch gen AI log event imposter attribute key
+ * Used to identify imposter events in log records
+ */
+export const ATTR_LANGWATCH_GEN_AI_LOG_EVENT_IMPOSTER =
+  "langwatch.gen_ai.log_event.imposter";
+
+/**
+ * LangWatch gen AI log event body attribute key
+ * Used to store the body content of log events
+ */
+export const ATTR_LANGWATCH_GEN_AI_LOG_EVENT_BODY =
+  "langwatch.gen_ai.log_event.body";
+
+/**
+ * LangWatch LangChain tags attribute key
+ * Used to store tags associated with LangChain operations
+ */
+export const ATTR_LANGWATCH_LANGCHAIN_TAGS = "langwatch.langchain.tags";
+
+/**
+ * LangWatch LangChain event name attribute key
+ * Used to identify the specific LangChain event type
+ */
+export const ATTR_LANGWATCH_LANGCHAIN_EVENT_NAME = "langwatch.langchain.event_name";
+
+/**
+ * LangWatch LangChain run ID attribute key
+ * Used to identify a specific LangChain run
+ */
+export const ATTR_LANGWATCH_LANGCHAIN_RUN_ID = "langwatch.langchain.run.id";
+
+/**
+ * LangWatch LangChain run tags attribute key
+ * Used to store tags associated with a LangChain run
+ */
+export const ATTR_LANGWATCH_LANGCHAIN_RUN_TAGS = "langwatch.langchain.run.tags";
+
+/**
+ * LangWatch LangChain run type attribute key
+ * Used to identify the type of LangChain run
+ */
+export const ATTR_LANGWATCH_LANGCHAIN_RUN_TYPE = "langwatch.langchain.run.type";
+
+/**
+ * LangWatch LangChain run metadata attribute key
+ * Used to store metadata associated with a LangChain run
+ */
+export const ATTR_LANGWATCH_LANGCHAIN_RUN_METADATA = "langwatch.langchain.run.metadata";
+
+/**
+ * LangWatch LangChain run extra parameters attribute key
+ * Used to store additional parameters for a LangChain run
+ */
+export const ATTR_LANGWATCH_LANGCHAIN_RUN_EXTRA_PARAMS = "langwatch.langchain.run.extra_params";
+
+/**
+ * LangWatch LangChain run parent ID attribute key
+ * Used to identify the parent run in a hierarchical structure
+ */
+export const ATTR_LANGWATCH_LANGCHAIN_RUN_PARENT_ID =
+  "langwatch.langchain.run.parent.id";

package/src/observability/semconv/events.ts

@@ -0,0 +1,42 @@
+/*
+  This file contains the values for the OpenTelemetry semantic conventions for GenAI log
+  record event names.
+
+  👉 https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-events/
+*/
+
+/**
+ * GenAI system message event name
+ * Used for log records representing system messages in AI conversations
+ */
+export const LOG_EVNT_GEN_AI_SYSTEM_MESSAGE = "gen.ai.system_message";
+
+/**
+ * GenAI user message event name
+ * Used for log records representing user messages in AI conversations
+ */
+export const LOG_EVNT_GEN_AI_USER_MESSAGE = "gen.ai.user_message";
+
+/**
+ * GenAI assistant message event name
+ * Used for log records representing assistant responses in AI conversations
+ */
+export const LOG_EVNT_GEN_AI_ASSISTANT_MESSAGE = "gen.ai.assistant_message";
+
+/**
+ * GenAI tool message event name
+ * Used for log records representing tool calls or responses in AI conversations
+ */
+export const LOG_EVNT_GEN_AI_TOOL_MESSAGE = "gen.ai.tool_message";
+
+/**
+ * GenAI choice event name
+ * Used for log records representing choices made by AI models
+ */
+export const LOG_EVNT_GEN_AI_CHOICE = "gen.ai.choice";
+
+/**
+ * LangWatch LangChain callback event name
+ * Used for log records representing LangChain callback events
+ */
+export const EVNT_LANGWATCH_LANGCHAIN_CALLBACK = "langwatch.langchain.callback";

package/src/observability/semconv/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Semantic conventions module for LangWatch observability
+ *
+ * This module exports all semantic convention constants used for:
+ * - Attributes: Key-value pairs for span and event metadata
+ * - Values: Predefined values for semantic convention attributes
+ * - Events: Event names for log records and traces
+ *
+ * @see {@link ./attributes} for attribute constants
+ * @see {@link ./values} for value constants
+ * @see {@link ./events} for event constants
+ */
+
+export * from "./attributes";
+export * from "./values";
+export * from "./events";

package/src/observability/semconv/values.ts

@@ -0,0 +1,159 @@
+/*
+  This file contains the values for the OpenTelemetry semantic conventions for Gen AI,
+  some of which are still in development and therefor currently considered to be
+  experimental.
+
+  👉 https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-events/
+*/
+
+/**
+ * Anthropic AI system identifier
+ * Used to identify Anthropic's Claude models
+ */
+export const VAL_GEN_AI_SYSTEM_ANTHROPIC = "anthropic";
+
+/**
+ * AWS Bedrock system identifier
+ * Used to identify AWS Bedrock AI services
+ */
+export const VAL_GEN_AI_SYSTEM_AWS_BEDROCK = "aws.bedrock";
+
+/**
+ * Azure AI Inference system identifier
+ * Used to identify Azure AI Inference services
+ */
+export const VAL_GEN_AI_SYSTEM_AZURE_AI_INFERENCE = "azure.ai.inference";
+
+/**
+ * Azure AI OpenAI system identifier
+ * Used to identify Azure OpenAI services
+ */
+export const VAL_GEN_AI_SYSTEM_AZURE_AI_OPENAI = "azure.ai.openai";
+
+/**
+ * Cohere system identifier
+ * Used to identify Cohere AI models
+ */
+export const VAL_GEN_AI_SYSTEM_COHERE = "cohere";
+
+/**
+ * DeepSeek system identifier
+ * Used to identify DeepSeek AI models
+ */
+export const VAL_GEN_AI_SYSTEM_DEEPSEEK = "deepseek";
+
+/**
+ * GCP Gemini system identifier
+ * Used to identify Google Cloud Gemini models
+ */
+export const VAL_GEN_AI_SYSTEM_GCP_GEMINI = "gcp.gemini";
+
+/**
+ * GCP Gen AI system identifier
+ * Used to identify Google Cloud Generative AI services
+ */
+export const VAL_GEN_AI_SYSTEM_GCP_GEN_AI = "gcp.gen_ai";
+
+/**
+ * GCP Vertex AI system identifier
+ * Used to identify Google Cloud Vertex AI services
+ */
+export const VAL_GEN_AI_SYSTEM_GCP_VERTEX_AI = "gcp.vertex_ai";
+
+/**
+ * Groq system identifier
+ * Used to identify Groq AI models
+ */
+export const VAL_GEN_AI_SYSTEM_GROQ = "groq";
+
+/**
+ * IBM WatsonX AI system identifier
+ * Used to identify IBM WatsonX AI services
+ */
+export const VAL_GEN_AI_SYSTEM_IBM_WATSONX_AI = "ibm.watsonx.ai";
+
+/**
+ * Mistral AI system identifier
+ * Used to identify Mistral AI models
+ */
+export const VAL_GEN_AI_SYSTEM_MISTRAL_AI = "mistral_ai";
+
+/**
+ * OpenAI system identifier
+ * Used to identify OpenAI models and services
+ */
+export const VAL_GEN_AI_SYSTEM_OPENAI = "openai";
+
+/**
+ * Perplexity system identifier
+ * Used to identify Perplexity AI models
+ */
+export const VAL_GEN_AI_SYSTEM_PERPLEXITY = "perplexity";
+
+/**
+ * XAI system identifier
+ * Used to identify XAI models and services
+ */
+export const VAL_GEN_AI_SYSTEM_XAI = "xai";
+
+/**
+ * Content filter finish reason
+ * Used when generation stops due to content filtering
+ */
+export const VAL_GEN_AI_FINISH_REASON_CONTENT_FILTER = "content_filter";
+
+/**
+ * Error finish reason
+ * Used when generation stops due to an error
+ */
+export const VAL_GEN_AI_FINISH_REASON_ERROR = "error";
+
+/**
+ * Length finish reason
+ * Used when generation stops due to length limits
+ */
+export const VAL_GEN_AI_FINISH_REASON_LENGTH = "length";
+
+/**
+ * Stop finish reason
+ * Used when generation stops due to stop tokens
+ */
+export const VAL_GEN_AI_FINISH_REASON_STOP = "stop";
+
+/**
+ * Tool calls finish reason
+ * Used when generation stops due to tool calls
+ */
+export const VAL_GEN_AI_FINISH_REASON_TOOL_CALLS = "tool_calls";
+
+/**
+ * Union type of all supported GenAI system identifiers
+ * Used for type safety when working with system identification
+ */
+export type VAL_GEN_AI_SYSTEMS =
+  | typeof VAL_GEN_AI_SYSTEM_ANTHROPIC
+  | typeof VAL_GEN_AI_SYSTEM_AWS_BEDROCK
+  | typeof VAL_GEN_AI_SYSTEM_AZURE_AI_INFERENCE
+  | typeof VAL_GEN_AI_SYSTEM_AZURE_AI_OPENAI
+  | typeof VAL_GEN_AI_SYSTEM_COHERE
+  | typeof VAL_GEN_AI_SYSTEM_DEEPSEEK
+  | typeof VAL_GEN_AI_SYSTEM_GCP_GEMINI
+  | typeof VAL_GEN_AI_SYSTEM_GCP_GEN_AI
+  | typeof VAL_GEN_AI_SYSTEM_GCP_VERTEX_AI
+  | typeof VAL_GEN_AI_SYSTEM_GROQ
+  | typeof VAL_GEN_AI_SYSTEM_IBM_WATSONX_AI
+  | typeof VAL_GEN_AI_SYSTEM_MISTRAL_AI
+  | typeof VAL_GEN_AI_SYSTEM_OPENAI
+  | typeof VAL_GEN_AI_SYSTEM_PERPLEXITY
+  | typeof VAL_GEN_AI_SYSTEM_XAI;
+
+/**
+ * Union type of all supported GenAI finish reasons
+ * Used for type safety when working with generation completion reasons
+ */
+export type VAL_GEN_AI_FINISH_REASONS =
+  | typeof VAL_GEN_AI_FINISH_REASON_CONTENT_FILTER
+  | typeof VAL_GEN_AI_FINISH_REASON_ERROR
+  | typeof VAL_GEN_AI_FINISH_REASON_LENGTH
+  | typeof VAL_GEN_AI_FINISH_REASON_STOP
+  | typeof VAL_GEN_AI_FINISH_REASON_TOOL_CALLS;