@moduna/otel 1.1.2 → 1.1.4

package/README.md

@@ -121,10 +121,16 @@ const result = await model.invoke("Hello, world!", {
 });
 ```
 
+Enable callback trace lifecycle logs while debugging instrumentation.
+
+```ts
+const handler = otel.langChainHandler({}, { debug: true });
+```
+
 Or register it globally for all LangChain runs.
 
 ```ts
-otel.registerGlobalLangChainHandler();
+otel.registerGlobalLangChainHandler({}, { debug: true });
 
 const result = await model.invoke("Hello, world!", {
     metadata: {

package/dist/services/ModunaLangChainCallbackHandler.d.ts

@@ -7,6 +7,14 @@ import type { ModunaTraceContext } from "../types/TraceContext.js";
  * Configuration for Moduna's LangChain callback handler.
  */
 export interface ModunaLangChainCallbackHandlerConfig {
+    /**
+     * Enables trace lifecycle logging for LangChain callback events.
+     */
+    debug?: boolean;
+    /**
+     * Logger used when debug trace logging is enabled.
+     */
+    logger?: Pick<Console, "debug" | "error">;
     /**
      * Default trace identifiers used when a LangChain call has no metadata.
      */
@@ -20,7 +28,9 @@ export declare class ModunaLangChainCallbackHandler extends BaseCallbackHandler
      * Stable handler name used by LangChain callback manager de-duplication.
      */
     name: string;
+    private readonly debug;
     private readonly defaultTraceContext;
+    private readonly logger;
     private readonly runs;
     /**
      * Creates a LangChain callback handler for Moduna spans.
@@ -77,9 +87,174 @@ export declare class ModunaLangChainCallbackHandler extends BaseCallbackHandler
      */
     handleLLMError(error: unknown, runId: string): void;
     private startRun;
+    /**
+     * Applies model/provider attributes using LangChain serialization metadata.
+     *
+     * @param span Span receiving model attributes.
+     * @param llm Serialized LangChain model metadata.
+     * @param extraParams Provider-specific invocation parameters.
+     */
     private applyModelAttributes;
+    /**
+     * Applies Moduna conversation and session identifiers to a span.
+     *
+     * @param span Span receiving trace context attributes.
+     * @param metadata LangChain metadata supplied on the run.
+     */
     private applyTraceContext;
+    /**
+     * Applies prompt input attributes in LangSmith-compatible GenAI format.
+     *
+     * @param span Span receiving prompt attributes.
+     * @param messages Normalized prompt messages.
+     */
+    private applyPromptAttributes;
+    /**
+     * Applies request parameter attributes in GenAI semantic format.
+     *
+     * @param span Span receiving invocation parameter attributes.
+     * @param extraParams Provider-specific invocation parameters.
+     */
+    private applyInvocationAttributes;
+    /**
+     * Applies model completion output attributes from a LangChain result.
+     *
+     * @param span Span receiving completion attributes.
+     * @param output LangChain LLM output.
+     */
+    private applyCompletionAttributes;
+    /**
+     * Applies token usage attributes from a LangChain result.
+     *
+     * @param span Span receiving usage attributes.
+     * @param output LangChain LLM output.
+     * @param streamedTokenCount Token count observed from streaming callbacks.
+     */
+    private applyUsageAttributes;
+    /**
+     * Extracts token usage from LangChain result metadata and provider outputs.
+     *
+     * @param output LangChain LLM output.
+     * @returns Normalized token usage when present.
+     */
+    private extractUsage;
+    /**
+     * Finds the first message usage metadata in a LangChain result.
+     *
+     * @param output LangChain LLM output.
+     * @returns Usage metadata record when present.
+     */
+    private getFirstUsageMetadata;
+    /**
+     * Finds the model name returned by the provider, when available.
+     *
+     * @param output LangChain LLM output.
+     * @returns Provider response model name when present.
+     */
+    private getResponseModel;
+    /**
+     * Counts all generated candidates in a LangChain result.
+     *
+     * @param output LangChain LLM output.
+     * @returns Total generation candidate count.
+     */
+    private countGenerations;
+    /**
+     * Converts batches of LangChain messages to flat normalized messages.
+     *
+     * @param messageBatches LangChain message batches.
+     * @returns Flat list of normalized prompt messages.
+     */
+    private normalizeMessageBatches;
+    /**
+     * Converts a LangChain message to a GenAI-compatible role/content pair.
+     *
+     * @param message LangChain base message.
+     * @returns Normalized message.
+     */
+    private normalizeMessage;
+    /**
+     * Converts LangChain message types to GenAI/OpenAI role names.
+     *
+     * @param type LangChain message type.
+     * @returns Role name for telemetry.
+     */
+    private mapMessageRole;
+    /**
+     * Extracts a normalized chat generation message when one exists.
+     *
+     * @param generation LangChain generation candidate.
+     * @returns Normalized generation message when present.
+     */
+    private getGenerationMessage;
+    /**
+     * Extracts a message-shaped value from a LangChain generation.
+     *
+     * @param generation LangChain generation candidate.
+     * @returns Message-shaped record when present.
+     */
+    private getMessageLike;
+    /**
+     * Infers a provider name from serialized model metadata.
+     *
+     * @param llm Serialized LangChain model metadata.
+     * @param modelName Model name used for the request.
+     * @returns Provider name for GenAI attributes.
+     */
+    private inferProvider;
+    /**
+     * Sets a span attribute when the value is OpenTelemetry-compatible.
+     *
+     * @param span Span receiving the attribute.
+     * @param key Attribute key.
+     * @param value Attribute value.
+     */
+    private setAttributeIfSupported;
+    /**
+     * Emits a debug trace lifecycle log when debug mode is enabled.
+     *
+     * @param event Trace lifecycle event name.
+     * @param span Span associated with the lifecycle event.
+     * @param payload Additional event fields.
+     */
+    private debugLog;
+    /**
+     * Converts arbitrary values to supported OpenTelemetry attribute values.
+     *
+     * @param value Unknown source value.
+     * @returns OpenTelemetry attribute value when representable.
+     */
+    private toAttributeValue;
+    /**
+     * Reads an object-valued property from a record-like value.
+     *
+     * @param value Record-like source value.
+     * @param key Property key.
+     * @returns Nested record when present.
+     */
+    private getRecord;
+    /**
+     * Reads a string-valued property from a record-like value.
+     *
+     * @param value Record-like source value.
+     * @param key Property key.
+     * @returns String property when present.
+     */
     private getString;
+    /**
+     * Reads a number-valued property from a record-like value.
+     *
+     * @param value Record-like source value.
+     * @param key Property key.
+     * @returns Number property when present.
+     */
+    private getNumber;
+    /**
+     * Normalizes unknown errors to Error instances.
+     *
+     * @param error Unknown error value.
+     * @returns Error instance.
+     */
     private toError;
 }
 /**

package/dist/services/ModunaLangChainCallbackHandler.js

@@ -11,7 +11,9 @@ export class ModunaLangChainCallbackHandler extends BaseCallbackHandler {
      * Stable handler name used by LangChain callback manager de-duplication.
      */
     name = "moduna_otel_langchain_callback_handler";
+    debug;
     defaultTraceContext;
+    logger;
     runs = new Map();
     /**
      * Creates a LangChain callback handler for Moduna spans.
@@ -20,7 +22,9 @@ export class ModunaLangChainCallbackHandler extends BaseCallbackHandler {
      */
     constructor(config = {}) {
         super();
+        this.debug = config.debug ?? false;
         this.defaultTraceContext = config.traceContext ?? {};
+        this.logger = config.logger ?? console;
     }
     /**
      * Starts a span for a LangChain chat model run.
@@ -37,7 +41,8 @@ export class ModunaLangChainCallbackHandler extends BaseCallbackHandler {
     handleChatModelStart(llm, messages, runId, parentRunId, extraParams, tags, metadata, runName) {
         this.startRun({
             extraParams,
-            inputCount: messages.length,
+            inputCount: messages.flat().length,
+            inputMessages: this.normalizeMessageBatches(messages),
             llm,
             metadata,
             parentRunId,
@@ -63,6 +68,10 @@ export class ModunaLangChainCallbackHandler extends BaseCallbackHandler {
         this.startRun({
             extraParams,
             inputCount: prompts.length,
+            inputMessages: prompts.map((prompt) => ({
+                content: prompt,
+                role: "user",
+            })),
             llm,
             metadata,
             parentRunId,
@@ -80,7 +89,21 @@ export class ModunaLangChainCallbackHandler extends BaseCallbackHandler {
      * @param runId LangChain run identifier.
      */
     handleLLMNewToken(_token, _idx, runId) {
-        this.runs.get(runId)?.span.addEvent("langchain.llm.token");
+        const run = this.runs.get(runId);
+        if (!run) {
+            return;
+        }
+        run.streamedTokenCount += 1;
+        run.span.addEvent("gen_ai.content.completion", {
+            content: _token,
+            role: "assistant",
+        });
+        this.debugLog("token", run.span, {
+            runId,
+            runType: run.runType,
+            streamedTokenCount: run.streamedTokenCount,
+            tokenLength: _token.length,
+        });
     }
     /**
      * Ends the span for a successful LangChain run.
@@ -94,6 +117,17 @@ export class ModunaLangChainCallbackHandler extends BaseCallbackHandler {
             return;
         }
         run.span.setAttribute("langchain.output.generations", output.generations.length);
+        run.span.setAttribute("langchain.output.candidates", this.countGenerations(output));
+        this.applyCompletionAttributes(run.span, output);
+        this.applyUsageAttributes(run.span, output, run.streamedTokenCount);
+        this.debugLog("end", run.span, {
+            candidateCount: this.countGenerations(output),
+            generationCount: output.generations.length,
+            runId,
+            runType: run.runType,
+            streamedTokenCount: run.streamedTokenCount,
+            usage: this.extractUsage(output),
+        });
         run.span.setStatus({ code: SpanStatusCode.OK });
         run.span.end();
         this.runs.delete(runId);
@@ -109,10 +143,17 @@ export class ModunaLangChainCallbackHandler extends BaseCallbackHandler {
         if (!run) {
             return;
         }
-        run.span.recordException(this.toError(error));
+        const normalizedError = this.toError(error);
+        run.span.recordException(normalizedError);
         run.span.setStatus({
             code: SpanStatusCode.ERROR,
-            message: this.toError(error).message,
+            message: normalizedError.message,
+        });
+        this.debugLog("error", run.span, {
+            errorName: normalizedError.name,
+            errorMessage: normalizedError.message,
+            runId,
+            runType: run.runType,
         });
         run.span.end();
         this.runs.delete(runId);
@@ -127,25 +168,66 @@ export class ModunaLangChainCallbackHandler extends BaseCallbackHandler {
         span.setAttribute("langchain.run.id", input.runId);
         span.setAttribute("langchain.run.type", input.runType);
         span.setAttribute("langchain.input.count", input.inputCount);
+        span.setAttribute("langsmith.span.kind", "llm");
+        span.setAttribute("gen_ai.operation.name", input.runType === "chat_model" ? "chat" : "completion");
+        span.setAttribute("llm.request.type", input.runType === "chat_model" ? "chat" : "completion");
         if (input.parentRunId) {
             span.setAttribute("langchain.parent_run.id", input.parentRunId);
         }
+        if (input.runName) {
+            span.setAttribute("langsmith.trace.name", input.runName);
+        }
         if (input.tags?.length) {
             span.setAttribute("langchain.tags", input.tags.join(","));
+            span.setAttribute("langsmith.span.tags", input.tags.join(","));
         }
         this.applyModelAttributes(span, input.llm, input.extraParams);
+        this.applyPromptAttributes(span, input.inputMessages);
+        this.applyInvocationAttributes(span, input.extraParams);
         this.applyTraceContext(span, input.metadata);
-        this.runs.set(input.runId, { span });
+        this.runs.set(input.runId, {
+            runType: input.runType,
+            span,
+            streamedTokenCount: 0,
+        });
+        this.debugLog("start", span, {
+            inputCount: input.inputCount,
+            parentRunId: input.parentRunId,
+            runId: input.runId,
+            runName: input.runName,
+            runType: input.runType,
+            tags: input.tags,
+        });
     }
+    /**
+     * Applies model/provider attributes using LangChain serialization metadata.
+     *
+     * @param span Span receiving model attributes.
+     * @param llm Serialized LangChain model metadata.
+     * @param extraParams Provider-specific invocation parameters.
+     */
     applyModelAttributes(span, llm, extraParams) {
-        const modelName = this.getString(extraParams?.invocation_params, "model") ??
-            this.getString(extraParams?.invocation_params, "modelName") ??
+        const invocationParams = this.getRecord(extraParams, "invocation_params");
+        const modelName = this.getString(invocationParams, "model") ??
+            this.getString(invocationParams, "modelName") ??
+            this.getString(invocationParams, "model_name") ??
             this.getString(llm, "name") ??
             llm.id.join(".");
-        span.setAttribute("gen_ai.system", "google");
+        const provider = this.getString(invocationParams, "model_provider") ??
+            this.getString(invocationParams, "provider") ??
+            this.inferProvider(llm, modelName);
+        span.setAttribute("gen_ai.system", provider);
         span.setAttribute("gen_ai.request.model", modelName);
+        span.setAttribute("llm.model_name", modelName);
+        span.setAttribute("metadata.ls_model_name", modelName);
         span.setAttribute("langchain.serialized.id", llm.id.join("."));
     }
+    /**
+     * Applies Moduna conversation and session identifiers to a span.
+     *
+     * @param span Span receiving trace context attributes.
+     * @param metadata LangChain metadata supplied on the run.
+     */
     applyTraceContext(span, metadata) {
         const traceContext = {
             conversationId: this.getString(metadata, "conversationId") ??
@@ -157,11 +239,378 @@ export class ModunaLangChainCallbackHandler extends BaseCallbackHandler {
         };
         if (traceContext.conversationId) {
             span.setAttribute("moduna.conversation.id", traceContext.conversationId);
+            span.setAttribute("langsmith.metadata.conversation_id", traceContext.conversationId);
         }
         if (traceContext.sessionId) {
             span.setAttribute("moduna.session.id", traceContext.sessionId);
+            span.setAttribute("langsmith.metadata.session_id", traceContext.sessionId);
+            span.setAttribute("langsmith.trace.session_id", traceContext.sessionId);
+        }
+    }
+    /**
+     * Applies prompt input attributes in LangSmith-compatible GenAI format.
+     *
+     * @param span Span receiving prompt attributes.
+     * @param messages Normalized prompt messages.
+     */
+    applyPromptAttributes(span, messages) {
+        if (messages.length === 0) {
+            return;
+        }
+        for (const [index, message] of messages.entries()) {
+            span.setAttribute(`gen_ai.prompt.${index}.role`, message.role);
+            span.setAttribute(`gen_ai.prompt.${index}.content`, message.content);
+        }
+        span.setAttribute("gen_ai.input.messages", JSON.stringify(messages));
+        span.addEvent("gen_ai.content.prompt", {
+            content: JSON.stringify(messages),
+        });
+    }
+    /**
+     * Applies request parameter attributes in GenAI semantic format.
+     *
+     * @param span Span receiving invocation parameter attributes.
+     * @param extraParams Provider-specific invocation parameters.
+     */
+    applyInvocationAttributes(span, extraParams) {
+        const invocationParams = this.getRecord(extraParams, "invocation_params");
+        if (!invocationParams) {
+            return;
         }
+        const mappings = [
+            ["temperature", "gen_ai.request.temperature"],
+            ["top_p", "gen_ai.request.top_p"],
+            ["max_tokens", "gen_ai.request.max_tokens"],
+            ["maxOutputTokens", "gen_ai.request.max_tokens"],
+            ["frequency_penalty", "gen_ai.request.frequency_penalty"],
+            ["presence_penalty", "gen_ai.request.presence_penalty"],
+            ["seed", "gen_ai.request.seed"],
+            ["stop", "gen_ai.request.stop_sequences"],
+            ["stop_sequences", "gen_ai.request.stop_sequences"],
+            ["top_k", "gen_ai.request.top_k"],
+            ["encoding_formats", "gen_ai.request.encoding_formats"],
+            ["tools", "tools"],
+        ];
+        for (const [sourceKey, attributeKey] of mappings) {
+            this.setAttributeIfSupported(span, attributeKey, invocationParams[sourceKey]);
+        }
+        span.setAttribute("llm.invocation_parameters", JSON.stringify(invocationParams));
     }
+    /**
+     * Applies model completion output attributes from a LangChain result.
+     *
+     * @param span Span receiving completion attributes.
+     * @param output LangChain LLM output.
+     */
+    applyCompletionAttributes(span, output) {
+        const messages = [];
+        for (const generationGroup of output.generations) {
+            for (const generation of generationGroup) {
+                const message = this.getGenerationMessage(generation);
+                messages.push(message ?? {
+                    content: generation.text,
+                    role: "assistant",
+                });
+            }
+        }
+        for (const [index, message] of messages.entries()) {
+            span.setAttribute(`gen_ai.completion.${index}.role`, message.role);
+            span.setAttribute(`gen_ai.completion.${index}.content`, message.content);
+        }
+        if (messages.length > 0) {
+            span.setAttribute("gen_ai.output.messages", JSON.stringify(messages));
+            span.addEvent("gen_ai.content.completion", {
+                content: JSON.stringify(messages),
+            });
+        }
+        const responseModel = this.getResponseModel(output);
+        if (responseModel) {
+            span.setAttribute("gen_ai.response.model", responseModel);
+        }
+    }
+    /**
+     * Applies token usage attributes from a LangChain result.
+     *
+     * @param span Span receiving usage attributes.
+     * @param output LangChain LLM output.
+     * @param streamedTokenCount Token count observed from streaming callbacks.
+     */
+    applyUsageAttributes(span, output, streamedTokenCount) {
+        const usage = this.extractUsage(output);
+        if (usage.promptTokens !== undefined) {
+            span.setAttribute("gen_ai.usage.input_tokens", usage.promptTokens);
+            span.setAttribute("gen_ai.usage.prompt_tokens", usage.promptTokens);
+            span.setAttribute("llm.token_count.prompt", usage.promptTokens);
+        }
+        const completionTokens = usage.completionTokens ??
+            (streamedTokenCount > 0 ? streamedTokenCount : undefined);
+        if (completionTokens !== undefined) {
+            span.setAttribute("gen_ai.usage.output_tokens", completionTokens);
+            span.setAttribute("gen_ai.usage.completion_tokens", completionTokens);
+            span.setAttribute("llm.token_count.completion", completionTokens);
+        }
+        if (usage.totalTokens !== undefined) {
+            span.setAttribute("gen_ai.usage.total_tokens", usage.totalTokens);
+            span.setAttribute("llm.token_count.total", usage.totalTokens);
+            span.setAttribute("llm.usage.total_tokens", usage.totalTokens);
+        }
+        if (usage.reasoningTokens !== undefined) {
+            span.setAttribute("gen_ai.usage.details.reasoning_tokens", usage.reasoningTokens);
+        }
+    }
+    /**
+     * Extracts token usage from LangChain result metadata and provider outputs.
+     *
+     * @param output LangChain LLM output.
+     * @returns Normalized token usage when present.
+     */
+    extractUsage(output) {
+        const usageMetadata = this.getFirstUsageMetadata(output);
+        const tokenUsage = this.getRecord(output.llmOutput, "tokenUsage");
+        const estimatedTokenUsage = this.getRecord(output.llmOutput, "estimatedTokenUsage");
+        return {
+            completionTokens: this.getNumber(usageMetadata, "output_tokens") ??
+                this.getNumber(tokenUsage, "completionTokens") ??
+                this.getNumber(tokenUsage, "completion_tokens") ??
+                this.getNumber(estimatedTokenUsage, "completionTokens"),
+            promptTokens: this.getNumber(usageMetadata, "input_tokens") ??
+                this.getNumber(tokenUsage, "promptTokens") ??
+                this.getNumber(tokenUsage, "prompt_tokens") ??
+                this.getNumber(estimatedTokenUsage, "promptTokens"),
+            reasoningTokens: this.getNumber(this.getRecord(usageMetadata, "output_token_details"), "reasoning"),
+            totalTokens: this.getNumber(usageMetadata, "total_tokens") ??
+                this.getNumber(tokenUsage, "totalTokens") ??
+                this.getNumber(tokenUsage, "total_tokens") ??
+                this.getNumber(estimatedTokenUsage, "totalTokens"),
+        };
+    }
+    /**
+     * Finds the first message usage metadata in a LangChain result.
+     *
+     * @param output LangChain LLM output.
+     * @returns Usage metadata record when present.
+     */
+    getFirstUsageMetadata(output) {
+        for (const generationGroup of output.generations) {
+            for (const generation of generationGroup) {
+                const message = this.getMessageLike(generation);
+                const usageMetadata = this.getRecord(message, "usage_metadata");
+                if (usageMetadata) {
+                    return usageMetadata;
+                }
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Finds the model name returned by the provider, when available.
+     *
+     * @param output LangChain LLM output.
+     * @returns Provider response model name when present.
+     */
+    getResponseModel(output) {
+        for (const generationGroup of output.generations) {
+            for (const generation of generationGroup) {
+                const message = this.getMessageLike(generation);
+                const responseMetadata = this.getRecord(message, "response_metadata");
+                const model = this.getString(responseMetadata, "model_name") ??
+                    this.getString(responseMetadata, "model") ??
+                    this.getString(output.llmOutput, "model");
+                if (model) {
+                    return model;
+                }
+            }
+        }
+        return this.getString(output.llmOutput, "model");
+    }
+    /**
+     * Counts all generated candidates in a LangChain result.
+     *
+     * @param output LangChain LLM output.
+     * @returns Total generation candidate count.
+     */
+    countGenerations(output) {
+        return output.generations.reduce((count, generationGroup) => count + generationGroup.length, 0);
+    }
+    /**
+     * Converts batches of LangChain messages to flat normalized messages.
+     *
+     * @param messageBatches LangChain message batches.
+     * @returns Flat list of normalized prompt messages.
+     */
+    normalizeMessageBatches(messageBatches) {
+        return messageBatches.flatMap((messages) => messages.map((message) => this.normalizeMessage(message)));
+    }
+    /**
+     * Converts a LangChain message to a GenAI-compatible role/content pair.
+     *
+     * @param message LangChain base message.
+     * @returns Normalized message.
+     */
+    normalizeMessage(message) {
+        return {
+            content: typeof message.content === "string"
+                ? message.content
+                : JSON.stringify(message.content),
+            role: this.mapMessageRole(message.type),
+        };
+    }
+    /**
+     * Converts LangChain message types to GenAI/OpenAI role names.
+     *
+     * @param type LangChain message type.
+     * @returns Role name for telemetry.
+     */
+    mapMessageRole(type) {
+        const roleMap = {
+            ai: "assistant",
+            human: "user",
+            system: "system",
+            tool: "tool",
+        };
+        return roleMap[type] ?? type;
+    }
+    /**
+     * Extracts a normalized chat generation message when one exists.
+     *
+     * @param generation LangChain generation candidate.
+     * @returns Normalized generation message when present.
+     */
+    getGenerationMessage(generation) {
+        const message = this.getMessageLike(generation);
+        if (!message) {
+            return undefined;
+        }
+        const content = message.content;
+        const type = this.getString(message, "type");
+        if (typeof content !== "string" && !Array.isArray(content)) {
+            return undefined;
+        }
+        return {
+            content: typeof content === "string" ? content : JSON.stringify(content),
+            role: this.mapMessageRole(type ?? "assistant"),
+        };
+    }
+    /**
+     * Extracts a message-shaped value from a LangChain generation.
+     *
+     * @param generation LangChain generation candidate.
+     * @returns Message-shaped record when present.
+     */
+    getMessageLike(generation) {
+        return this.getRecord(generation, "message");
+    }
+    /**
+     * Infers a provider name from serialized model metadata.
+     *
+     * @param llm Serialized LangChain model metadata.
+     * @param modelName Model name used for the request.
+     * @returns Provider name for GenAI attributes.
+     */
+    inferProvider(llm, modelName) {
+        const serializedId = llm.id.join(".").toLowerCase();
+        const model = modelName.toLowerCase();
+        if (serializedId.includes("google") || model.includes("gemini")) {
+            return "google";
+        }
+        if (serializedId.includes("openai") || model.includes("gpt")) {
+            return "openai";
+        }
+        if (serializedId.includes("anthropic") || model.includes("claude")) {
+            return "anthropic";
+        }
+        return llm.id.at(-1) ?? "unknown";
+    }
+    /**
+     * Sets a span attribute when the value is OpenTelemetry-compatible.
+     *
+     * @param span Span receiving the attribute.
+     * @param key Attribute key.
+     * @param value Attribute value.
+     */
+    setAttributeIfSupported(span, key, value) {
+        const attributeValue = this.toAttributeValue(value);
+        if (attributeValue !== undefined) {
+            span.setAttribute(key, attributeValue);
+        }
+    }
+    /**
+     * Emits a debug trace lifecycle log when debug mode is enabled.
+     *
+     * @param event Trace lifecycle event name.
+     * @param span Span associated with the lifecycle event.
+     * @param payload Additional event fields.
+     */
+    debugLog(event, span, payload) {
+        if (!this.debug) {
+            return;
+        }
+        const spanContext = span.spanContext();
+        const logPayload = {
+            event,
+            spanId: spanContext.spanId,
+            traceId: spanContext.traceId,
+            ...payload,
+        };
+        if (event === "error") {
+            this.logger.error("[moduna:langchain]", logPayload);
+            return;
+        }
+        this.logger.debug("[moduna:langchain]", logPayload);
+    }
+    /**
+     * Converts arbitrary values to supported OpenTelemetry attribute values.
+     *
+     * @param value Unknown source value.
+     * @returns OpenTelemetry attribute value when representable.
+     */
+    toAttributeValue(value) {
+        if (typeof value === "string" ||
+            typeof value === "number" ||
+            typeof value === "boolean") {
+            return value;
+        }
+        if (Array.isArray(value)) {
+            if (value.every((item) => typeof item === "string")) {
+                return value;
+            }
+            if (value.every((item) => typeof item === "number")) {
+                return value;
+            }
+            if (value.every((item) => typeof item === "boolean")) {
+                return value;
+            }
+            return JSON.stringify(value);
+        }
+        if (value && typeof value === "object") {
+            return JSON.stringify(value);
+        }
+        return undefined;
+    }
+    /**
+     * Reads an object-valued property from a record-like value.
+     *
+     * @param value Record-like source value.
+     * @param key Property key.
+     * @returns Nested record when present.
+     */
+    getRecord(value, key) {
+        if (!value || typeof value !== "object") {
+            return undefined;
+        }
+        const record = value;
+        const result = record[key];
+        return result && typeof result === "object" && !Array.isArray(result)
+            ? result
+            : undefined;
+    }
+    /**
+     * Reads a string-valued property from a record-like value.
+     *
+     * @param value Record-like source value.
+     * @param key Property key.
+     * @returns String property when present.
+     */
     getString(value, key) {
         if (!value || typeof value !== "object") {
             return undefined;
@@ -170,6 +619,27 @@ export class ModunaLangChainCallbackHandler extends BaseCallbackHandler {
         const result = record[key];
         return typeof result === "string" ? result : undefined;
     }
+    /**
+     * Reads a number-valued property from a record-like value.
+     *
+     * @param value Record-like source value.
+     * @param key Property key.
+     * @returns Number property when present.
+     */
+    getNumber(value, key) {
+        if (!value || typeof value !== "object") {
+            return undefined;
+        }
+        const record = value;
+        const result = record[key];
+        return typeof result === "number" ? result : undefined;
+    }
+    /**
+     * Normalizes unknown errors to Error instances.
+     *
+     * @param error Unknown error value.
+     * @returns Error instance.
+     */
     toError(error) {
         return error instanceof Error ? error : new Error(String(error));
     }

package/dist/services/ModunaOTEL.d.ts

@@ -2,6 +2,7 @@ import type { AttributeValue } from "@opentelemetry/api";
 import type { ModunaOTELConfig } from "../interface/ModunaOTELConfig.js";
 import type { TraceCallback } from "../types/TraceCallback.js";
 import type { ModunaTelemetryMetadata, ModunaTraceContext } from "../types/TraceContext.js";
+import type { ModunaLangChainCallbackHandlerConfig } from "./ModunaLangChainCallbackHandler.js";
 import { ModunaLangChainCallbackHandler } from "./ModunaLangChainCallbackHandler.js";
 /**
  * Vercel AI SDK compatible telemetry settings.
@@ -58,16 +59,18 @@ export declare class ModunaOTEL {
      * Creates a LangChain callback handler for per-call usage.
      *
      * @param context Default conversation or session identifiers.
+     * @param config Optional LangChain handler settings.
      * @returns LangChain callback handler that emits Moduna spans.
      */
-    langChainHandler(context?: ModunaTraceContext): ModunaLangChainCallbackHandler;
+    langChainHandler(context?: ModunaTraceContext, config?: Omit<ModunaLangChainCallbackHandlerConfig, "traceContext">): ModunaLangChainCallbackHandler;
     /**
      * Registers a LangChain callback handler for all LangChain runs.
      *
      * @param context Default conversation or session identifiers.
+     * @param config Optional LangChain handler settings.
      * @returns The globally registered LangChain callback handler.
      */
-    registerGlobalLangChainHandler(context?: ModunaTraceContext): ModunaLangChainCallbackHandler;
+    registerGlobalLangChainHandler(context?: ModunaTraceContext, config?: Omit<ModunaLangChainCallbackHandlerConfig, "traceContext">): ModunaLangChainCallbackHandler;
     /**
      * Instruments a callback with a Moduna span.
      *

package/dist/services/ModunaOTEL.js

@@ -133,10 +133,12 @@ export class ModunaOTEL {
      * Creates a LangChain callback handler for per-call usage.
      *
      * @param context Default conversation or session identifiers.
+     * @param config Optional LangChain handler settings.
      * @returns LangChain callback handler that emits Moduna spans.
      */
-    langChainHandler(context = {}) {
+    langChainHandler(context = {}, config = {}) {
         return new ModunaLangChainCallbackHandler({
+            ...config,
             traceContext: context,
         });
     }
@@ -144,10 +146,11 @@ export class ModunaOTEL {
      * Registers a LangChain callback handler for all LangChain runs.
      *
      * @param context Default conversation or session identifiers.
+     * @param config Optional LangChain handler settings.
      * @returns The globally registered LangChain callback handler.
      */
-    registerGlobalLangChainHandler(context = {}) {
-        const handler = this.langChainHandler(context);
+    registerGlobalLangChainHandler(context = {}, config = {}) {
+        const handler = this.langChainHandler(context, config);
         registerGlobalModunaLangChainHandler(handler);
         return handler;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moduna/otel",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "private": false,
   "description": "One-line OpenTelemetry setup for Moduna AI traces.",
   "license": "MIT",
@@ -35,10 +35,32 @@
     "@opentelemetry/exporter-trace-otlp-http": "^0.218.0",
     "@opentelemetry/resources": "^2.7.1",
     "@opentelemetry/sdk-node": "^0.218.0",
-    "@opentelemetry/semantic-conventions": "^1.41.1",
+    "@opentelemetry/semantic-conventions": "^1.41.1"
+  },
+  "peerDependencies": {
+    "@ai-sdk/google": "^3.0.75",
+    "@langchain/google-genai": "^2.1.30",
+    "ai": "^6.0.184",
     "langchain": "^1.4.0",
     "openai": "^6.38.0"
   },
+  "peerDependenciesMeta": {
+    "@ai-sdk/google": {
+      "optional": true
+    },
+    "@langchain/google-genai": {
+      "optional": true
+    },
+    "ai": {
+      "optional": true
+    },
+    "langchain": {
+      "optional": true
+    },
+    "openai": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@ai-sdk/google": "^3.0.75",
     "@changesets/cli": "^2.31.0",