Notatka
Dostęp do tej strony wymaga autoryzacji. Może spróbować zalogować się lub zmienić katalogi.
Dostęp do tej strony wymaga autoryzacji. Możesz spróbować zmienić katalogi.
Ważne
Elementy oznaczone (wersja zapoznawcza) w tym artykule są obecnie dostępne w publicznej wersji zapoznawczej. Ta wersja zapoznawcza jest udostępniana bez umowy dotyczącej poziomu usług i nie zalecamy korzystania z niej w przypadku obciążeń produkcyjnych. Niektóre funkcje mogą nie być obsługiwane lub mogą mieć ograniczone możliwości. Aby uzyskać więcej informacji, zobacz Wygólne warunki użytkowania Microsoft Azure Previews.
Uwaga
Śledzenie jest powszechnie dostępne dla agentów promptów i agentów hostowanych. Przepływy pracy i agenci zewnętrzni są dostępne w wersji zapoznawczej.
Gdy agenci sztucznej inteligencji zachowują się nieoczekiwanie w środowisku produkcyjnym, śledzenie zapewnia widoczność, aby szybko zidentyfikować główną przyczynę. Śledzenie przechwytuje szczegółowe dane telemetryczne — w tym wywołania LLM, wywołania narzędzi i przepływy decyzyjne agenta — dzięki czemu można debugować problemy, monitorować opóźnienia i interpretować zachowanie agenta między żądaniami.
Microsoft Foundry udostępnia integracje śledzenia dla popularnych struktur agentów, które wymagają minimalnych zmian kodu. Z tego artykułu dowiesz się, jak wykonywać następujące działania:
- Konfigurowanie automatycznego śledzenia dla programu Microsoft Agent Framework i jądra semantycznego
- Skonfiguruj dystrybucję Microsoft OpenTelemetry dla LangChain i LangGraph
- Instrumentacja zestawu SDK agentów OpenAI przy użyciu platformy OpenTelemetry
- Sprawdź, czy ślady są wyświetlane w portalu Foundry
- Rozwiązywanie typowych problemów z śledzeniem
Funkcja Microsoft Foundry Skill może pomóc w konfigurowaniu instrumentacji frameworka i weryfikowaniu śladów w Foundry.
Wymagania wstępne
- Projekt Foundry. Aby uzyskać więcej informacji, zobacz Utwórz projekt Foundry.
- Śledzenie połączone z zasobem usługi Azure Monitor Application Insights. Aby ją skonfigurować, zobacz Konfigurowanie śledzenia w rozwiązaniu Microsoft Foundry.
- Współautor lub wyższa rola w zasobie usługi Application Insights na potrzeby przyjmowania danych śledzenia.
- Dostęp do połączonego zasobu usługi Application Insights w celu wyświetlania śladów. W przypadku zapytań opartych na dziennikach może być również potrzebny dostęp do skojarzonego Log Analytics obszaru roboczego.
- Python 3.10 lub nowszy (wymagane dla wszystkich przykładów kodu w tym artykule).
- Pakiet
microsoft-opentelemetry(wymagany dla przykładów LangChain i LangGraph). - Jeśli używasz bibliotek LangChain lub LangGraph, potrzebujesz środowiska Python z zainstalowanym pip.
Potwierdź, że możesz wyświetlić dane telemetryczne
Aby wyświetlić dane śledzenia, upewnij się, że twoje konto ma dostęp do połączonego zasobu usługi Application Insights.
W portalu Azure otwórz zasób usługi Application Insights połączony z projektem Foundry.
Wybierz pozycję Kontrola dostępu (IAM).
Przypisz odpowiednią rolę do użytkownika lub grupy.
Jeśli używasz zapytań opartych na dziennikach, zacznij od udzielenia roli Log Analytics Reader. Jeśli bazowe tabele Log Analytics są chronione, przyznaj również rolę Czytelnik uprzywilejowanych danych monitorowania.
Bezpieczeństwo i prywatność
Śledzenie może przechwytywać poufne informacje (na przykład dane wejściowe użytkownika, dane wyjściowe modelu i argumenty narzędzi i wyniki).
- Włącz rejestrowanie zawartości podczas programowania i debugowania, aby wyświetlić pełne dane żądania i odpowiedzi. Wyłącz rejestrowanie zawartości w środowiskach produkcyjnych, aby chronić poufne dane. W przykładach w tym artykule rejestrowanie zawartości jest kontrolowane przez zmienne
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENTśrodowiskowe ,OTEL_SEMCONV_STABILITY_OPT_INiAZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING. - Nie przechowuj tajemnic, poświadczeń ani tokenów w monitach lub w argumentach narzędzi.
Aby uzyskać więcej wskazówek, zobacz Zabezpieczenia i prywatność.
Uwaga
Dane śledzenia przechowywane w usłudze Application Insights podlegają ustawieniom przechowywania danych w obszarze roboczym oraz cenom usługi Azure Monitor. W przypadku zarządzania kosztami rozważ dostosowanie częstotliwości próbkowania lub okresów przechowywania w środowisku produkcyjnym. Zobacz cennik Azure Monitor i Konfiguruj przechowywanie i archiwizowanie danych.
Konfigurowanie śledzenia dla Microsoft Agent Framework i Semantic Kernel
Platforma Microsoft Foundry ma natywną integrację zarówno z programem Microsoft Agent Framework, jak i jądrem semantycznym. Agenci zbudowani za pomocą któregokolwiek z obu platform automatycznie emitują ślady po włączeniu śledzenia dla projektu Foundry — nie jest wymagany żaden dodatkowy kod ani pakiety.
Aby sprawdzić, czy śledzenie działa:
- Uruchom agenta co najmniej raz.
- W portalu Foundry przejdź do Monitorowanie>Ślady.
- Upewnij się, że zostanie wyświetlony nowy ślad z zakresami dla operacji agenta.
Ślady zwykle pojawiają się w ciągu 2–5 minut po uruchomieniu agenta. Aby uzyskać zaawansowaną konfigurację, zobacz dokumentację specyficzną dla platformy:
Konfigurowanie śledzenia za pomocą bibliotek instrumentacji OpenInference
Microsoft Foundry obsługuje biblioteki instrumentacyjne OpenInference do śledzenia agentów AI. Te openinference-* pakiety zapewniają automatyczną instrumentację dla szerokiej gamy frameworków i mogą być używane do śledzenia zarówno hostowanych agentów (agentów wdrożonych we Foundry), jak i agentów spoza Foundry (agentów hostowanych poza Foundry).
Przeglądaj dostępne pakiety instrumentacji w interfejsie PyPI. Informacje dotyczące LangChain można znaleźć w przykładzie LangChain dla dystrybucji Microsoft OpenTelemetry, który pokazuje, jak włączyć eksport do usługi Azure Monitor i automatyczną instrumentację LangChain za pomocą use_microsoft_opentelemetry.
Kluczowym wymaganiem jest korelacja śladów openInference z określonym agentem. Sposób osiągnięcia tego celu zależy od tego, gdzie działa agent:
Agenci hostowani (wdrożeni do usługi Foundry)
Gdy wdrażasz agenta w usłudze Foundry przy użyciu jednego z hostowanych pakietów serwera dla agenta, korelacja śladów jest obsługiwana automatycznie. Pakiet serwera:
- Konfiguruje eksport do usługi Azure Monitor dla spanów OpenTelemetry.
- Wzbogaca wszystkie zakresy za pomocą atrybutów projektu, nazwy agenta, wersji agenta i identyfikatora agenta, dzięki czemu interfejs użytkownika rozwiązania Foundry może wykonywać zapytania i wyświetlać je.
Nie jest wymagana dodatkowa konfiguracja. Zainstaluj odpowiedni pakiet instrumentacji openinference-* dla używanego frameworka, a ślady będą automatycznie widoczne w portalu Foundry.
Agenci platformy Microsoft Agent Framework hostowani poza usługą Foundry
Jeśli agent Microsoft Agent Framework nie został wdrożony przy użyciu pakietu serwera hostowanego agenta Foundry, skonfiguruj eksport do usługi Azure Monitor oraz instrumentację struktury agenta przy użyciu dystrybucji Microsoft OpenTelemetry. Dystrybucja może włączyć eksportera Azure Monitor i dodać atrybuty tożsamości agenta do spanów:
from microsoft.opentelemetry import use_microsoft_opentelemetry
use_microsoft_opentelemetry(
enable_azure_monitor=True,
azure_monitor_connection_string="...",
sampling_ratio=1.0,
enable_sensitive_data=True,
instrumentation_options={
"agent-framework": {
"enabled": True,
"agent_id": "ms-imagination-agent",
"agent_name": "ms-imagination-agent",
},
},
)
Ustaw azure_monitor_connection_string na zasób Application Insights połączony z projektem Foundry. Aby przechwytywać treść polecenia i wygenerowanej odpowiedzi podczas tworzenia aplikacji, ustaw enable_sensitive_data=True.
Agenci LangChain hostowani poza programem Foundry
Jeśli agent nie jest wdrożony przy użyciu pakietu serwera agenta hostowanego w usłudze Foundry, skonfiguruj eksport do usługi Azure Monitor oraz instrumentację LangChain przy użyciu dystrybucji Microsoft OpenTelemetry. Dystrybucja może włączyć eksportera Azure Monitor i dodać atrybuty tożsamości agenta do spanów LangChain:
from microsoft.opentelemetry import use_microsoft_opentelemetry
use_microsoft_opentelemetry(
enable_azure_monitor=True,
sampling_ratio=1.0,
instrumentation_options={
"langchain": {
"enabled": True,
"agent_id": "weather_info_agent_771929",
"agent_name": "Weather information agent",
},
},
)
Ustaw APPLICATIONINSIGHTS_CONNECTION_STRING na zasób Application Insights połączony z projektem Foundry. Aby przechwycić zawartość monitu i ukończenia podczas programowania, ustaw wartości OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=SPAN_AND_EVENT, OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimentali AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING=true.
Konfigurowanie śledzenia dla bibliotek LangChain i LangGraph
Uwaga
Integracja śledzenia dla bibliotek LangChain i LangGraph jest obecnie dostępna tylko w Python.
Użyj dystrybucji Microsoft OpenTelemetry, aby wysyłać spany zgodne ze standardem OpenTelemetry dla operacji LangChain i LangGraph. Te ślady są wyświetlane w widoku Ślady obserwacji> w portalu Foundry.
- Konwencje semantyczne openTelemetry dla generowania sztucznej inteligencji
- Przykład dystrybucji OpenTelemetry LangChain firmy Microsoft
Przykład: agent LangChain w wersji 1 ze śledzeniem Azure AI
Użyj tego kompleksowego przykładu, aby instrumentować agenta LangChain v1 (wersja zapoznawcza) przy użyciu dystrybucji Microsoft OpenTelemetry. Dystrybucja umożliwia automatyczną instrumentację LangChain zgodną z najnowszymi konwencjami semantycznymi OpenTelemetry (OTel), dzięki czemu możesz wyświetlać szczegółowe ślady w widoku obserwowalności w Foundry.
LangChain v1: Instalowanie pakietów
pip install \
microsoft-opentelemetry \
langchain \
langgraph \
langchain-openai \
azure-identity \
python-dotenv \
rich
LangChain v1: Konfigurowanie środowiska
-
APPLICATIONINSIGHTS_CONNECTION_STRING: Ciąg połączenia Azure Monitor Application Insights do śledzenia operacji. -
AZURE_OPENAI_ENDPOINT: Adres URL punktu końcowego Azure OpenAI. -
AZURE_OPENAI_CHAT_DEPLOYMENT: nazwa wdrożenia modelu czatu. -
AZURE_OPENAI_VERSION: wersja interfejsu API, na przykład2024-08-01-preview. - Zestaw SDK rozpoznaje poświadczenia Azure przy użyciu
DefaultAzureCredential, który obsługuje zmienne środowiskowe, tożsamość zarządzaną i logowanie przez VS Code.
Zapisz te wartości w pliku na potrzeby programowania lokalnego .env .
LangChain v1: Konfiguracja narzędzia Tracer
from dotenv import load_dotenv
from microsoft.opentelemetry import use_microsoft_opentelemetry
load_dotenv(override=True)
use_microsoft_opentelemetry(
enable_azure_monitor=True,
sampling_ratio=1.0,
instrumentation_options={
"langchain": {
"enabled": True,
"agent_id": "weather_info_agent_771929",
"agent_name": "Weather information agent",
},
},
)
LangChain v1: Konfiguracja modelu (Azure OpenAI)
import os
import azure.identity
from langchain_openai import AzureChatOpenAI
token_provider = azure.identity.get_bearer_token_provider(
azure.identity.DefaultAzureCredential(),
"https://cognitiveservices.azure.com/.default",
)
model = AzureChatOpenAI(
azure_endpoint=os.environ.get("AZURE_OPENAI_ENDPOINT"),
azure_deployment=os.environ.get("AZURE_OPENAI_CHAT_DEPLOYMENT"),
openai_api_version=os.environ.get("AZURE_OPENAI_VERSION"),
azure_ad_token_provider=token_provider,
)
LangChain v1: Definiowanie narzędzi i monitów
from dataclasses import dataclass
from langchain_core.tools import tool
system_prompt = """You are an expert weather forecaster, who speaks in puns.
You have access to two tools:
- get_weather_for_location: use this to get the weather for a specific location
- get_user_location: use this to get the user's location
If a user asks you for the weather, make sure you know the location.
If you can tell from the question that they mean wherever they are,
use the get_user_location tool to find their location."""
# Mock user locations keyed by user id (string)
USER_LOCATION = {
"1": "Florida",
"2": "SF",
}
@dataclass
class UserContext:
user_id: str
@tool
def get_weather(city: str) -> str:
"""Get weather for a given city."""
return f"It's always sunny in {city}!"
LangChain v1: Użyj kontekstu środowiska uruchomieniowego i zdefiniuj narzędzie user-info
from langgraph.runtime import get_runtime
from langchain_core.runnables import RunnableConfig
@tool
def get_user_info(config: RunnableConfig) -> str:
"""Retrieve user information based on user ID."""
runtime = get_runtime(UserContext)
user_id = runtime.context.user_id
return USER_LOCATION[user_id]
LangChain v1: tworzenie agenta
from langchain.agents import create_agent
from langgraph.checkpoint.memory import InMemorySaver
from dataclasses import dataclass
@dataclass
class WeatherResponse:
conditions: str
punny_response: str
checkpointer = InMemorySaver()
agent = create_agent(
model=model,
prompt=system_prompt,
tools=[get_user_info, get_weather],
response_format=WeatherResponse,
checkpointer=checkpointer,
)
LangChain v1: Uruchamianie agenta ze śledzeniem
from rich import print
def main():
config = {"configurable": {"thread_id": "1"}}
context = UserContext(user_id="1")
r1 = agent.invoke(
{"messages": [{"role": "user", "content": "what is the weather outside?"}]},
config=config,
context=context,
)
print(r1.get("structured_response"))
r2 = agent.invoke(
{"messages": [{"role": "user", "content": "Thanks"}]},
config=config,
context=context,
)
print(r2.get("structured_response"))
if __name__ == "__main__":
main()
Po włączeniu dystrybucji Microsoft OpenTelemetry wszystkie operacje LangChain v1 (wywołania LLM, wywołania narzędzi, kroki agenta) emitują spany OpenTelemetry zgodnie z najnowszymi konwencjami semantycznymi. Te ślady są wyświetlane w widoku Obserwowalność>Ślady w portalu Foundry i są połączone z Twoim zasobem Application Insights.
Wskazówka
Po uruchomieniu agenta poczekaj kilka minut na wyświetlenie śladów. Jeśli nie widzisz śladów, sprawdź, czy ciąg połączenia usługi Application Insights jest poprawny i sprawdź sekcję Rozwiązywanie typowych problemów.
Zweryfikuj ślady LangChain v1
Po uruchomieniu agenta:
- Poczekaj 2–5 minut na propagację śladów.
- W portalu Foundry przejdź do Monitorowanie>Ślady.
- Wyszukaj ślad z określoną nazwą (na przykład "Agent informacji o pogodzie").
- Rozwiń ślad, aby wyświetlić zakresy wywołań LLM, wywołań narzędzi i kroków agenta.
Jeśli nie widzisz śladów, zapoznaj się z sekcją Rozwiązywanie typowych problemów .
Przykład: agent LangGraph z śledzeniem sztucznej inteligencji Azure
W tym przykładzie pokazano prostego agenta LangGraph instrumentowanego za pomocą dystrybucji Microsoft OpenTelemetry w celu emitowania śladów zgodnych ze standardem OpenTelemetry dla kroków grafu, wywołań narzędzi i wywołań modelu.
LangGraph: Instalowanie pakietów
pip install \
microsoft-opentelemetry \
"langgraph>=1.0.0" \
"langchain>=1.0.0" \
langchain-openai \
azure-identity \
python-dotenv
LangGraph: Konfigurowanie środowiska
-
APPLICATIONINSIGHTS_CONNECTION_STRING: Ciąg połączenia Azure Monitor Application Insights do śledzenia operacji. -
AZURE_OPENAI_ENDPOINT: Adres URL punktu końcowego Azure OpenAI. -
AZURE_OPENAI_CHAT_DEPLOYMENT: nazwa wdrożenia modelu czatu. -
AZURE_OPENAI_VERSION: wersja interfejsu API, na przykład2024-08-01-preview.
Zapisz te wartości w pliku na potrzeby programowania lokalnego .env .
LangGraph — konfiguracja śledzenia
from dotenv import load_dotenv
from microsoft.opentelemetry import use_microsoft_opentelemetry
load_dotenv(override=True)
use_microsoft_opentelemetry(
enable_azure_monitor=True,
sampling_ratio=1.0,
instrumentation_options={
"langchain": {
"enabled": True,
"agent_name": "Music Player Agent",
},
},
)
LangGraph: Narzędzia
from langchain_core.tools import tool
@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!"
tools = [play_song_on_apple, play_song_on_spotify]
LangGraph: Konfiguracja modelu (Azure OpenAI)
import os
import azure.identity
from langchain_openai import AzureChatOpenAI
token_provider = azure.identity.get_bearer_token_provider(
azure.identity.DefaultAzureCredential(),
"https://cognitiveservices.azure.com/.default",
)
model = AzureChatOpenAI(
azure_endpoint=os.environ.get("AZURE_OPENAI_ENDPOINT"),
azure_deployment=os.environ.get("AZURE_OPENAI_CHAT_DEPLOYMENT"),
openai_api_version=os.environ.get("AZURE_OPENAI_VERSION"),
azure_ad_token_provider=token_provider,
).bind_tools(tools, parallel_tool_calls=False)
Budowanie procesu LangGraph
from langgraph.graph import END, START, MessagesState, StateGraph
from langgraph.prebuilt import ToolNode
from langgraph.checkpoint.memory import MemorySaver
tool_node = ToolNode(tools)
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.invoke(messages)
return {"messages": [response]}
workflow = StateGraph(MessagesState)
workflow.add_node("agent", call_model)
workflow.add_node("action", tool_node)
workflow.add_edge(START, "agent")
workflow.add_conditional_edges(
"agent",
should_continue,
{
"continue": "action",
"end": END,
},
)
workflow.add_edge("action", "agent")
memory = MemorySaver()
app = workflow.compile(checkpointer=memory)
LangGraph: Uruchamianie ze śledzeniem
from langchain_core.messages import HumanMessage
config = {"configurable": {"thread_id": "1"}}
input_message = HumanMessage(content="Can you play Taylor Swift's most popular song?")
for event in app.stream({"messages": [input_message]}, config, stream_mode="values"):
event["messages"][-1].pretty_print()
Po włączeniu dystrybucji Microsoft OpenTelemetry uruchomienie LangGraph emituje spany zgodne ze standardem OpenTelemetry dla wywołań modelu, wywołań narzędzi i przejść grafu. Te ślady przepływają do usługi Application Insights i są wyświetlane w widoku Obserwowalność>Ślady w portalu Foundry.
Wskazówka
Każdy węzeł grafu i przejście brzegowe tworzy oddzielny zakres, co ułatwia wizualizowanie przepływu decyzyjnego agenta.
Zweryfikuj ślady LangGraph
Po uruchomieniu agenta:
- Poczekaj 2–5 minut na propagację śladów.
- W portalu Foundry przejdź do Monitorowanie>Ślady.
- Poszukaj śladu o określonej nazwie (na przykład "Agent odtwarzacza muzyki").
- Rozwiń ślad, aby wyświetlić zakresy dla węzłów grafu, wywołań narzędzi i wywołań modelu.
Jeśli nie widzisz śladów, zapoznaj się z sekcją Rozwiązywanie typowych problemów .
Przykład: konfiguracja pakietu LangChain 0.3 przy użyciu śledzenia sztucznej inteligencji Azure
Ta minimalna konfiguracja pokazuje, jak włączyć śledzenie sztucznej inteligencji Azure w aplikacji LangChain 0.3 przy użyciu dystrybucji Microsoft OpenTelemetry i AzureChatOpenAI.
LangChain 0.3: Instalowanie pakietów
pip install \
"langchain>=0.3,<0.4" \
langchain-openai \
microsoft-opentelemetry \
python-dotenv
LangChain 0.3: Konfigurowanie środowiska
-
APPLICATIONINSIGHTS_CONNECTION_STRING: ciąg połączenia usługi Application Insights do śledzenia. Aby znaleźć tę wartość, otwórz zasób usługi Application Insights w portalu Azure, wybierz pozycję Overview i skopiuj Ciąg połączenia. -
AZURE_OPENAI_ENDPOINT: Adres URL punktu końcowego Azure OpenAI. -
AZURE_OPENAI_CHAT_DEPLOYMENT: Nazwa wdrożenia modelu czatu. -
AZURE_OPENAI_VERSION: wersja interfejsu API, na przykład2024-08-01-preview. -
AZURE_OPENAI_API_KEY: Klucz API Azure OpenAI.
Uwaga
W tym przykładzie użyto uwierzytelniania klucza API dla uproszczenia. W przypadku obciążeń produkcyjnych należy używać DefaultAzureCredential z get_bearer_token_provider, jak pokazano w przykładach LangChain v1 i LangGraph.
LangChain 0.3: Tracer i konfiguracja modelu
import os
from dotenv import load_dotenv
from microsoft.opentelemetry import use_microsoft_opentelemetry
from langchain_openai import AzureChatOpenAI
load_dotenv(override=True)
# Enable Azure Monitor export and LangChain auto-instrumentation
use_microsoft_opentelemetry(
enable_azure_monitor=True,
sampling_ratio=1.0,
instrumentation_options={
"langchain": {
"enabled": True,
"agent_id": "trip_planner_orchestrator_v3",
"agent_name": "Trip Planner Orchestrator",
},
},
)
# Model: Azure OpenAI
llm = AzureChatOpenAI(
azure_deployment=os.environ.get("AZURE_OPENAI_CHAT_DEPLOYMENT"),
api_key=os.environ.get("AZURE_OPENAI_API_KEY"),
azure_endpoint=os.environ.get("AZURE_OPENAI_ENDPOINT"),
api_version=os.environ.get("AZURE_OPENAI_VERSION"),
temperature=0.2,
)
Po zainicjowaniu dystrybucji operacje LangChain 0.3 są automatycznie instrumentowane globalnie. Po uruchomieniu łańcucha lub agenta, ślady pojawiają się w widoku Obserwowalność>Ślady w portalu Foundry w ciągu 2–5 minut.
Konfigurowanie śledzenia dla SDK dla agentów OpenAI
Zestaw SDK agentów OpenAI obsługuje instrumentację OpenTelemetry. Użyj poniższego fragmentu kodu, aby skonfigurować śledzenie i eksport odcinków do Azure Monitor. Jeśli APPLICATION_INSIGHTS_CONNECTION_STRING nie zostanie ustawiona, eksporter wróci do konsoli na potrzeby lokalnego debugowania.
Przed uruchomieniem przykładu zainstaluj wymagane pakiety:
pip install opentelemetry-sdk opentelemetry-instrumentation-openai-agents azure-monitor-opentelemetry-exporter
import os
from opentelemetry import trace
from opentelemetry.instrumentation.openai_agents import OpenAIAgentsInstrumentor
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter
# Configure tracer provider + exporter
resource = Resource.create({
"service.name": os.getenv("OTEL_SERVICE_NAME", "openai-agents-app"),
})
provider = TracerProvider(resource=resource)
conn = os.getenv("APPLICATION_INSIGHTS_CONNECTION_STRING")
if conn:
from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter
provider.add_span_processor(
BatchSpanProcessor(AzureMonitorTraceExporter.from_connection_string(conn))
)
else:
provider.add_span_processor(BatchSpanProcessor(ConsoleSpanExporter()))
trace.set_tracer_provider(provider)
# Instrument the OpenAI Agents SDK
OpenAIAgentsInstrumentor().instrument(tracer_provider=trace.get_tracer_provider())
# Example: create a session span around your agent run
tracer = trace.get_tracer(__name__)
with tracer.start_as_current_span("agent_session[openai.agents]"):
# ... run your agent here
pass
Weryfikowanie śladów w portalu Foundry
- Zaloguj się do Microsoft Foundry. Upewnij się, że przełącznik New Foundry jest włączony. Kroki te dotyczą nowego Foundry.
- Upewnij się, że śledzenie jest włączone dla twojego projektu. W razie potrzeby postępuj zgodnie z Skonfiguruj śledzenie w usłudze Microsoft Foundry.
- Uruchom agenta co najmniej raz.
- W portalu Foundry przejdź do Monitorowanie>Ślady.
- Upewnij się, że zostanie wyświetlony nowy ślad z zakresami dla operacji agenta.
Ślady zwykle pojawiają się w ciągu 2–5 minut po uruchomieniu agenta. Jeśli ślady nadal nie są wyświetlane po tym czasie, zobacz Rozwiązywanie typowych problemów.
Rozwiązywanie typowych problemów
| Kwestia | Przyczyna | Rozdzielczość |
|---|---|---|
| Nie widzisz śladów w Foundry. | Śledzenie nie jest aktywne, nie ma ostatniego ruchu lub przetwarzanie danych jest opóźnione. | Potwierdź połączenie usługi Application Insights, wygeneruj nowy ruch i odśwież po 2–5 minutach. |
| Nie widzisz zakresów LangChain ani LangGraph | Dystrybucja Microsoft OpenTelemetry nie jest inicjowana lub instrumentacja LangChain nie jest włączona | Przed uruchomieniem agenta upewnij się, że wywołujesz use_microsoft_opentelemetry(...) z użyciem "langchain": {"enabled": True}. |
| Zakresy langchain są wyświetlane, ale brakuje wywołań narzędzi | Narzędzia nie są powiązane z modelem lub węzeł narzędzia nie jest skonfigurowany | Sprawdź, czy narzędzia są przekazywane do bind_tools() modelu i czy węzły narzędzi są dodawane do grafu. |
| Ślady są wyświetlane, ale są niekompletne lub niektóre fragmenty są brakujące. | Rejestrowanie treści jest wyłączone, nie włączono semantycznej konwencji GenAI lub niektóre operacje nie są objęte instrumentacją | W przypadku LangChain i LangGraph ustaw OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=SPAN_AND_EVENT, OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental i AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING=true podczas programowania. W przypadku operacji niestandardowych dodaj zakresy ręczne przy użyciu zestawu OpenTelemetry SDK. |
| Podczas wykonywania zapytań dotyczących telemetrii są wyświetlane błędy autoryzacji | Brak uprawnień RBAC w usłudze Application Insights lub Log Analytics | Potwierdź dostęp w konsoli kontroli dostępu (IAM) dla połączonych zasobów. W przypadku zapytań dziennika przypisz rolę Log Analytics Reader. Jeśli tabele są chronione, przypisz również rolę Uprzywilejowany czytelnik danych monitorowania. |
| Zawartość wrażliwa występuje w śladach. | Rejestrowanie zawartości jest włączone, a monity, argumenty narzędzi lub dane wyjściowe obejmują dane poufne | Wyłącz rejestrowanie zawartości w środowisku produkcyjnym i zanonimizuj poufne dane przed wprowadzeniem ich do telemetrii. |
Treści powiązane
- Poznaj podstawowe pojęcia i architekturę w omówieniu śledzenia agentów.
- Jeśli nie włączyłeś jeszcze śledzenia, zobacz Konfigurowanie śledzenia w Microsoft Foundry.
- Wizualizowanie metryk kondycji i wydajności agenta za pomocą pulpitu nawigacyjnego monitorowania agenta.
- Zapoznaj się z szerszymi możliwościami obserwowalności w generatywnej sztucznej inteligencji.