Zbieranie i sprawdzanie śladów w zestawie narzędzi Microsoft Foundry Toolkit

Użyj Microsoft Foundry Toolkit for Visual Studio Code, aby zbierać lokalne ślady lub wyświetlać dane telemetryczne agentów wdrożonych w usłudze Microsoft Foundry. Ślad grupuje zarejestrowane operacje dla żądania. Każda operacja jest spanem z czasem, stanem i wszystkimi atrybutami lub zdarzeniami dostarczonymi przez instrumentację.

W tym artykule najpierw opisano kolekcję lokalną, a następnie śledzenie w chmurze dla wdrożonych agentów. Wybierz źródło danych zgodne z dochodzeniem:

Agent hostowany uruchamia niestandardowy kod w usłudze agenta usługi Foundry. Usługa Foundry zarządza hostingiem, ale nadal ponosisz odpowiedzialność za kod i zależności. Śledzenie nie zastępuje tworzenia i wdrażania agenta.

Prerequisites

• Visual Studio Code z bieżącym publicznym rozszerzeniem Foundry Toolkit. Zobacz artykuł Instalacja pakietu Foundry Toolkit.
• Aplikacja, którą można uruchomić lokalnie, ze skonfigurowanymi połączeniami modelu i narzędzi.
• W pierwszym przykładzie pokazano aplikację Python Microsoft Agent Framework i wybrane środowisko Python. W przypadku innych zestawów SDK użyj konfiguracji Python lub JavaScript i TypeScript.
• W przypadku śledzenia w chmurze wymagane są wdrożony agent i zasób usługi Application Insights połączony z projektem Foundry albo uprawnienia do połączenia lub utworzenia takiego zasobu.
• W przypadku zapytań w chmurze wymagana jest rola czytelnika Log Analytics na połączonym zasobie usługi Application Insights. W przypadku tabel chronionych przypisz również rolę Czytelnik danych monitorowania uprzywilejowanego. Zapoznaj się z wymaganiami wstępnymi dotyczącymi śledzenia usługi Foundry.

Kolekcja lokalna nie wymaga uprawnień usługi Application Insights ani uprawnień do telemetrii w chmurze. Wywołania modelu i wykonywanie narzędzi mogą nadal korzystać z usług zdalnych i wiązać się z opłatami.

Zbieranie lokalnych śladów

Lokalny kolektor odbiera dane telemetryczne za pośrednictwem protokołu OpenTelemetry Protocol (OTLP). Nie instrumentuje automatycznie aplikacji. Framework lub biblioteka instrumentacji musi tworzyć spany i eksportować je do modułu zbierającego.

Konfiguracja zestawu SDK i języka

Zestawy SDK z wbudowaną instrumentacją nadal potrzebują eksportera. Inne zestawy SDK używają oddzielnego pakietu instrumentacji.

"Brak dedykowanych wskazówek dotyczących konfiguracji zestawu narzędzi" oznacza, że nie ma tutaj ścieżki konfiguracji specyficznej dla zestawu SDK dla tego języka, a nie, że moduł zbierający odrzuca jego dane telemetryczne. Moduł zbierający akceptuje dane OTLP. Instrumentacja określa, które operacje i szczegóły komunikatów są przechwytywane.

W tych przykładach użyto wybranych opcji instrumentacji, a nie wyczerpującej listy zgodnych bibliotek. Instrumentacja OpenLLMetry i Traceloop to biblioteki inne niż Microsoft.

Skonfiguruj instrumentację

Użyj tej procedury z istniejącą aplikacją Python Agent Framework. Zachowaj agenta i moduł zbierający w tym samym środowisku lokalnym na potrzeby tego przewodnika.

1. Wybierz pozycję Foundry Toolkit na pasku działań, a następnie pozycję Narzędzia deweloperskie>>.

2. Wybierz opcję Uruchom kolektor przed uruchomieniem aplikacji.

3. W środowisku Python aplikacji zainstaluj eksportera gRPC, jeśli nie został jeszcze zadeklarowany w zależnościach:

   python -m pip install opentelemetry-exporter-otlp-proto-grpc
   

   Odnośnik: Eksportery OTLP OpenTelemetry Python.

4. Skonfiguruj funkcję OpenTelemetry raz podczas uruchamiania aplikacji przed utworzeniem lub uruchomieniem agenta:

   import os
   
   os.environ["OTEL_EXPORTER_OTLP_ENDPOINT"] = "http://localhost:4317"
   os.environ["OTEL_EXPORTER_OTLP_PROTOCOL"] = "grpc"
   
   from agent_framework.observability import configure_otel_providers
   
   configure_otel_providers(enable_sensitive_data=False)
   

   Odnośnik: obserwowalność Agent Framework.

   Jeśli aplikacja lub biblioteka hostująca już konfiguruje dostawców OpenTelemetry, skonfiguruj istniejących eksporterów zamiast dodawania innej konfiguracji dostawcy. Zmienne specyficzne dla OTEL_EXPORTER_OTLP_*_ENDPOINT sygnału mogą zastąpić podstawowy punkt końcowy. Sprawdź istniejące ustawienia śledzenia, dziennika lub metryk, które wskazują gdzie indziej.

5. Uruchom aplikację z normalnym punktem wejścia i wyślij żądanie, które powoduje aktywację agenta. Pozwól na zakończenie żądania i daj eksporterowi czas na wysłanie danych telemetrycznych przed zatrzymaniem procesu.

6. W obszarze Śledzenie wybierz pozycję Odśwież, a następnie wybierz nowy ślad, aby sprawdzić jego spany.

Agent Framework monitorował klientów modeli, agentów i operacje przepływu pracy. Inne frameworki mogą wymagać biblioteki instrumentacji. Zgodność OTLP umożliwia modułowi zbierającemu odbieranie danych, podczas gdy emitowane atrybuty i konwencje semantyczne generatywnej AI określają, co wyświetla osoba przeglądająca.

W przypadku innego zestawu SDK lub języka użyj poniższej konfiguracji zamiast konfiguracji programu Agent Framework. Najpierw uruchom moduł zbierający, skonfiguruj instrumentację przed utworzeniem klientów, a następnie uruchom aplikację i odśwież listę śledzenia.

Punkty końcowe kolektora

Dopasuj protokół eksportera do punktu końcowego kolektora. Zestaw narzędzi nasłuchuje na localhost przy użyciu następujących wartości domyślnych:

Niektórzy eksporterzy HTTP akceptują http://localhost:4318 i dołączają ścieżkę sygnału. Postępuj zgodnie z konfiguracją eksportera zamiast dwukrotnie dołączać ścieżkę. Niektóre biblioteki instrumentacji wysyłają zawartość komunikatów jako rekordy dziennika, dlatego eksportowanie samych spanów może nie dostarczać szczegółów danych wejściowych i wyjściowych.

Te porty nie są powiązane z serwerem HTTP agenta i portami debugera. W kontenerze lub zdalnym środowisku projektowym localhost odnosi się do tego środowiska. Ustanów odpowiednie połączenie z kolektorem zamiast zakładać, że odwołuje się do pulpitu.

Konfiguracja SDK Python

W poniższych przykładach założono, że aplikacja ma już swój model SDK, dane uwierzytelniające i konfigurację modelu. Zainstaluj współużytkowane zależności i dodatkowy pakiet zestawu SDK zgodnie z poniższą tabelą:

python -m pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http

Materiały referencyjne: OpenTelemetry Python SDK, eksportery OTLP.

Dodaj tę wspólną konfigurację raz podczas uruchamiania aplikacji, a następnie instrumentację z jednego wiersza tabeli. Nie należy łączyć go z konfiguracją providera innej biblioteki.

import os

os.environ["TRACELOOP_TRACE_CONTENT"] = "false"
os.environ["OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT"] = "false"
os.environ["AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED"] = "false"

from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import (
    OTLPSpanExporter,
)

provider = TracerProvider(
    resource=Resource.create({"service.name": "my-agent"})
)
provider.add_span_processor(BatchSpanProcessor(
    OTLPSpanExporter(endpoint="http://localhost:4318/v1/traces")
))
trace.set_tracer_provider(provider)

Zobacz: TracerProvider and span processors, OTLPSpanExporter.

Zainstaluj pakiet w wybranym wierszu za pomocą python -m pip install <package>. Przykłady OpenAI, Anthropic, LangChain i oddzielnych agentów OpenAI używają instrumentacji OpenLLMetry innej niż Microsoft. Wersje zestawu SDK i interfejsy API modelu mogą dawać różne wyniki.

W przypadku aplikacji Foundry Projects postępuj zgodnie ze wskazówkami dotyczącymi śledzenia po stronie klienta i utwórz klienta OpenAI po instrumentacji. Te wskazówki różnią się od klasycznego zestawu SDK agentów. Nie instrumentuj tych samych wywołań OpenAI zarówno z oddzielnym instrumentorem OpenAI, jak AIProjectInstrumentor i oddzielnym instrumentorem OpenAI.

W przypadku zestawu OpenAI Agents SDK zainstaluj opentelemetry-instrumentation-openai-agents i dodaj ten kod po konfiguracji udostępnionej:

from agents import set_trace_processors
from opentelemetry.instrumentation.openai_agents import OpenAIAgentsInstrumentor

set_trace_processors([])
OpenAIAgentsInstrumentor().instrument()

Odnośnik: Instrumentacja agentów OpenAI, śledzenie agentów OpenAI.

Ten przykład zastępuje istniejące procesory śledzenia przed dodaniem procesora OpenTelemetry. Bez tej zamiany zestaw SDK może również eksportować ślady do domyślnego backendu. Jeśli musisz użyć istniejących procesorów, przed ich zmianą przejrzyj lokalizacje docelowe śledzenia. Zachowaj włączone śledzenie zestawu SDK, aby procesor OpenTelemetry odbierał zdarzenia.

Po zakończeniu żądań przez krótkotrwałą aplikację wywołaj provider.force_flush() przed zakończeniem, aby wysłać zbuforowane zakresy. Aby uzyskać pomoc w dostosowaniu tych fragmentów kodu, użyj narzędzia Tracing Code Gen z pakietu Toolkit.

Eksportowanie rekordów dziennika komunikatów

Niektóre instrumentacje emitują treść komunikatów jako rekordy logów OpenTelemetry, a nie jako atrybuty spanów. Jeśli zdecydujesz się zarejestrować tę zawartość w kontrolowanym teście deweloperskim, dodaj tę konfigurację raz obok poprzedniego dostawcy śledzenia Python:

from opentelemetry import _logs
from opentelemetry.sdk._logs import LoggerProvider
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter

logger_provider = LoggerProvider(resource=provider.resource)
logger_provider.add_log_record_processor(BatchLogRecordProcessor(
    OTLPLogExporter(endpoint="http://localhost:4318/v1/logs")
))
_logs.set_logger_provider(logger_provider)

Dokumentacja: OpenTelemetry Python logging SDK, OTLPLogExporter.

Wywołaj logger_provider.force_flush() przed zakończeniem aplikacji o krótkim czasie działania. Eksporter dziennika nie włącza przechwytywania zawartości samodzielnie. Postępuj zgodnie z ustawieniami zawartości instrumentora i wskazówkami dotyczącymi przetwarzania danych.

Konfiguracja zestawu SDK języka JavaScript i języka TypeScript

W przypadku aplikacji Node.js użyj jednego współdzielonego dostawcy śledzenia i zarejestruj instrumentację w swoim SDK. Ten przykład korzysta z CommonJS i konfiguracji providera OpenTelemetry JavaScript 2.x. Aplikacje TypeScript skompilowane do formatu CommonJS mogą używać tej samej kolejności inicjalizacji.

Aplikacja musi już mieć swój model SDK, poświadczenia i konfigurację modelu. Zainstaluj współużytkowane zależności i instrumentor OpenAI:

npm install @opentelemetry/api @opentelemetry/sdk-trace-node \
  @opentelemetry/sdk-trace-base @opentelemetry/exporter-trace-otlp-proto \
  @opentelemetry/instrumentation @traceloop/instrumentation-openai

Informacje: eksportery JavaScript OpenTelemetry, instrumentacja OpenAI.

Utwórz tracing.cjs:

const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
const { BatchSpanProcessor } = require('@opentelemetry/sdk-trace-base');
const {
  OTLPTraceExporter
} = require('@opentelemetry/exporter-trace-otlp-proto');
const { registerInstrumentations } = require('@opentelemetry/instrumentation');
const { OpenAIInstrumentation } = require('@traceloop/instrumentation-openai');

const provider = new NodeTracerProvider({
  spanProcessors: [
    new BatchSpanProcessor(new OTLPTraceExporter({
      url: 'http://localhost:4318/v1/traces'
    }))
  ]
});
provider.register();

registerInstrumentations({
  instrumentations: [new OpenAIInstrumentation({ traceContent: false })]
});

module.exports = provider;

Odniesienie: NodeTracerProvider, instrumentacja OpenAI.

Załaduj ten plik przed zaimportowaniem lub użyciem require zestawu SDK modelu. Na przykład uruchom polecenie node --require ./tracing.cjs app.cjs dla aplikacji CommonJS. W przypadku innego zestawu SDK zastąp pakiet OpenAI, import i wpis rejestracji pasującym wierszem:

Pakiety Traceloop to instrumentacja firmy innej niż Microsoft. W przypadku aplikacji Foundry Projects application instrumentuj klienta, który wysyła żądanie do modelu. Instrumentacja Azure SDK nie zastępuje instrumentacji OpenAI dla wywołań wykonanych za pośrednictwem klienta OpenAI.

W przypadku natywnych modułów ECMAScript postępuj zgodnie z instrukcjami konfiguracji rozwiązania ESM OpenTelemetry. Ładowanie instrumentacji po załadowaniu docelowego zestawu SDK może pozostawić wywołania nieinstrumentowane. Podczas zamykania poczekaj na provider.shutdown() po ukończeniu żądań, aby wyeksportować buforowane spany.

Inspekcja lokalnych śladów i zarządzanie nimi

Użyj drzewa span, aby śledzić żądanie od orkiestracji agenta po operacje modelu i narzędzi.

1. Wybierz powolny lub nieudany span.
2. Sprawdź czas trwania i stan.
3. Otwórz plik Input + Output dla zarejestrowanych komunikatów, w przypadku dostarczenia przez instrumentację lub metadanych dla atrybutów span.

Przykłady zachowują przechwytywanie poufnych zawartości. Dane czasowe bez komunikatów mogą być oczekiwanym wynikiem.

W przypadku kontrolowanego testu programistycznego Agent Framework ustaw enable_sensitive_data=True w istniejącej konfiguracji, aby rejestrować obsługiwane monity, odpowiedź i zawartość narzędzi. Przywróć go do False po zakończeniu testu. Inne instrumentatory mają własne ustawienia zawartości.

Zebrane ślady są utrwalane w lokalnej bazie danych SQLite o nazwie traces.db, w podkatalogu tracing.aitk w folderze głównym użytkownika. Zamknięcie przeglądarki nie powoduje usunięcia ich.

Wybierz pozycję Zatrzymaj moduł zbierający , aby zatrzymać kolekcję lokalną. Agent i jego model wywołania nadal działają. Aby usunąć rekordy lokalne, wybierz ślady na liście i wybierz pozycję Usuń.

Magazyn lokalny jest oddzielony od usługi Application Insights. Usunięcie lokalnych śladów nie powoduje usunięcia danych telemetrycznych w chmurze i wyczyszczenie konwersacji w inspektorze nie powoduje usunięcia ani magazynu.

Wyświetlanie śladów hostowanych agentów

Po wdrożeniu użyj śladów w chmurze, aby zbadać agenta uruchomionego w narzędziu Foundry, a nie w procesie lokalnym. Zestaw narzędzi wykonuje zapytania dotyczące połączonego zasobu usługi Application Insights w projekcie. Nie przekazuje lokalnej bazy danych śledzenia.

Przed rozpoczęciem potwierdź wymagania wstępne dotyczące chmury . Sam dostęp do agenta nie udziela uprawnień do wykonywania zapytań dotyczących telemetrii.

Łączenie usługi Application Insights i sprawdzanie żądania

Użyj karty Ślady agenta, aby połączyć usługę Application Insights i znaleźć żądanie wdrożonego agenta.

1. Na pasku bocznym zestawu narzędzi Foundry Toolkit otwórz pozycję Moi agenci zasobów>. Wybierz kartę Hostowany agent , a następnie wybierz nazwę agenta.

2. Wybierz pozycję Ślady. Jeśli projekt nie ma połączonego zasobu, wybierz pozycję Włącz usługę App Insights.

3. W obszarze Ustawienia usługi App Insights wybierz istniejącą nazwę zasobu usługi App Insights. Alternatywnie możesz utworzyć zasób i wypełnić wymagane pola zasobu i obszaru roboczego. Wybierz pozycję Prześlij i poczekaj na potwierdzenie.

   Spowoduje to zmianę udostępnionego połączenia usługi Application Insights projektu, a nie preferencji lokalnego obszaru roboczego. Tworzenie zasobów i zbieranie danych telemetrycznych mogą powodować naliczanie opłat platformy Azure. Przed przesłaniem potwierdź właściwy projekt i zasób.

4. Wróć do Playground i wyślij żądanie testowe do wdrożonego agenta.

5. Poczekaj na zakończenie przetwarzania danych, a następnie ponownie otwórz pozycję Traces. Użyj zakresu czasu, filtru wyszukiwania według identyfikatora konwersacji, stanu lub czasu trwania, aby zlokalizować żądanie.

   

6. Wybierz ślad, a następnie span, aby przejrzeć metadane i dane wejściowe i wyjściowe, gdy zawartość jest dostępna.

Aby sprawdzić operacje skojarzone z konwersacją, wybierz jej identyfikator konwersacji na liście śledzenia. Widok konwersacji przedstawia drzewo operacji i metadane.

Połączenie z usługą Application Insights umożliwia śledzenie po stronie serwera w usłudze Foundry. Wgląd w wywołania modelu, wywołania narzędzi i kod niestandardowy również zależą od biblioteki hostującej i instrumentacji frameworka. Zobacz Konfigurowanie śledzenia w narzędziu Foundry na potrzeby zbierania po stronie usługi i dodatkowej instrumentacji klienta.

Zapytanie trace-detail w Toolkit obejmuje obecnie ostatnie siedem dni. Jest to okno zapytania, a nie ustawienie przechowywania. W przypadku starszych danych użyj portalu Foundry lub Azure Monitor, z zastrzeżeniem konfiguracji przechowywania połączonego obszaru roboczego.

Dane, dostęp, przechowywanie i koszty

Zdecyduj, dokąd ma trafiać telemetria przed włączeniem przechwytywania zawartości lub łączeniem zasobu w chmurze. To samo żądanie może generować lokalne spany, dane telemetryczne w chmurze i dane wysyłane do dostawców modeli lub narzędzi.

Skorzystaj ze wskazówek Foundry dotyczących śledzenia w celu zapewnienia bezpieczeństwa i prywatności oraz retencji danych i kosztów. W przypadku tożsamości produkcyjnej, izolacji sieci i dostępu podrzędnego należy postępować zgodnie z zabezpieczeniami i obsługą danych hostowanych agentów. Nie traktuj poświadczeń lokalnych jako uprawnień wdrożonego agenta.

Troubleshooting

Treści powiązane

• Debuguj agentów za pomocą Agent Inspector.
• Pojęcia dotyczące śledzenia agentów.
• Skonfiguruj śledzenie po stronie klienta.