Trace LangChain- und LangGraph-Apps mit Microsoft Foundry und Azure Monitor

Verwenden Sie das integrationspaket langchain-azure-ai, um OpenTelemetry-Ablaufverfolgungen aus LangChain- und LangGraph-Anwendungen auszugeben und sie in Azure-Anwendung Insights zu senken. In diesem Artikel konfigurieren Sie AzureAIOpenTelemetryTracer, binden es an Ihr ausführbares Modul und prüfen Sie die Ablaufverfolgungen in Azure Monitor.

Der Tracer emittiert Spanne für die Agentausführung, Modellaufrufe, Toolausführung und Abrufvorgänge. Sie können es für Apps verwenden, die vollständig lokal ausgeführt werden, Hybridflüsse, die den Foundry Agent Service aufrufen, oder für Multi-Agent LangGraph-Lösungen.

Voraussetzungen

• Ein Azure-Abonnement. Erstellen Sie eine kostenlos.
• Ein Foundry-Projekt.
• Ein bereitgestelltes Azure OpenAI-Chatmodell (z. B. gpt-4.1).
• Python 3.10 oder höher.
• Azure CLI ist angemeldet (az login), damit DefaultAzureCredential sich authentifizieren kann.

Konfigurieren Ihrer Umgebung

Erforderliche Pakete installieren:

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

Legen Sie die in diesem Artikel verwendeten Umgebungsvariablen fest:

import os

# Option 1: Project endpoint (recommended)
os.environ["AZURE_AI_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..."

Um zu steuern, ob Inhalte aus Nachrichten und Toolaufrufen in der Ablaufverfolgung aufgezeichnet werden, übergeben Sie enable_content_recording an den AzureAIOpenTelemetryTracer-Konstruktor. Die Inhaltsaufzeichnung ist standardmäßig aktiviert.

Erstellen des Tracers

Erstellen Sie eine Tracer-Instanz und verwenden Sie diese im gesamten Workflow erneut.

import os

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

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

Was dieser Code-Schnipsel tut: Er konfiguriert einen Tracer, der die zugehörige Verbindung(s)zeichenfolge von Application Insights von Ihrem Foundry-Projekt-Endpunkt auflöst und das Tracing für LangGraph-Knoten aktiviert. Verwenden Sie den Parameter agent_id, um das Attribut gen_ai.agent.id beim Aufrufen von Agenten festzulegen. Der name Parameter legt den Namen des OpenTelemetry-Trace fest.

Der Tracer unterstützt allgemeine Steuerelemente für Produktionsworkflows:

• Übergeben Sie connection_string an eine bestimmte Application Insights-Ressource oder konfigurieren Sie die Umgebungsvariable APPLICATION_INSIGHTS_CONNECTION_STRING.
• Festlegen trace_all_langgraph_nodes=True , dass alle Knoten standardmäßig nachverfolgt werden.
• Verwenden Sie Knotenmetadaten wie otel_trace: True oder otel_trace: False, um bestimmte Knoten einzuschließen oder zu überspringen.
• Verwenden message_keys und message_paths, wenn Ihre Nachrichten unter einer benutzerdefinierten Zustandsform geschachtelt sind, z. B. chat_history.

Verweis:

• AzureAIOpenTelemetryTracer

Verfolgen eines Agents

Beginnen Sie mit einem minimalen LangChain-Agenten, damit Sie die Nachverfolgung schnell überprüfen können. Fügen Sie für LangGraph den Tracer mit with_config dem kompilierten Diagramm an.

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.

Funktionsweise dieses Codeausschnitts: Erstellt einen einfachen LangGraph-Agent, fügt den Tracer an und ruft den Agent mit einer Nachricht auf.

Verweis:

• LangGraph
• OpenTelemetry

Verfolgen eines LangChain Runnable

Beginnen Sie mit einem minimalen LangChain-Fluss, damit Sie die Ablaufverfolgung schnell überprüfen können.

import os

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

model = AzureAIChatCompletionsModel(
	endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
	credential=DefaultAzureCredential(),
	model=os.environ["AZURE_OPENAI_DEPLOYMENT"],
)

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.

Funktionsweise dieses Codeausschnitts: Führt eine Standardmäßige LangChain-Pipeline aus und sendet Chats über OpenTelemetry.AzureAIOpenTelemetryTracer

Verweis:

• AzureAIChatCompletionsModel
• ChatPromptTemplate

Nachverfolgen eines LangGraph-Diagramms

Fügen Sie für LangGraph den Tracer mit with_config dem kompilierten Diagramm an. Dieser Codeausschnitt verwendet model und tracer aus früheren Beispielen erneut.

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

Anschließend können Sie das Diagramm wie gewohnt ausführen:

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.

Funktionsweise dieses Codeausschnitts: Erstellt eine einfache LangGraph-App, markiert den Knoten für die Ablaufverfolgung und sendet invoke_agent und modell/tool umfasst die gleiche Ablaufverfolgung.

Verweis:

• LangGraph
• OpenTelemetry

Verstehen der Ablaufverfolgungsstruktur

Der Tracer emittiert Bereiche, die den OpenTelemetry GenAI-Semantikkonventionen entsprechen. Jeder Span-Typ verwendet einen bestimmten gen_ai.operation.name Wert:

Spans tragen auch die folgenden Schlüsselattribute:

• gen_ai.agent.name — Der Agent- oder Knotenname.
• gen_ai.agent.id — Aus dem agent_id Konstruktorparameter festgelegt.
• gen_ai.agent.description — Eine Beschreibung des Agenten.
• gen_ai.provider.name — Der Modellanbieter (z. B openai. , azure.ai.inference).
• gen_ai.request.model — Der Modellname, der für die Ableitung verwendet wird.
• gen_ai.conversation.id — Thread- oder Sitzungsbezeichner, sofern verfügbar.
• gen_ai.usage.input_tokens / gen_ai.usage.output_tokens — Tokenanzahl von Modellantworten.
• gen_ai.input.messages / gen_ai.output.messages — Nachrichteninhalt (wenn die Inhaltsaufzeichnung aktiviert ist).

Wie der Tracer aufgelöst wird gen_ai.agent.name

Der Tracer ermittelt den Agentnamen aus dem ersten nicht leeren Wert in dieser Reihenfolge:

1. agent_name in den Knotenmetadaten.
2. langgraph_node in den Knotenmetadaten (automatisch von LangGraph festgelegt).
3. agent_type in den Knotenmetadaten.
4. Das name Schlüsselwortargument aus dem LangChain-Rückruf.
5. langgraph_path (letztes Element) wenn die oben genannten generischen Platzhalter sind.
6. Die serialisierte Ketten-ID oder der Klassenname.
7. Der name-Parameter im AzureAIOpenTelemetryTracer-Konstruktor (Standardwert für Fallback).

Wie der Tracer aufgelöst wird gen_ai.agent.id

Der Tracer ermittelt die Agent-ID aus:

1. agent_id in den Knotenmetadaten (überschreiben pro Knoten).
2. Der agent_id Konstruktorparameter (Standardeinstellung für alle Bereiche).

Anpassen von Attributen mit Knotenmetadaten

Mit LangGraph-Metadaten können Sie agent_name, agent_id und agent_description pro Knoten festlegen. Jeder Metadatenschlüssel, der mit gen_ai. beginnt, wird auch als Span-Attribut weitergeleitet.

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

Wenn Sie LangGraph verwenden, können Sie auch Metadaten pro Knoten in der Diagrammdefinition festlegen:

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

Verweis:

• OpenTelemetry GenAI Agent Spans
• OpenTelemetry GenAI Spans

Anzeigen von Ablaufverfolgungen in Azure Monitor

Traces werden an Azure-Anwendung Insights gesendet und können mithilfe von Azure Monitor abgefragt werden.

1. Wechseln Sie zum portal Azure.

2. Navigieren Sie zu den Azure-Anwendung Insights, die Sie konfiguriert haben.

3. Verwenden Sie die linke Navigationsleiste und wählen Sie Untersuchen>Agents (Vorschau).

4. Es wird ein Dashboard mit Agent-, Modell- und Toolausführungen angezeigt. Verwenden Sie diese Ansicht, um die allgemeine Aktivität Ihrer Agents zu verstehen.

5. Wählen Sie "Ablaufverfolgungen mit Agent-Ausführungen anzeigen" aus. Im Seitenbereich werden alle vom Agenten generierten Protokolle angezeigt.

   

6. Wählen Sie eine der Ablaufverfolgungen aus. Sie sollten die Details sehen.

   

Ablaufverfolgungen in der Foundry-Kontrollebene anzeigen

Wenn Sie Ihre LangGraph- oder LangChain-Lösung bereitgestellt haben, können Sie diese Bereitstellung in Foundry Control Plane registrieren, um Sichtbarkeit und Governance zu erhalten.

Registrieren Sie Ihre Anwendung im Foundry Control Plane, um Traces im Foundry-Portal anzuzeigen.

Führen Sie die folgenden Schritte aus:

1. Stellen Sie sicher, dass Sie die Anforderungen für die Verwendung der benutzerdefinierten Agentfunktion "Foundry Control Plane" erfüllen:

   • Ein AI-Gateway, das in Ihrer Foundry-Ressource konfiguriert ist. Foundry verwendet Azure API Management, um Agents als APIs zu registrieren.

   • Ein Agent, den Sie über einen erreichbaren Endpunkt bereitstellen und verfügbar machen. Der Endpunkt kann entweder ein öffentlicher Endpunkt oder ein Endpunkt sein, der über das Netzwerk erreichbar ist, in dem Sie die Foundry-Ressource bereitstellen.

2. Stellen Sie sicher, dass die Observability im Projekt konfiguriert ist.

3. Stellen Sie beim Konfigurieren der Klasse AzureAIOpenTelemetryTracersicher, dass Sie den Endpunkt des Projekts verwenden, bei dem der Agent registriert werden soll. Stellen Sie sicher, dass agent_id konfiguriert ist.

4. Wechseln Sie zum Foundry-Portal.

5. Wählen Sie auf der Symbolleiste "Ausführen" aus.

6. Wählen Sie im Bereich "Übersicht " die Option "Agent registrieren" aus.

7. Der Registrierungs-Assistent wird angezeigt. Führen Sie zunächst die Details zu dem Agent aus, den Sie registrieren möchten.

   • Agent-URL: Der Endpunkt (URL), an dem Ihr Agent läuft und Anforderungen empfängt.
   • Protokoll: Das Kommunikationsprotokoll, das Ihr Agent unterstützt.
   • OpenTelemetry-Agent-ID: Der agent_id Parameter, den Sie in der AzureAIOpenTelemetryTracer Klasse konfiguriert haben.
   • Project: Das Projekt, das Sie für den Empfang von Ablaufverfolgungen in der Klasse AzureAIOpenTelemetryTracer konfiguriert haben.
   • Agentname: Der Name des Agents (er kann identisch sein mit agent_id).

8. Rufen Sie den Agenten auf, um sicherzustellen, dass er ausgeführt wird.

9. Wählen Sie auf der Symbolleiste "Ausführen" aus.

10. Wählen Sie im linken Bereich "Objekte" aus.

11. Wählen Sie den von Ihnen erstellten Agent aus.

12. Im Abschnitt "Ablaufverfolgungen " wird ein Eintrag für jeden HTTP-Aufruf angezeigt, der an den Endpunkt des Agents gesendet wurde.

    Um die Details anzuzeigen, wählen Sie einen Eintrag aus.

    

Fehlerbehebung

• Wenn keine Ablaufverfolgungen angezeigt werden, stellen Sie sicher, dass entweder connection_string konfiguriert ist oder Ihr Projektendpunkt Telemetrie verfügbar macht.
• Wenn der Nachrichteninhalt als redigiert erscheint, setzen Sie enable_content_recording=True im AzureAIOpenTelemetryTracer Konstruktor.
• Wenn einige LangGraph-Knoten fehlen, legen Sie Knotenmetadaten trace_all_langgraph_nodes=Truefest otel_trace: True oder fügen Sie sie hinzu.

Verwandte Inhalte

• Erste Schritte mit langchain-azure-ai
• Verwenden von LangGraph mit dem Agent-Dienst
• Einrichten von Tracing-Integrationen für Agent-Frameworks