LangChain.js

npm install @langchain/core @langchain/openai \
  @arizeai/openinference-instrumentation-langchain \
  @arizeai/openinference-semantic-conventions \
  @opentelemetry/api \
  @opentelemetry/exporter-trace-otlp-proto \
  @opentelemetry/instrumentation \
  @opentelemetry/resources \
  @opentelemetry/sdk-trace-base \
  @opentelemetry/sdk-trace-node \
  @opentelemetry/semantic-conventions

export ARIZE_SPACE_ID="<your-space-id>"
export ARIZE_API_KEY="<your-api-key>"
export ARIZE_PROJECT_NAME="langchain-js-tracing-example"
export OPENAI_API_KEY="<your-openai-api-key>"

// instrumentation.ts
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
import { resourceFromAttributes } from "@opentelemetry/resources";
import { SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base";
import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
import {
  SEMRESATTRS_PROJECT_NAME,
} from "@arizeai/openinference-semantic-conventions";
import {
  LangChainInstrumentation,
} from "@arizeai/openinference-instrumentation-langchain";
import * as CallbackManagerModule from "@langchain/core/callbacks/manager";

const projectName =
  process.env.ARIZE_PROJECT_NAME ?? "langchain-js-tracing-example";

export const provider = new NodeTracerProvider({
  resource: resourceFromAttributes({
    [ATTR_SERVICE_NAME]: projectName,
    [SEMRESATTRS_PROJECT_NAME]: projectName,
  }),
  spanProcessors: [
    new SimpleSpanProcessor(
      new OTLPTraceExporter({
        url: "https://otlp.arize.com/v1/traces",
        headers: {
          "arize-space-id": process.env.ARIZE_SPACE_ID ?? "",
          "arize-api-key": process.env.ARIZE_API_KEY ?? "",
        },
      }),
    ),
  ],
});

provider.register();

const instrumentation = new LangChainInstrumentation();
instrumentation.manuallyInstrument(CallbackManagerModule);

console.log("Arize AX tracing initialized for LangChain.js.");

// example.ts

// Importing instrumentation first ensures tracing is set up before any
// LangChain client is created.
import { provider } from "./instrumentation";

import { ChatOpenAI } from "@langchain/openai";
import { ChatPromptTemplate } from "@langchain/core/prompts";
import { StringOutputParser } from "@langchain/core/output_parsers";

// ChatOpenAI reads OPENAI_API_KEY from the environment.
const model = new ChatOpenAI({ model: "gpt-5" });
const prompt = ChatPromptTemplate.fromTemplate(
  "Answer the question concisely.\nQuestion: {question}\nAnswer:",
);
const chain = prompt.pipe(model).pipe(new StringOutputParser());

const result = await chain.invoke({
  question: "Why is the ocean salty? Answer in two sentences.",
});

console.log(result);

// Flush any pending spans before the process exits.
await provider.forceFlush();

import {
  ReadableSpan,
  SimpleSpanProcessor,
} from "@opentelemetry/sdk-trace-base";
import { SemanticConventions } from "@arizeai/openinference-semantic-conventions";

function isOpenInferenceSpan(span: ReadableSpan): boolean {
  return (
    typeof span.attributes[SemanticConventions.OPENINFERENCE_SPAN_KIND] ===
    "string"
  );
}

class OpenInferenceFilteringSpanProcessor extends SimpleSpanProcessor {
  onEnd(span: ReadableSpan): void {
    if (!isOpenInferenceSpan(span)) return;
    super.onEnd(span);
  }
}

// then in spanProcessors:
new OpenInferenceFilteringSpanProcessor(
  new OTLPTraceExporter({ /* ... */ }),
);

// root-aware-processor.ts
import { Context } from "@opentelemetry/api";
import {
  BatchSpanProcessor,
  ReadableSpan,
  Span,
  SpanExporter,
} from "@opentelemetry/sdk-trace-base";
import { getSession } from "@arizeai/openinference-core";
import {
  SemanticConventions,
  SESSION_ID,
} from "@arizeai/openinference-semantic-conventions";
import { LRUCache } from "lru-cache";

// Top-level LangChain / LangGraph runnable names. `LangGraph` is the
// `lc_name()` of a compiled Pregel graph (returned by `createReactAgent`
// and friends), `RunnableSequence` is the typical chain root for
// `prompt.pipe(model).pipe(parser)`-style chains, and `AgentExecutor`
// covers legacy LangChain agents. Match on the first whitespace-delimited
// token so suffixed run names (e.g. `RunnableSequence my-chain`) still hit.
const ROOT_OI_SPAN_PREFIXES = [
  "LangGraph",
  "RunnableSequence",
  "AgentExecutor",
];

function isRootOISpanByName(spanName: string): boolean {
  const head = spanName.split(" ")[0];
  return ROOT_OI_SPAN_PREFIXES.some(
    (prefix) => head === prefix || head.startsWith(prefix + " "),
  );
}

function isOpenInferenceSpan(span: ReadableSpan): boolean {
  return (
    typeof span.attributes[SemanticConventions.OPENINFERENCE_SPAN_KIND] ===
    "string"
  );
}

interface RootAwareConfig {
  exporter: SpanExporter;
  /** LRU size for tracking which traces have a promoted root. */
  cacheSize?: number;
}

/**
 * Filters non-OpenInference spans (HTTP, fetch, etc.) and promotes the
 * first LangChain span in each trace to root by clearing its parent IDs.
 * Also propagates session ids from context onto every emitted span.
 */
export class RootAwareOpenInferenceProcessor extends BatchSpanProcessor {
  private traceIds: LRUCache<string, boolean>;

  constructor(config: RootAwareConfig) {
    super(config.exporter);
    this.traceIds = new LRUCache({ max: config.cacheSize ?? 1000 });
  }

  onStart(span: Span, parentContext: Context): void {
    const session = getSession(parentContext);
    if (session?.sessionId) {
      span.setAttribute(SESSION_ID, session.sessionId);
    }

    const traceId = span.spanContext().traceId;
    if (
      isRootOISpanByName(span.name) &&
      !this.traceIds.has(traceId)
    ) {
      // parentSpanId is readonly on the public Span type; cast to clear.
      (span as unknown as { parentSpanId?: string }).parentSpanId =
        undefined;
      (span as unknown as { parentSpanContext?: unknown })
        .parentSpanContext = undefined;
      this.traceIds.set(traceId, true);
    }

    super.onStart(span, parentContext);
  }

  onEnd(span: ReadableSpan): void {
    if (!isOpenInferenceSpan(span)) return;
    super.onEnd(span);
  }

  shutdown(): Promise<void> {
    this.traceIds.clear();
    return super.shutdown();
  }
}

import { RootAwareOpenInferenceProcessor } from "./root-aware-processor";

spanProcessors: [
  new RootAwareOpenInferenceProcessor({
    exporter: new OTLPTraceExporter({
      url: "https://otlp.arize.com/v1/traces",
      headers: {
        "arize-space-id": process.env.ARIZE_SPACE_ID ?? "",
        "arize-api-key": process.env.ARIZE_API_KEY ?? "",
      },
    }),
  }),
],