LangChain | Opik Documentation | Opik Documentation

Opik provides seamless integration with LangChain through the opik-langchain package, allowing you to trace, monitor, and debug your LangChain applications.

Features

Comprehensive Tracing: Automatically trace LLM calls, chains, tools, retrievers, and agents
Hierarchical Visualization: View your LangChain execution as a structured trace with parent-child relationships
Detailed Metadata Capture: Record model names, prompts, completions, usage statistics, and custom metadata
Error Handling: Capture and visualize errors at every step of your LangChain execution
Custom Tagging: Add custom tags to organize and filter your traces

Installation

Option 1: Using npm

$ npm install opik-langchain

Option 2: Using yarn

$ yarn add opik-langchain

Requirements

Node.js ≥ 18
LangChain (@langchain/core ≥ 0.3.42)
Opik SDK (automatically installed as a dependency)

Basic Usage

Using with LLM Calls

You can add the OpikCallbackHandler in two ways in LangChain: at construction time and at execution time. Here’s how to use both approaches:

1 import { OpikCallbackHandler } from "opik-langchain";
2 import { ChatOpenAI } from "@langchain/openai";
3 
4 // Create the Opik callback handler
5 const opikHandler = new OpikCallbackHandler();
6 
7 // Option 1: Add the handler at model initialization time
8 const llm = new ChatOpenAI({
9   callbacks: [opikHandler], // Will be used for all calls to this model
10 });
11 
12 // Run LLM
13 const response = await llm.invoke("Hello, how can you help me today?");
14 
15 // Option 2: Add the handler at invocation time (or both)
16 const llmWithoutHandler = new ChatOpenAI();
17 const response2 = await llmWithoutHandler.invoke("What's the weather like today?", {
18   callbacks: [opikHandler], // Will be used just for this specific call
19 });
20 
21 // You can also combine both approaches
22 const anotherResponse = await llm.invoke("Tell me a joke", {
23   callbacks: [opikHandler], // Will use both the constructor handler and this one
24 });
25 
26 // Ensure all traces are sent before your app terminates
27 await opikHandler.flushAsync();

Configuring for All Components

You can also set up the handler to be used across all LangChain components in your application:

1 import { OpikCallbackHandler } from "opik-langchain";
2 import { ChatOpenAI } from "@langchain/openai";
3 import { PromptTemplate } from "@langchain/core/prompts";
4 import { LLMChain } from "langchain/chains";
5 import { setGlobalCallbacks } from "@langchain/core/callbacks/manager";
6 
7 // Create the Opik callback handler
8 const opikHandler = new OpikCallbackHandler({
9   tags: ["global"],
10   projectName: "langchain-app",
11 });
12 
13 // Set as global handler (will be used for all LangChain components)
14 setGlobalCallbacks([opikHandler]);
15 
16 // These components will now automatically use the global handler
17 const llm = new ChatOpenAI();
18 const template = PromptTemplate.fromTemplate("Answer this question: {question}");
19 const chain = new LLMChain({ llm, prompt: template });
20 
21 // Global handlers are used automatically
22 const result = await chain.call({ question: "What is 2+2?" });
23 
24 // Flush before your app exits
25 await opikHandler.flushAsync();

Advanced Configuration

The OpikCallbackHandler constructor accepts several options to customize the integration:

1 const opikHandler = new OpikCallbackHandler({
2   // Optional array of tags to apply to all traces
3   tags: ["langchain", "production", "user-query"],
4 
5   // Optional metadata to include with all traces
6   metadata: {
7     environment: "production",
8     version: "1.0.0",
9   },
10 
11   // Optional project name for Opik
12   projectName: "my-langchain-project",
13 
14   // Optional pre-configured Opik client
15   // If not provided, a new client will be created automatically
16   client: customOpikClient,
17 });

Troubleshooting

Missing Traces: Ensure you’re providing the OpikCallbackHandler to both the component constructor and each invoke call.

Incomplete Hierarchies: For proper parent-child relationships, use the same handler instance throughout your application.

Performance Impact: The Opik integration adds minimal overhead to your LangChain application.

1	import { OpikCallbackHandler } from "opik-langchain";
2	import { ChatOpenAI } from "@langchain/openai";
3
4	// Create the Opik callback handler
5	const opikHandler = new OpikCallbackHandler();
6
7	// Option 1: Add the handler at model initialization time
8	const llm = new ChatOpenAI({
9	callbacks: [opikHandler], // Will be used for all calls to this model
10	});
11
12	// Run LLM
13	const response = await llm.invoke("Hello, how can you help me today?");
14
15	// Option 2: Add the handler at invocation time (or both)
16	const llmWithoutHandler = new ChatOpenAI();
17	const response2 = await llmWithoutHandler.invoke("What's the weather like today?", {
18	callbacks: [opikHandler], // Will be used just for this specific call
19	});
20
21	// You can also combine both approaches
22	const anotherResponse = await llm.invoke("Tell me a joke", {
23	callbacks: [opikHandler], // Will use both the constructor handler and this one
24	});
25
26	// Ensure all traces are sent before your app terminates
27	await opikHandler.flushAsync();

1	import { OpikCallbackHandler } from "opik-langchain";
2	import { ChatOpenAI } from "@langchain/openai";
3	import { PromptTemplate } from "@langchain/core/prompts";
4	import { LLMChain } from "langchain/chains";
5	import { setGlobalCallbacks } from "@langchain/core/callbacks/manager";
6
7	// Create the Opik callback handler
8	const opikHandler = new OpikCallbackHandler({
9	tags: ["global"],
10	projectName: "langchain-app",
11	});
12
13	// Set as global handler (will be used for all LangChain components)
14	setGlobalCallbacks([opikHandler]);
15
16	// These components will now automatically use the global handler
17	const llm = new ChatOpenAI();
18	const template = PromptTemplate.fromTemplate("Answer this question: {question}");
19	const chain = new LLMChain({ llm, prompt: template });
20
21	// Global handlers are used automatically
22	const result = await chain.call({ question: "What is 2+2?" });
23
24	// Flush before your app exits
25	await opikHandler.flushAsync();

1	const opikHandler = new OpikCallbackHandler({
2	// Optional array of tags to apply to all traces
3	tags: ["langchain", "production", "user-query"],
4
5	// Optional metadata to include with all traces
6	metadata: {
7	environment: "production",
8	version: "1.0.0",
9	},
10
11	// Optional project name for Opik
12	projectName: "my-langchain-project",
13
14	// Optional pre-configured Opik client
15	// If not provided, a new client will be created automatically
16	client: customOpikClient,
17	});