使用 Microsoft Foundry 和 Azure 監視器 追蹤 LangChain 和 LangGraph 應用程式

使用 langchain-azure-ai 整合套件，從 LangChain 和 LangGraph 應用程式中輸出 OpenTelemetry 追蹤，並匯入 Azure 應用程式 Insights。 在本文中，您將設定 AzureAIOpenTelemetryTracer，將其附加到可執行檔，並在 Azure 監視器 中查看追蹤。

追蹤器會輸出代理執行、模型呼叫、工具執行及檢索操作的跨度。 你可以用它來執行完全本地化的應用程式、呼叫 Foundry Agent Service 的混合流程，或多代理的 LangGraph 解決方案。

先決條件

• 一個 Azure 訂閱。 免費創建一個。
• Foundry 專案。
• 一個已部署Azure OpenAI 聊天模型（例如 gpt-4.1）。
• Python 3.10 或更新版本。
• Azure CLI已登入（az login），所以 DefaultAzureCredential 可以進行認證。

配置你的環境

安裝所需套件：

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

請設定本文中使用的環境變數：

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..."

若要控制訊息與工具呼叫的內容是否被記錄在追蹤中，請傳遞 enable_content_recording 給 AzureAIOpenTelemetryTracer 建構子。 內容錄製預設已啟用。

製作追蹤器

建立一個追蹤器實例，並在工作流程中重複使用。

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,
)

此片段的功能：配置一個追蹤功能，從 Foundry 專案端點解析相關的應用程式洞察連接字串，並啟用 LangGraph 節點的追蹤功能。 呼叫代理時使用 agent_id 參數來設定屬性 gen_ai.agent.id 。 參數 name 設定 OpenTelemetry 追蹤器的名稱。

追蹤器支援生產工作流程的共通控制措施：

• 可通過 connection_string 以鎖定特定的 Application Insights 資源，或透過設定環境變數 APPLICATION_INSIGHTS_CONNECTION_STRING。
• trace_all_langgraph_nodes=True預設設定為追蹤所有節點。
• 使用節點元資料，例如otel_trace: Trueotel_trace: False包含或跳過特定節點。
• 當您的訊息在自訂狀態形狀底下為巢狀時，請使用message_keys和message_paths 範例，例如，chat_history。

參考資料：

• AzureAIOpenTelemetryTracer

追蹤代理人

先用一個最小的 LangChain 代理，這樣你才能快速驗證追蹤。 對於 LangGraph，將追蹤器 with_config 附加在已編譯的圖上。

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.

這段內容 ：建立一個簡單的 LangGraph 代理，附加追蹤器，並以訊息呼叫代理。

參考資料：

• LangGraph
• OpenTelemetry

追蹤可執行的 LangChain

先從最簡單的 LangChain 流程開始，這樣你才能快速驗證追蹤。

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.

此程式碼片段的作用是： 運行標準的 LangChain 管線，並透過 AzureAIOpenTelemetryTracer 將聊天追蹤傳送到 OpenTelemetry。

參考資料：

• AzureAIChatCompletionsModel
• ChatPromptTemplate

描繪 LangGraph 圖

對於 LangGraph，將追蹤器 with_config 附加在已編譯的圖上。 此片段重用了先前範例中的 model 和 tracer。

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)
)

接著，你可以像平常一樣執行這張圖表：

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.

這個程式碼片段的作用： 建立一個簡單的 LangGraph 應用程式，標記節點以供追蹤，並將invoke_agent和模型/工具跨度發出至相同的追蹤中。

參考資料：

• LangGraph
• OpenTelemetry

了解痕跡結構

追蹤器發射的跨度遵循 OpenTelemetry GenAI 語意慣例。 每種跨度類型使用特定的 gen_ai.operation.name 數值：

跨度也具備以下關鍵特性：

• gen_ai.agent.name — 代理或節點名稱。
• gen_ai.agent.id — 由 agent_id 建構子參數設定。
• gen_ai.agent.description — 代理人描述。
• gen_ai.provider.name — 模型提供者（例如， openai）。
• gen_ai.request.model — 用於推論的模型名稱。
• gen_ai.conversation.id — 執行緒或會話識別碼（如有）。
• gen_ai.usage.input_tokens / gen_ai.usage.output_tokens — 模型回覆的詞元計數。
• gen_ai.input.messages / gen_ai.output.messages — 訊息內容（啟用內容錄製時）。

追蹤器的解析方式 gen_ai.agent.name

追蹤器依序從第一個非空值解析代理人名稱：

1. agent_name 在節點的元資料中。
2. langgraph_node 在節點元資料中（由 LangGraph 自動設定）。
3. agent_type 在節點的元資料中。
4. name 來自 LangChain 回調中的關鍵字引數。
5. langgraph_path （最後一個元素）如果上述是通用的佔位符。
6. 序列化鏈 ID 或類別名稱。
7. 來自name 建構子 (回退預設) 的AzureAIOpenTelemetryTracer參數。

追蹤器的解析方式 gen_ai.agent.id

追蹤器從以下位置解析 Agent 識別碼：

1. agent_id在節點中繼資料 (每個節點覆寫) 中。
2. agent_id建構參數（所有跨度的預設參數）。

以節點元資料自訂屬性

你可以用 LangGraph 元資料設定 agent_name、 agent_id和 agent_description 每個節點。 任何以 開頭的 gen_ai. 元資料金鑰也會以 span 屬性轉發。

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)

使用 LangGraph 時，你也可以在圖定義中設定每個節點的元資料：

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

參考資料：

• OpenTelemetry GenAI Agent 跨度
• OpenTelemetry GenAI Spans

在 Azure 監視器 中查看追蹤

追蹤訊息會傳送到 Azure 應用程式 Insights，並可使用 Azure 監視器 進行查詢。

1. 前往Azure入口。

2. 導航到你設定的 Azure 應用程式 Insights。

3. 在左側導覽欄中，選擇 「調查>代理人（預覽）」。

4. 你會看到一個儀表板，顯示代理、模型和工具執行。 使用此視圖來了解您代理人的整體活動。

5. 選取使用 Agent 執行作業檢視追蹤。。 側面板顯示所有由代理執行產生的痕跡。

   

6. 選擇一條走線。 你應該看看細節。

   

在 Foundry 控制平面查看追蹤記錄

如果你部署了 LangGraph 或 LangChain 解決方案，可以在 Foundry Control Plane 註冊該部署，以獲得可視性與治理權限。

請將您的應用程式註冊到 Foundry Control Plane ，以便在 Foundry 入口網站查看痕跡。

請遵循以下步驟：

1. 確保您符合使用 Foundry Control Plane 客製化代理能力的要求：

   • 一個 在你的 Foundry 資源中設定的 AI 閘道。 Foundry 使用 Azure API 管理 來註冊代理為 API。

   • 一個你部署並透過可達的端點公開的代理程式。 端點可以是公開端點，也可以是可從你在其上佈建 Foundry 資源的網路中可達的端點。

2. 確保你在 專案中有可觀察性設定。

3. 設定類別 AzureAIOpenTelemetryTracer時，務必使用你想讓代理註冊的專案端點。 確保你設定 agent_id。

4. 前往 Foundry 入口網站。

5. 在工具列中，選擇 操作。

6. 在 概覽 面板中，選擇 註冊代理人。

7. 註冊精靈出現了。 首先，填寫你想註冊的經紀人的詳細資料。

   • 代理 URL：代理執行並接收請求的端點（URL）。
   • 協議：您的代理所支援的通訊協議。
   • OpenTelemetry Agent ID： agent_id 你在類別中設定 AzureAIOpenTelemetryTracer 的參數。
   • Project：你設定為接收 AzureAIOpenTelemetryTracer 類別追蹤的專案。
   • 代理人名稱：代理人的名稱（可以與 agent_id相同）。

8. 叫用 Agent 以確認它已執行。

9. 在工具列中，選擇 操作。

10. 在左側窗格，選擇 資產。

11. 選擇你建立的代理人。

12. Traces 區塊顯示對代理程式端點每次進行的 HTTP 呼叫皆會有一項對應的記錄。

    欲查看詳情，請選擇一條條目。

    

故障排除

• 如果沒有發現痕跡，請確認是否 connection_string 已設定好，或是你的專案端點是否公開遙測資料。
• 若訊息內容顯示為已編寫，則在enable_content_recording=True建構子中設定AzureAIOpenTelemetryTracer。
• 若缺少某些 LangGraph 節點，則設定 trace_all_langgraph_nodes=True 或新增節點元資料 otel_trace: True。

相關內容

• 開始使用 langchain-azure-ai
• 使用 LangGraph 搭配代理服務
• 為代理框架設定追蹤整合