Melacak aplikasi LangChain dan LangGraph dengan Microsoft Foundry dan Azure Monitor

Gunakan paket integrasi langchain-azure-ai untuk memancarkan jejak OpenTelemetry dari aplikasi LangChain dan LangGraph dan menenggelamkannya di Azure Application Insights. Dalam artikel ini, Anda mengonfigurasi AzureAIOpenTelemetryTracer, melampirkannya ke runnable Anda, dan memeriksa jejak di Azure Monitor.

Pelacak memancarkan span untuk eksekusi agen, pemanggilan model, pelaksanaan alat, dan operasi pengambilan. Anda dapat menggunakannya untuk aplikasi yang berjalan sepenuhnya lokal, alur hibrid yang memanggil Foundry Agent Service, atau solusi LangGraph multi-agen.

Prasyarat

  • Langganan Azure. Buat satu secara gratis.
  • Proyek Foundry.
  • Model obrolan Azure OpenAI yang telah dideploy (misalnya, gpt-4.1).
  • Python 3.10 atau yang lebih baru.
  • Azure CLI masuk (az login) sehingga DefaultAzureCredential dapat mengautentikasi.

Mengonfigurasi lingkungan Anda

Pasang paket yang diperlukan:

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

Atur variabel lingkungan yang digunakan dalam artikel ini:

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

Untuk mengontrol apakah konten dari pesan dan panggilan alat direkam dalam jejak, berikan enable_content_recording ke konstruktor AzureAIOpenTelemetryTracer. Perekaman konten diaktifkan secara default.

Tips

Atur enable_content_recording=False dalam AzureAIOpenTelemetryTracer konstruktor untuk menyensor konten pesan dan argumen panggilan alat dari lacak.

Membuat pelacak

Buat satu instans pelacak dan gunakan kembali di seluruh alur kerja Anda.

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

Yang dilakukan cuplikan ini: Mengonfigurasi pelacak jejak yang menyelesaikan string koneksi Application Insights terkait dari titik akhir proyek Foundry Anda serta mengaktifkan pelacakan untuk node LangGraph. Gunakan agent_id parameter untuk mengatur atribut gen_ai.agent.id saat memanggil agen. Parameter name menetapkan nama pelacak OpenTelemetry.

Pelacak mendukung kontrol umum untuk alur kerja produksi:

  • Teruskan connection_string untuk menargetkan sumber daya Application Insights tertentu atau dengan mengonfigurasi variabel lingkungan APPLICATION_INSIGHTS_CONNECTION_STRING.
  • Atur trace_all_langgraph_nodes=True untuk melacak semua simpul secara default.
  • Gunakan metadata simpul seperti otel_trace: True atau otel_trace: False untuk menyertakan atau melewati simpul tertentu.
  • Gunakan message_keys dan message_paths saat pesan Anda disarangkan di bawah bentuk status kustom, misalnya chat_history.

Referensi:

Melacak agen

Mulailah dengan agen LangChain minimal sehingga Anda dapat memverifikasi pelacakan dengan cepat. Untuk LangGraph, lampirkan pelacak dengan with_config pada grafik yang dikompilasi.

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.

Apa yang dilakukan cuplikan ini: Membuat agen LangGraph sederhana, melampirkan pelacak, dan memanggil agen dengan pesan.

Referensi:

Melacak LangChain yang dapat dijalankan

Mulailah dengan alur LangChain minimal sehingga Anda dapat memverifikasi pelacakan dengan cepat.

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.

Apa yang dilakukan cuplikan ini: Menjalankan alur LangChain standar dan mengirim rentang obrolan ke OpenTelemetry melalui AzureAIOpenTelemetryTracer.

Referensi:

Melacak grafik LangGraph

Untuk LangGraph, lampirkan pelacak dengan with_config pada grafik yang dikompilasi. Cuplikan ini memanfaatkan model dan tracer dari contoh sebelumnya.

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

Kemudian, Anda dapat menjalankan grafik seperti biasa:

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.

Apa yang dilakukan potongan kode ini: Membuat aplikasi LangGraph sederhana, menandai simpul untuk pelacakan, dan mengeluarkan invoke_agent serta jangkauan model/alat ke dalam jejak yang sama.

Referensi:

Memahami struktur penelusuran

Pelacak menghasilkan rentang yang mengikuti konvensi semantik OpenTelemetry GenAI. Setiap jenis rentang menggunakan nilai tertentu gen_ai.operation.name :

Jenis rentang gen_ai.operation.name Deskripsi
Pemanggilan agen atau rantai invoke_agent Setiap simpul LangGraph atau langkah rantai. Nama rentang adalah invoke_agent {gen_ai.agent.name}.
Panggilan model obrolan chat Permintaan inferensi LLM. Nama rentang adalah chat {gen_ai.request.model}.
Pelengkapan teks text_completion Panggilan non-chat LLM.
Pelaksanaan alat execute_tool Panggilan alat yang dipicu oleh model. Nama rentang adalah execute_tool {gen_ai.tool.name}.
Retriever execute_tool Pengambilan data dari toko vektor atau pencarian.

Rentang juga membawa atribut utama ini:

  • gen_ai.agent.name — Nama agen atau node.
  • gen_ai.agent.id — Disetel dari parameter konstruktor agent_id.
  • gen_ai.agent.description — Deskripsi agen.
  • gen_ai.provider.name — Penyedia model (misalnya, openai).
  • gen_ai.request.model — Nama model yang digunakan untuk inferensi.
  • gen_ai.conversation.id — Utas atau pengidentifikasi sesi, jika tersedia.
  • gen_ai.usage.input_tokens / gen_ai.usage.output_tokens — Jumlah token dari respons model.
  • gen_ai.input.messages / gen_ai.output.messages — Konten pesan (saat perekaman konten diaktifkan).

Bagaimana penjejak mengatasinya gen_ai.agent.name

Pelacak mengidentifikasi nama agen dari nilai tidak kosong yang pertama dalam urutan ini:

  1. agent_name dalam metadata simpul.
  2. langgraph_node dalam metadata simpul (diatur secara otomatis oleh LangGraph).
  3. agent_type dalam metadata simpul.
  4. Argumen kata kunci name dari callback LangChain.
  5. langgraph_path (elemen terakhir) jika elemen di atas adalah placeholder generik.
  6. ID rantai berseri atau nama kelas.
  7. Parameter name dari konstruktor AzureAIOpenTelemetryTracer (default cadangan).

Bagaimana penjejak mengatasinya gen_ai.agent.id

Pelacak mengurai ID agen dari sumber:

  1. agent_id dalam metadata simpul (penggantian pada setiap simpul).
  2. Parameter konstruktor agent_id (bawaan untuk semua rentang).

Menyesuaikan atribut dengan metadata simpul

Anda dapat mengatur agent_name, agent_id, dan agent_description per simpul menggunakan metadata LangGraph. Kunci metadata apa pun yang dimulai dengan gen_ai. juga diteruskan sebagai atribut rentang.

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)

Saat menggunakan LangGraph, Anda juga dapat mengatur metadata per simpul dalam definisi grafik:

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

Referensi:

Lihat jejak di Azure Monitor

Jejak dikirim ke Azure Application Insights dan dapat dikueri menggunakan Azure Monitor:

  1. Buka portal Azure.

  2. Navigasikan ke Azure Application Insights yang Anda konfigurasikan.

  3. Menggunakan bilah navigasi kiri, pilih Selidiki>Agen (Pratinjau).

  4. Anda melihat dasbor yang menampilkan agen, model, dan pelaksanaan alat. Gunakan tampilan ini untuk memahami aktivitas keseluruhan agen Anda.

  5. Pilih Tampilkan Jejak dengan Eksekusi Agen. Panel samping menunjukkan semua jejak yang dihasilkan oleh eksekusi agen.

    Screenshot memperlihatkan bagian Agen (Pratinjau) di Azure Monitor menampilkan beberapa runs.

  6. Pilih salah satu jejak. Anda akan melihat detailnya.

    Cuplikan layar memperlihatkan detail pelacakan eksekusi yang dipilih.

Melihat jejak di Foundry Control Plane

Jika Anda menyebarkan solusi LangGraph atau LangChain, Anda dapat mendaftarkan penyebaran tersebut ke Foundry Control Plane untuk mendapatkan visibilitas dan tata kelola.

Daftarkan aplikasi Anda ke Foundry Control Plane untuk melihat jejak di portal Foundry.

Ikuti langkah-langkah berikut:

  1. Pastikan Anda memenuhi persyaratan untuk menggunakan kemampuan agen kustom Foundry Control Plane:

    • Gateway AI yang dikonfigurasi di sumber daya Foundry Anda. Foundry menggunakan Azure API Management untuk mendaftarkan agen sebagai API.

    • Agen yang Anda sebarkan dan diekspos melalui sebuah titik akhir yang dapat dijangkau. Titik akhir dapat berupa titik akhir publik atau titik akhir yang dapat dijangkau dari jaringan tempat Anda menyebarkan sumber daya Foundry.

  2. Pastikan Anda memiliki observabilitas yang sudah dikonfigurasi dalam proyek.

  3. Saat mengonfigurasi kelas AzureAIOpenTelemetryTracer, pastikan untuk menggunakan titik akhir proyek tempat Anda ingin agen didaftarkan. Pastikan Anda mengonfigurasi agent_id.

  4. Buka portal Foundry.

  5. Pada toolbar, pilih Operasikan.

  6. Pada panel Gambaran Umum , pilih Daftarkan agen.

  7. Panduan pendaftaran muncul. Pertama, lengkapi detail tentang agen yang ingin Anda daftarkan.

    • URL Agen: Titik akhir (URL) tempat agen Anda menjalankan dan menerima permintaan.
    • Protokol: Protokol komunikasi yang didukung agen Anda.
    • ID Agen OpenTelemetry: parameter yang telah Anda konfigurasikan di kelas agent_id.
    • Project: Project yang Anda konfigurasikan untuk menerima jejak di kelas AzureAIOpenTelemetryTracer.
    • Nama agen: Nama agen (bisa sama dengan agent_id).

  8. Memanggil agen untuk memastikan bahwa ia beroperasi.

  9. Pada toolbar, pilih Operasikan.

  10. Di panel kiri, pilih Aset.

  11. Pilih agen yang Anda buat.

  12. Bagian Jejak menunjukkan satu entri untuk setiap panggilan HTTP yang dilakukan ke endpoint agen.

    Untuk melihat detailnya, pilih entri.

    Cuplikan layar panggilan ke endpoint agen di bawah rute untuk eksekusi proses dan streaming.

Pemecahan Masalah

  • Jika tidak ada jejak yang terlihat, verifikasi apakah connection_string telah dikonfigurasi atau apakah titik akhir proyek Anda memungkinkan akses ke telemetri.
  • Jika konten pesan terlihat disensor, atur enable_content_recording=True di konstruktor AzureAIOpenTelemetryTracer.
  • Jika beberapa node LangGraph hilang, atur trace_all_langgraph_nodes=True atau tambahkan metadata otel_trace: True simpul.

Menggunakan Memori Foundry dengan LangChain dan LangGraph

Konten terkait

  • Terakhir diperbarui pada