Trace LangChain and LangGraph apps with Microsoft Foundry and Azure Monitor

Use the langchain-azure-ai integration package to emit OpenTelemetry traces from LangChain and LangGraph applications and sink them in Azure Application Insights. In this article, you configure AzureAIOpenTelemetryTracer, attach it to your runnable, and inspect traces in Azure Monitor.

The tracer emits spans for agent execution, model calls, tool execution, and retrieval operations. You can use it for apps that run fully local, hybrid flows that call Foundry Agent Service, or multi-agent LangGraph solutions.

Prerequisites

  • An Azure subscription. Create one for free.
  • A Foundry project.
  • A deployed Azure OpenAI chat model (for example, gpt-4.1).
  • Python 3.11 or later.
  • Azure CLI signed in (az login) so DefaultAzureCredential can authenticate.

Configure your environment

Install required packages:

pip install -U "langchain-azure-ai[opentelemetry]" azure-identity

Set the environment variables used in this article:

import os

# Option 1: Project endpoint (recommended)
os.environ["FOUNDRY_PROJECT_ENDPOINT"] = (
	"https://<resource>.services.ai.azure.com/api/projects/<project>"
)

# Option 2: Direct OpenAI-compatible endpoint + API key
os.environ["OPENAI_BASE_URL"] = (
	"https://<resource>.services.ai.azure.com/openai/v1"
)
os.environ["OPENAI_API_KEY"] = "<your-api-key>"
os.environ["APPLICATION_INSIGHTS_CONNECTION_STRING"] = "InstrumentationKey=0ab1c2d3..."

To control whether content from messages and tool calls is recorded in the trace, pass enable_content_recording to the AzureAIOpenTelemetryTracer constructor. Content recording is enabled by default.

Tip

Set enable_content_recording=False in the AzureAIOpenTelemetryTracer constructor to redact message content and tool call arguments from traces.

Create the tracer

Create one tracer instance and reuse it across your workflow.

import os

from azure.identity import DefaultAzureCredential
from langchain_azure_ai.callbacks.tracers import AzureAIOpenTelemetryTracer

tracer = AzureAIOpenTelemetryTracer(
	project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
	credential=DefaultAzureCredential(),
	name="langchain-tracing-sample",
	agent_id="support-bot",
	trace_all_langgraph_nodes=True,
)

What this snippet does: Configures a tracer that resolves the associated Application Insights connection string from your Foundry project endpoint and enables tracing for LangGraph nodes. Use the agent_id parameter to set the attribute gen_ai.agent.id when invoking agents. The name parameter sets the OpenTelemetry tracer name.

The tracer supports common controls for production workflows:

  • Pass connection_string to target a specific Application Insights resource or configure the environment variable APPLICATION_INSIGHTS_CONNECTION_STRING.
  • Set trace_all_langgraph_nodes=True to trace all nodes by default.
  • Use node metadata like otel_trace: True or otel_trace: False to include or skip specific nodes.
  • Use message_keys and message_paths when your messages are nested under a custom state shape, for example chat_history.

Reference:

Trace an agent

Start with a minimal LangChain agent so you can verify tracing quickly. For LangGraph, attach the tracer with with_config on the compiled graph.

from langchain.agents import create_agent

agent = create_agent(
    model="azure_ai:gpt-5.2", 
    system_prompt="You're an informational agent. Answer questions cheerfully.", 
).with_config(
    {"callbacks": [tracer]}
)

response = agent.invoke({"messages": "what's your name?"})
response["messages"][-1].pretty_print()
================================== Ai Message ==================================

I’m ChatGPT, your AI assistant.

What this snippet does: Creates a simple LangGraph agent, attaches the tracer, and invokes the agent with a message.

Reference:

Trace a LangChain runnable

Start with a minimal LangChain flow so you can verify tracing quickly.

import os

from azure.identity import DefaultAzureCredential
from langchain_core.prompts import ChatPromptTemplate
from langchain_azure_ai.chat_models import AzureAIChatCompletionsModel

model = AzureAIChatCompletionsModel(
	project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
	credential=DefaultAzureCredential(),
	model="gpt-4.1",
)

prompt = ChatPromptTemplate.from_template(
	"You are concise. Answer in one sentence: {question}"
)
chain = prompt | model

response = chain.invoke(
	{"question": "What does OpenTelemetry help me do?"},
	config={"callbacks": [tracer]},
)

print(response.content)
OpenTelemetry helps you observe requests, latency, dependencies, and failures across your AI workflow.

What this snippet does: Runs a standard LangChain pipeline and sends chat spans to OpenTelemetry through AzureAIOpenTelemetryTracer.

Reference:

Trace a LangGraph graph

For LangGraph, attach the tracer by using with_config on the compiled graph. This snippet reuses model and tracer from earlier examples.

from langgraph.graph import END, START, MessagesState, StateGraph
from langgraph.prebuilt import ToolNode
from langgraph.checkpoint.memory import MemorySaver
from langchain_core.tools import tool
from langchain_azure_ai.utils.agents import pretty_print

@tool
def play_song_on_spotify(song: str):
    """Play a song on Spotify"""
    # Integrate with Spotify API here.
    return f"Successfully played {song} on Spotify!"

@tool
def play_song_on_apple(song: str):
    """Play a song on Apple Music"""
    # Integrate with Apple Music API here.
    return f"Successfully played {song} on Apple Music!"

tool_node = ToolNode([play_song_on_apple, play_song_on_spotify])
model_with_tools = model.bind_tools([play_song_on_apple, play_song_on_spotify])

def should_continue(state: MessagesState):
    messages = state["messages"]
    last_message = messages[-1]
    return "continue" if getattr(last_message, "tool_calls", None) else "end"

def call_model(state: MessagesState):
    messages = state["messages"]
    response = model_with_tools.invoke(messages)
    return {"messages": [response]}

memory = MemorySaver()
workflow = (
    StateGraph(MessagesState)
    .add_node("agent", call_model)
    .add_node("action", tool_node)
    .add_edge(START, "agent")
    .add_conditional_edges(
        "agent",
        should_continue,
        {
            "continue": "action",
            "end": END,
        },
    )
    .add_edge("action", "agent")
    .compile(checkpointer=memory)
)

Then, you can run the graph as usual:

from langchain_core.messages import HumanMessage

config = {"configurable": {"thread_id": "1"}, "callbacks": [tracer]}
message = HumanMessage(content="Can you play Taylor Swift's most popular song?")

result = workflow.invoke({"messages": [message]}, config)
pretty_print(result)
================================ Human Message =================================

Can you play Taylor Swift's most popular song?
================================== Ai Message ==================================
Tool Calls:
  play_song_on_spotify (call_xxx)
 Call ID: call_xxx
  Args:
    song: Anti-Hero
================================= Tool Message =================================
Name: play_song_on_spotify

Successfully played Anti-Hero on Spotify!
================================== Ai Message ==================================

I played Taylor Swift's popular song "Anti-Hero" on Spotify.

What this snippet does: Creates a simple LangGraph app, marks the node for tracing, and emits invoke_agent and model/tool spans into the same trace.

Reference:

Understand trace structure

The tracer emits spans that follow the OpenTelemetry GenAI semantic conventions. Each span type uses a specific gen_ai.operation.name value:

Span type gen_ai.operation.name Description
Agent or chain invocation invoke_agent Each LangGraph node or chain step. Span name is invoke_agent {gen_ai.agent.name}.
Chat model call chat LLM inference requests. Span name is chat {gen_ai.request.model}.
Text completion text_completion Non-chat LLM calls.
Tool execution execute_tool Tool calls triggered by the model. Span name is execute_tool {gen_ai.tool.name}.
Retriever execute_tool Retrieval operations from vector stores or search.

Spans also carry these key attributes:

  • gen_ai.agent.name — The agent or node name.
  • gen_ai.agent.id — Set from the agent_id constructor parameter.
  • gen_ai.agent.description — A description of the agent.
  • gen_ai.provider.name — The model provider (for example, openai).
  • gen_ai.request.model — The model name used for inference.
  • gen_ai.conversation.id — Thread or session identifier, when available.
  • gen_ai.usage.input_tokens / gen_ai.usage.output_tokens — Token counts from model responses.
  • gen_ai.input.messages / gen_ai.output.messages — Message content (when content recording is enabled).

How the tracer resolves gen_ai.agent.name

The tracer resolves the agent name from the first non-empty value in this order:

  1. agent_name in the node metadata.
  2. langgraph_node in the node metadata (set automatically by LangGraph).
  3. agent_type in the node metadata.
  4. The name keyword argument from the LangChain callback.
  5. langgraph_path (last element) if the preceding values are generic placeholders.
  6. The serialized chain ID or class name.
  7. The name parameter from the AzureAIOpenTelemetryTracer constructor (fallback default).

How the tracer resolves gen_ai.agent.id

The tracer resolves the agent ID from:

  1. agent_id in the node metadata (per-node override).
  2. The agent_id constructor parameter (default for all spans).

Customize attributes with node metadata

Set agent_name, agent_id, and agent_description for each node by using LangGraph metadata. Any metadata key starting with gen_ai. is also forwarded as a span attribute.

config = {
    "configurable": {"thread_id": "session-abc-123"},
    "callbacks": [tracer],
    "metadata": {
        "agent_name": "support-bot",
        "agent_id": "support-bot-v2",
        "agent_description": "Handles customer support requests",
    },
}
result = workflow.invoke({"messages": [message]}, config)

When you use LangGraph, you can also set metadata for each node in the graph definition:

workflow = StateGraph(MessagesState)
workflow.add_node(
    "planner",
    planner_fn,
    metadata={
        "agent_name": "PlannerAgent",
        "agent_id": "planner-v1",
        "otel_agent_span": True,
    },
)

Reference:

View traces in Azure Monitor

Azure Application Insights receives traces, and you can query them by using Azure Monitor:

  1. Go to the Azure portal.

  2. Navigate to the Azure Application Insights you configured.

  3. In the left navigation bar, select Investigate > Agents (Preview).

  4. You see a dashboard that shows agent, model, and tool executions. Use this view to understand the overall activity of your agents.

  5. Select View Traces with Agent Runs. The side panel shows all the traces generated by agent runs.

    Screenshot showing the Agents (Preview) section in Azure Monitor displaying multiple runs.

  6. Select one of the traces. You see the details.

    Screenshot showing the trace details of the selected run.

View traces in Foundry Control Plane

Register a LangGraph or LangChain agent that runs outside Foundry as an external agent to link its telemetry to Foundry. Registration doesn't move or host your agent's runtime. For telemetry setup and access requirements, see Register external agents for observability and evaluation.

Important

You can no longer add new Control Plane custom agents. For an existing custom agent, follow Migrate custom agents to external agents. Preserve its OpenTelemetry agent ID, gateway, and invocation route. Don't unregister or delete the original custom agent or its API Management API during migration.

To register an external agent in the portal:

  1. Open your project in the Foundry portal and select Build > Agents.

  2. Select New agent > Link external agent.

    Screenshot of the New agent menu with the Link external agent option.

  3. Enter Agent name and, optionally, Description.

  4. Enter the OTel agent ID that matches the gen_ai.agent.id emitted by your instrumentation.

    This field is optional and defaults to the agent name if you leave it blank. The value must match the ID in your telemetry to associate traces with the registered agent.

  5. Select Register.

    Screenshot of the Register external agent form with Agent name, Description, OTel agent ID, and Register controls.

After your agent emits telemetry, select Manage > Fleet > Agents, select the agent, and open Traces. For details, see View agent traces.

Troubleshoot

  • If no traces appear, verify that either connection_string is configured or your project endpoint exposes telemetry.
  • If message content appears redacted, set enable_content_recording=True in the AzureAIOpenTelemetryTracer constructor.
  • If some LangGraph nodes are missing, set trace_all_langgraph_nodes=True or add node metadata otel_trace: True.