@langfuse/tracing 4.0.0-beta.8 → 4.0.0-beta.9

package/dist/index.d.cts

@@ -1598,15 +1598,164 @@ declare function startActiveObservation<F extends (span: LangfuseSpan) => unknow
  * @public
  */
 declare function updateActiveTrace(attributes: LangfuseTraceAttributes): void;
-declare function updateActiveObservation(currentType: "span", attributes: LangfuseSpanAttributes): void;
-declare function updateActiveObservation(currentType: "generation", attributes: LangfuseGenerationAttributes): void;
-declare function updateActiveObservation(currentType: "agent", attributes: LangfuseAgentAttributes): void;
-declare function updateActiveObservation(currentType: "tool", attributes: LangfuseToolAttributes): void;
-declare function updateActiveObservation(currentType: "chain", attributes: LangfuseChainAttributes): void;
-declare function updateActiveObservation(currentType: "embedding", attributes: LangfuseEmbeddingAttributes): void;
-declare function updateActiveObservation(currentType: "evaluator", attributes: LangfuseEvaluatorAttributes): void;
-declare function updateActiveObservation(currentType: "guardrail", attributes: LangfuseGuardrailAttributes): void;
-declare function updateActiveObservation(currentType: "retriever", attributes: LangfuseRetrieverAttributes): void;
+/**
+ * Updates the currently active observation with new attributes.
+ *
+ * This function finds the currently active OpenTelemetry span in the execution context
+ * and updates it with Langfuse-specific attributes. It supports all observation types
+ * through TypeScript overloads, providing type safety for attributes based on the
+ * specified `asType` parameter. If no active span exists, the update is skipped with a warning.
+ *
+ * ## Type Safety
+ * - Automatic type inference based on `asType` parameter
+ * - Compile-time validation of attribute compatibility
+ * - IntelliSense support for observation-specific attributes
+ *
+ * ## Context Requirements
+ * - Must be called within an active OpenTelemetry span context
+ * - Typically used inside `startActiveObservation` callbacks or manual span contexts
+ * - Relies on OpenTelemetry's context propagation mechanism
+ *
+ * ## Supported Observation Types
+ * - **span** (default): General-purpose operations and workflows
+ * - **generation**: LLM calls and AI model interactions
+ * - **agent**: AI agent workflows with tool usage
+ * - **tool**: Individual tool calls and API requests
+ * - **chain**: Multi-step processes and pipelines
+ * - **retriever**: Document retrieval and search operations
+ * - **evaluator**: Quality assessment and scoring
+ * - **guardrail**: Safety checks and content filtering
+ * - **embedding**: Text embedding and vector operations
+ *
+ * @param attributes - Observation-specific attributes to update (type varies by observation type)
+ * @param options - Configuration specifying observation type (defaults to 'span')
+ *
+ * @example
+ * ```typescript
+ * import { updateActiveObservation, startActiveObservation } from '@langfuse/tracing';
+ *
+ * // Update active span (default)
+ * await startActiveObservation('data-processing', async (observation) => {
+ *   // Process data...
+ *   const result = await processData(inputData);
+ *
+ *   // Update with results
+ *   updateActiveObservation({
+ *     output: { processedRecords: result.count },
+ *     metadata: { processingTime: result.duration }
+ *   });
+ * });
+ *
+ * // Update active generation
+ * await startActiveObservation('llm-call', async () => {
+ *   const response = await openai.chat.completions.create({
+ *     model: 'gpt-4',
+ *     messages: [{ role: 'user', content: 'Hello' }]
+ *   });
+ *
+ *   // Update with LLM-specific attributes
+ *   updateActiveObservation({
+ *     output: response.choices[0].message,
+ *     usageDetails: {
+ *       promptTokens: response.usage.prompt_tokens,
+ *       completionTokens: response.usage.completion_tokens,
+ *       totalTokens: response.usage.total_tokens
+ *     },
+ *     costDetails: {
+ *       totalCost: 0.025,
+ *       currency: 'USD'
+ *     }
+ *   }, { asType: 'generation' });
+ * }, {}, { asType: 'generation' });
+ *
+ * // Update active tool execution
+ * await startActiveObservation('web-search', async () => {
+ *   const results = await searchAPI('latest news');
+ *
+ *   updateActiveObservation({
+ *     output: {
+ *       results: results,
+ *       count: results.length,
+ *       relevanceScore: 0.89
+ *     },
+ *     metadata: {
+ *       searchLatency: 150,
+ *       cacheHit: false
+ *     }
+ *   }, { asType: 'tool' });
+ * }, {}, { asType: 'tool' });
+ *
+ * // Update active agent workflow
+ * await startActiveObservation('research-agent', async () => {
+ *   // Agent performs multiple operations...
+ *   const findings = await conductResearch();
+ *
+ *   updateActiveObservation({
+ *     output: {
+ *       completed: true,
+ *       toolsUsed: ['web-search', 'summarizer'],
+ *       iterationsRequired: 3,
+ *       confidence: 0.92
+ *     },
+ *     metadata: {
+ *       efficiency: 0.85,
+ *       qualityScore: 0.88
+ *     }
+ *   }, { asType: 'agent' });
+ * }, {}, { asType: 'agent' });
+ *
+ * // Update active chain workflow
+ * await startActiveObservation('rag-pipeline', async () => {
+ *   // Execute multi-step RAG process...
+ *   const finalResponse = await executeRAGPipeline();
+ *
+ *   updateActiveObservation({
+ *     output: {
+ *       finalResponse: finalResponse,
+ *       stepsCompleted: 4,
+ *       documentsRetrieved: 8,
+ *       qualityScore: 0.91
+ *     },
+ *     metadata: {
+ *       pipelineEfficiency: 0.87,
+ *       totalLatency: 3200
+ *     }
+ *   }, { asType: 'chain' });
+ * }, {}, { asType: 'chain' });
+ * ```
+ *
+ * @see {@link startActiveObservation} - For creating active observation contexts
+ * @see {@link updateActiveTrace} - For updating trace-level attributes
+ *
+ * @public
+ */
+declare function updateActiveObservation(attributes: LangfuseSpanAttributes, options?: {
+    asType: "span";
+}): void;
+declare function updateActiveObservation(attributes: LangfuseGenerationAttributes, options: {
+    asType: "generation";
+}): void;
+declare function updateActiveObservation(attributes: LangfuseAgentAttributes, options: {
+    asType: "agent";
+}): void;
+declare function updateActiveObservation(attributes: LangfuseToolAttributes, options: {
+    asType: "tool";
+}): void;
+declare function updateActiveObservation(attributes: LangfuseChainAttributes, options: {
+    asType: "chain";
+}): void;
+declare function updateActiveObservation(attributes: LangfuseEmbeddingAttributes, options: {
+    asType: "embedding";
+}): void;
+declare function updateActiveObservation(attributes: LangfuseEvaluatorAttributes, options: {
+    asType: "evaluator";
+}): void;
+declare function updateActiveObservation(attributes: LangfuseGuardrailAttributes, options: {
+    asType: "guardrail";
+}): void;
+declare function updateActiveObservation(attributes: LangfuseRetrieverAttributes, options: {
+    asType: "retriever";
+}): void;
 /**
  * Options for the observe decorator function.
  *
@@ -1875,7 +2024,7 @@ interface ObserveOptions {
  *
  * @public
  */
-declare function observe<T extends (...args: unknown[]) => unknown>(fn: T, options?: ObserveOptions): T;
+declare function observe<T extends (...args: any[]) => any>(fn: T, options?: ObserveOptions): T;
 /**
  * Creates a trace ID for OpenTelemetry spans.
  *

package/dist/index.d.ts

@@ -1598,15 +1598,164 @@ declare function startActiveObservation<F extends (span: LangfuseSpan) => unknow
  * @public
  */
 declare function updateActiveTrace(attributes: LangfuseTraceAttributes): void;
-declare function updateActiveObservation(currentType: "span", attributes: LangfuseSpanAttributes): void;
-declare function updateActiveObservation(currentType: "generation", attributes: LangfuseGenerationAttributes): void;
-declare function updateActiveObservation(currentType: "agent", attributes: LangfuseAgentAttributes): void;
-declare function updateActiveObservation(currentType: "tool", attributes: LangfuseToolAttributes): void;
-declare function updateActiveObservation(currentType: "chain", attributes: LangfuseChainAttributes): void;
-declare function updateActiveObservation(currentType: "embedding", attributes: LangfuseEmbeddingAttributes): void;
-declare function updateActiveObservation(currentType: "evaluator", attributes: LangfuseEvaluatorAttributes): void;
-declare function updateActiveObservation(currentType: "guardrail", attributes: LangfuseGuardrailAttributes): void;
-declare function updateActiveObservation(currentType: "retriever", attributes: LangfuseRetrieverAttributes): void;
+/**
+ * Updates the currently active observation with new attributes.
+ *
+ * This function finds the currently active OpenTelemetry span in the execution context
+ * and updates it with Langfuse-specific attributes. It supports all observation types
+ * through TypeScript overloads, providing type safety for attributes based on the
+ * specified `asType` parameter. If no active span exists, the update is skipped with a warning.
+ *
+ * ## Type Safety
+ * - Automatic type inference based on `asType` parameter
+ * - Compile-time validation of attribute compatibility
+ * - IntelliSense support for observation-specific attributes
+ *
+ * ## Context Requirements
+ * - Must be called within an active OpenTelemetry span context
+ * - Typically used inside `startActiveObservation` callbacks or manual span contexts
+ * - Relies on OpenTelemetry's context propagation mechanism
+ *
+ * ## Supported Observation Types
+ * - **span** (default): General-purpose operations and workflows
+ * - **generation**: LLM calls and AI model interactions
+ * - **agent**: AI agent workflows with tool usage
+ * - **tool**: Individual tool calls and API requests
+ * - **chain**: Multi-step processes and pipelines
+ * - **retriever**: Document retrieval and search operations
+ * - **evaluator**: Quality assessment and scoring
+ * - **guardrail**: Safety checks and content filtering
+ * - **embedding**: Text embedding and vector operations
+ *
+ * @param attributes - Observation-specific attributes to update (type varies by observation type)
+ * @param options - Configuration specifying observation type (defaults to 'span')
+ *
+ * @example
+ * ```typescript
+ * import { updateActiveObservation, startActiveObservation } from '@langfuse/tracing';
+ *
+ * // Update active span (default)
+ * await startActiveObservation('data-processing', async (observation) => {
+ *   // Process data...
+ *   const result = await processData(inputData);
+ *
+ *   // Update with results
+ *   updateActiveObservation({
+ *     output: { processedRecords: result.count },
+ *     metadata: { processingTime: result.duration }
+ *   });
+ * });
+ *
+ * // Update active generation
+ * await startActiveObservation('llm-call', async () => {
+ *   const response = await openai.chat.completions.create({
+ *     model: 'gpt-4',
+ *     messages: [{ role: 'user', content: 'Hello' }]
+ *   });
+ *
+ *   // Update with LLM-specific attributes
+ *   updateActiveObservation({
+ *     output: response.choices[0].message,
+ *     usageDetails: {
+ *       promptTokens: response.usage.prompt_tokens,
+ *       completionTokens: response.usage.completion_tokens,
+ *       totalTokens: response.usage.total_tokens
+ *     },
+ *     costDetails: {
+ *       totalCost: 0.025,
+ *       currency: 'USD'
+ *     }
+ *   }, { asType: 'generation' });
+ * }, {}, { asType: 'generation' });
+ *
+ * // Update active tool execution
+ * await startActiveObservation('web-search', async () => {
+ *   const results = await searchAPI('latest news');
+ *
+ *   updateActiveObservation({
+ *     output: {
+ *       results: results,
+ *       count: results.length,
+ *       relevanceScore: 0.89
+ *     },
+ *     metadata: {
+ *       searchLatency: 150,
+ *       cacheHit: false
+ *     }
+ *   }, { asType: 'tool' });
+ * }, {}, { asType: 'tool' });
+ *
+ * // Update active agent workflow
+ * await startActiveObservation('research-agent', async () => {
+ *   // Agent performs multiple operations...
+ *   const findings = await conductResearch();
+ *
+ *   updateActiveObservation({
+ *     output: {
+ *       completed: true,
+ *       toolsUsed: ['web-search', 'summarizer'],
+ *       iterationsRequired: 3,
+ *       confidence: 0.92
+ *     },
+ *     metadata: {
+ *       efficiency: 0.85,
+ *       qualityScore: 0.88
+ *     }
+ *   }, { asType: 'agent' });
+ * }, {}, { asType: 'agent' });
+ *
+ * // Update active chain workflow
+ * await startActiveObservation('rag-pipeline', async () => {
+ *   // Execute multi-step RAG process...
+ *   const finalResponse = await executeRAGPipeline();
+ *
+ *   updateActiveObservation({
+ *     output: {
+ *       finalResponse: finalResponse,
+ *       stepsCompleted: 4,
+ *       documentsRetrieved: 8,
+ *       qualityScore: 0.91
+ *     },
+ *     metadata: {
+ *       pipelineEfficiency: 0.87,
+ *       totalLatency: 3200
+ *     }
+ *   }, { asType: 'chain' });
+ * }, {}, { asType: 'chain' });
+ * ```
+ *
+ * @see {@link startActiveObservation} - For creating active observation contexts
+ * @see {@link updateActiveTrace} - For updating trace-level attributes
+ *
+ * @public
+ */
+declare function updateActiveObservation(attributes: LangfuseSpanAttributes, options?: {
+    asType: "span";
+}): void;
+declare function updateActiveObservation(attributes: LangfuseGenerationAttributes, options: {
+    asType: "generation";
+}): void;
+declare function updateActiveObservation(attributes: LangfuseAgentAttributes, options: {
+    asType: "agent";
+}): void;
+declare function updateActiveObservation(attributes: LangfuseToolAttributes, options: {
+    asType: "tool";
+}): void;
+declare function updateActiveObservation(attributes: LangfuseChainAttributes, options: {
+    asType: "chain";
+}): void;
+declare function updateActiveObservation(attributes: LangfuseEmbeddingAttributes, options: {
+    asType: "embedding";
+}): void;
+declare function updateActiveObservation(attributes: LangfuseEvaluatorAttributes, options: {
+    asType: "evaluator";
+}): void;
+declare function updateActiveObservation(attributes: LangfuseGuardrailAttributes, options: {
+    asType: "guardrail";
+}): void;
+declare function updateActiveObservation(attributes: LangfuseRetrieverAttributes, options: {
+    asType: "retriever";
+}): void;
 /**
  * Options for the observe decorator function.
  *
@@ -1875,7 +2024,7 @@ interface ObserveOptions {
  *
  * @public
  */
-declare function observe<T extends (...args: unknown[]) => unknown>(fn: T, options?: ObserveOptions): T;
+declare function observe<T extends (...args: any[]) => any>(fn: T, options?: ObserveOptions): T;
 /**
  * Creates a trace ID for OpenTelemetry spans.
  *

package/dist/index.mjs

@@ -1,5 +1,5 @@
 // src/index.ts
-import { getGlobalLogger as getGlobalLogger2 } from "@langfuse/core";
+import { getGlobalLogger as getGlobalLogger2, LangfuseOtelSpanAttributes as LangfuseOtelSpanAttributes2 } from "@langfuse/core";
 import {
   trace as trace2,
   context,
@@ -411,7 +411,7 @@ var LangfuseEvent = class extends LangfuseBaseObservation {
 };
 
 // src/index.ts
-import { LangfuseOtelSpanAttributes as LangfuseOtelSpanAttributes2 } from "@langfuse/core";
+import { LangfuseOtelSpanAttributes as LangfuseOtelSpanAttributes3 } from "@langfuse/core";
 function createOtelSpan(params) {
   return getLangfuseTracer().startSpan(
     params.name,
@@ -609,7 +609,8 @@ function updateActiveTrace(attributes) {
   }
   span.setAttributes(createTraceAttributes(attributes));
 }
-function updateActiveObservation(currentType, attributes) {
+function updateActiveObservation(attributes, options) {
+  var _a;
   const span = trace2.getActiveSpan();
   if (!span) {
     getGlobalLogger2().warn(
@@ -617,7 +618,14 @@ function updateActiveObservation(currentType, attributes) {
     );
     return;
   }
-  span.setAttributes(createObservationAttributes(currentType, attributes));
+  const otelAttributes = createObservationAttributes(
+    (_a = options == null ? void 0 : options.asType) != null ? _a : "span",
+    attributes
+  );
+  if (!(options == null ? void 0 : options.asType)) {
+    otelAttributes[LangfuseOtelSpanAttributes2.OBSERVATION_TYPE] = void 0;
+  }
+  span.setAttributes(otelAttributes);
 }
 function observe(fn, options = {}) {
   const {
@@ -734,7 +742,7 @@ export {
   LangfuseEvent,
   LangfuseGeneration,
   LangfuseGuardrail,
-  LangfuseOtelSpanAttributes2 as LangfuseOtelSpanAttributes,
+  LangfuseOtelSpanAttributes3 as LangfuseOtelSpanAttributes,
   LangfuseRetriever,
   LangfuseSpan,
   LangfuseTool,