Einrichten der Ablaufverfolgung in Microsoft Foundry

Wichtig

In diesem Artikel markierte Elemente (Vorschau) befinden sich derzeit in der öffentlichen Vorschau. Diese Vorschau wird ohne Vereinbarung auf Serviceebene bereitgestellt und wird für Produktionsworkloads nicht empfohlen. Bestimmte Features werden möglicherweise nicht unterstützt oder weisen eingeschränkte Funktionen auf. Weitere Informationen finden Sie unter Supplementale Nutzungsbedingungen für Microsoft Azure Previews.

Hinweis

Die Ablaufverfolgung ist grundsätzlich für Prompt- und gehostete Agents verfügbar. Der Workflow und externe Agenten sind als Vorschau verfügbar.

Verwenden Sie die Ablaufverfolgung, um Ihre KI-Agenten zu debuggen und ihr Verhalten in der Produktionsumgebung zu überwachen. Die Ablaufverfolgung erfasst detaillierte Telemetrie – einschließlich Latenz, Ausnahmen, Eingabeaufforderungsinhalte und Abrufvorgänge – damit Sie Probleme schneller identifizieren und beheben können.

Der empfohlene Einstieg ist serverseitiges Tracing. Foundry aktiviert sie automatisch, nachdem Sie eine Application Insights-Ressource mit Ihrem Projekt verbunden haben. Es sind keine Codeänderungen erforderlich, und Ablaufverfolgungen sind innerhalb von Minuten nach der Aktivierung verfügbar. Die serverseitige Nachverfolgung funktioniert für alle in Foundry gehosteten Agenten. Wenn Sie einen Einblick in Ihren eigenen Anwendungscode benötigen, z. B. um benutzerdefinierte Logik rund um den Aufruf eines Agenten nachzuverfolgen, können Sie in einem zweiten Schritt clientseitige Instrumentierung hinzufügen.

Die Microsoft Foundry Skill kann bei der Auswahl zwischen serverseitiger und clientseitiger Ablaufverfolgung sowie bei der Behebung fehlender Telemetriedaten helfen.

Voraussetzungen

Verbinden von Application Insights mit Ihrem Foundry-Projekt

Foundry speichert Ablaufverfolgungen in Application Insights unter Verwendung von OpenTelemetry-Semantikkonventionen.

  1. Melden Sie sich bei Microsoft Foundry an. Stellen Sie sicher, dass die Umschaltfläche "Neue Gießerei " aktiviert ist. Diese Schritte beziehen sich auf Foundry (neu).

  2. Öffnen Sie Ihr Foundry-Projekt.

  3. Wählen Sie im linken Navigationsbereich "Agents" aus.

  4. Wählen Sie oben Ablaufverfolgungen aus.

  5. Wählen Sie auf der rechten Seite "Verbinden" aus, um eine Application Insights-Ressource zu erstellen oder zu verbinden.

    Screenshot der Registerkarte

  • Um eine vorhandene Ressource zu verbinden, wählen Sie die Ressource aus, und wählen Sie dann "Verbinden" aus.
  • Um eine neue Ressource zu erstellen, wählen Sie "Neu erstellen" aus, und schließen Sie dann den Assistenten ab.

Eine Bestätigungsmeldung wird angezeigt, wenn die Verbindung erfolgreich ist.

Verwenden Sie den Verbindungspfad für die Projektdetails.

Wenn die Meldungsleiste oder die Schaltfläche "Verbinden" nicht angezeigt wird, verwenden Sie diese alternative Methode, um Azure Monitor Application Insights zu aktivieren.

  1. Wählen Sie "Verwalten" in der oberen rechten Navigationsleiste aus, und wählen Sie dann Project Details aus. Screenshot des Abschnitts
  2. Wählen Sie die Registerkarte "Verbundene Ressourcen " und dann " Verbindung hinzufügen" aus. Screenshot der Projektdetails mit ausgewählter Registerkarte „Verbundene Ressourcen“ und hervorgehobener Schaltfläche „Verbindung hinzufügen“.
  3. Wählen Sie in "Verbindung auswählen" die Option "Application Insights" aus. Screenshot von

Informationen zur Entra-authentifizierten Traceerfassung finden Sie unter Microsoft Entra-Authentifizierung für die Traceerfassung des Foundry-Agents konfigurieren (Vorschau).

Nachdem Sie die Ressource verbunden haben, kann Ihr Projekt die Ablaufverfolgung verwenden.

Wichtig

Stellen Sie sicher, dass Sie über die erforderlichen Berechtigungen zum Abfragen der Telemetrie verfügen.

Instrument KI-Agenten

Wählen Sie den Ansatz, der der Erstellung und dem Betrieb Ihres Agents entspricht.

Serverseitige Ablaufverfolgungen im Foundry-Portal

Beginnen Sie mit serverseitigem Tracing. Foundry loggt Spuren für allgemeine Agenten- und Workflowszenarien, ohne Ihren Code zu ändern.

  • Foundry protokolliert automatisch serverseitige Ablaufverfolgungen für Prompt-Agents, Host-Agents und Workflows im Foundry-Portal. Nachdem die Ablaufverfolgung in Ihrem Foundry-Projekt aktiviert wurde, haben Sie Zugriff auf sofort einsatzbereite Ablaufverfolgungen für die letzten 90 Tage.
  • Foundry unterstützt auch eine einfache Integration in top-Agent-Frameworks.

Clientseitige Ablaufverfolgungen mit dem Microsoft Foundry SDK (Python)

Installieren Sie OpenTelemetry und das Azure SDK-Ablaufverfolgungs-Plug-In mithilfe der folgenden Schritte:

pip install azure-ai-projects azure-identity opentelemetry-sdk azure-core-tracing-opentelemetry

Referenz: azure-ai-projects, azure-core-tracing-opentelemetry

Wichtig

Um den Endpunkt eines Projekts in Ihrer Anwendung zu verwenden, müssen Sie Microsoft Entra ID konfigurieren. Wenn Sie Microsoft Entra ID nicht konfigurieren, verwenden Sie die Application Insights-Verbindungszeichenfolge.

Nachdem Sie Ihren Agent ausgeführt haben, können Sie Ablaufverfolgungen im Foundry-Portal anzeigen und analysieren.

Ausführliche Anweisungen und SDK-spezifische Codebeispiele finden Sie unter Tracing with azure-ai-projects (Python SDK) und Telemetry samples for agents.

Lokal nachverfolgen mit der Microsoft Foundry Toolkit-Erweiterung für Visual Studio Code

Mit der Erweiterung für Microsoft Foundry Toolkit for Visual Studio Code können Sie lokal in VS Code nachverfolgen, indem Sie einen lokalen OTLP-kompatiblen Collector verwenden. Dieser Ansatz eignet sich ideal für die Entwicklung und das Debuggen.

Das Toolkit unterstützt KI-Frameworks wie Foundry Agent Service, OpenAI, Anthropic und LangChain über OpenTelemetry. Sie können Traces sofort in VS Code sehen, ohne auf die Cloud zugreifen zu müssen.

Ausführliche Einrichtungsanweisungen und SDK-spezifische Codebeispiele finden Sie unter Ablaufverfolgung im Foundry Toolkit.

Anzeigen und Analysieren von Ablaufverfolgungen

Anzeigen von Ablaufverfolgungen im Foundry-Portal

Wechseln Sie in Ihrem Foundry-Projekt zur Registerkarte Ablaufverfolgungen in Ihren Agents oder Workflows. Sie können erfasste Ablaufverfolgungen der letzten 90 Tage durchsuchen, filtern oder sortieren.

Wählen Sie eine Ablaufverfolgung aus, um die einzelnen Abschnitte zu durchlaufen, Probleme zu identifizieren und zu beobachten, wie Ihre Anwendung reagiert. Dieser Prozess hilft Ihnen beim Debuggen und Anheften von Problemen in Ihrer Anwendung.

Anzeigen von Ablaufverfolgungen in Azure Monitor

Ihre Protokollierungsdaten werden an Azure Monitor Application Insights gesendet, sodass Sie sie dort anzeigen können.

Weitere Informationen darüber, wie Sie Traces an Azure Monitor senden und eine Azure-Monitor-Ressource erstellen, finden Sie in der Azure Monitor OpenTelemetry-Dokumentation.

Unterhaltungsergebnisse anzeigen

Eine Konversation ist der permanente Kontext von End-to-End-Dialogverläufen zwischen einem Benutzer und einem Agenten. Im Foundry-Portal können Sie die Ergebnisse der Unterhaltung für Ihre Agent-Ausführung sofort anzeigen, zusammen mit den Ablaufverfolgungen auf der Seite Ablaufverfolgungen.

Suchen Sie anhand der Antwort-ID oder einer Trace-ID, die dieser Unterhaltung zugeordnet ist. Wählen Sie dann eine Conversation-ID aus, um sie zu überprüfen:

  • Gesprächsverlaufsdetails
  • Antwortinformationen und Token in einer Ausführung
  • Sortierte Aktionen, Ausführen von Schritten und Toolaufrufen
  • Eingaben und Ausgaben zwischen einem Benutzer und einem Agent

Screenshot des Bereichs „Unterhaltungsdetails“ in Foundry, auf dem eine Unterhaltungs-ID mit einer Ablaufverfolgungszeitachse und Details zum Ausführungsschritt zu sehen ist.

Überprüfen, ob die Ablaufverfolgung funktioniert

  1. Vergewissern Sie sich, dass Ihr Projekt mit Application Insights verbunden ist. Führen Sie bei Bedarf die Schritte in Connect Application Insights mit Ihrem Foundry-Projekt aus.

  2. Führen Sie Ihren Agent oder Workflow mindestens einmal aus (z. B. mithilfe des Portals oder Ihrer App).

  3. Öffnen Sie in Ihrem Foundry-Projekt die Ansicht Ablaufverfolgungen, und vergewissern Sie sich, dass eine neue Ablaufverfolgung angezeigt wird.

    Wenn die Ablaufverfolgung ordnungsgemäß funktioniert, wird eine Liste der letzten Ablaufverfolgungen mit Zeitstempeln, Dauer und Statusindikatoren angezeigt. Wählen Sie eine Leiterbahn aus, um deren Spannweite anzuzeigen.

Wenn Sie keine neuen Ablaufverfolgungen sehen, warten Sie ein paar Minuten, aktualisieren Sie, und beachten Sie dann die Informationen unter Problembehandlung.

Sicherheit und Datenschutz

Die Nachverfolgung kann sensible Informationen erfassen, z. B. Benutzereingaben, Modellausgaben sowie Argumente und Ergebnisse von Tools. Verwenden Sie diese Methoden, um Risiken zu reduzieren:

  • Speichern Sie geheime Schlüssel, Anmeldeinformationen oder Token nicht in Eingabeaufforderungen, Toolargumenten oder Span-Attributen.
  • Reduzieren oder entfernen Sie persönliche Daten und andere sensible Inhalte, bevor sie in der Telemetrie erscheinen.
  • Behandeln Sie Ablaufverfolgungsdaten als Produktionstelemetrie, und wenden Sie dieselben Zugriffssteuerungen und Aufbewahrungsrichtlinien an, die Sie für Protokolle und Metriken verwenden.

Weitere Anleitungen finden Sie unter "Sicherheit und Datenschutz".

Datenaufbewahrung und Kosten

Foundry speichert Protokolle in der mit Ihrem Projekt verbundenen Application Insights-Ressource. Die Datenaufbewahrung und -abrechnung folgen Ihrer Application Insights- und Log Analytics-Konfigurationen.

Problembehandlung

Angelegenheit Ursache Auflösung
Im Foundry-Portal werden keine Spuren angezeigt. Die Ablaufverfolgung ist nicht verbunden, es gibt keinen aktuellen Datenverkehr, oder die Erfassung ist verzögert. Bestätigen Sie die Verbindung von Application Insights, generieren Sie neuen Agentenverkehr, und aktualisieren Sie nach einigen Minuten.
Beim Abfragen oder Anzeigen von Telemetrie werden Autorisierungsfehler angezeigt. Fehlende RBAC-Berechtigungen für Application Insights oder Log Analytics Bestätigen Sie den Zugriff in access control (IAM) für die verbundenen Ressourcen. Weisen Sie für Protokollabfragen die Rolle Log Analytics Reader zu. Wenn die Tabellen geschützt sind, weisen Sie auch privileged Monitoring Data Reader zu.
Clientseitige Ablaufverfolgungen werden nicht angezeigt. Die Instrumentation ist nicht installiert oder konfiguriert. Überprüfen Sie die Paketinstallation erneut, und befolgen Sie die SDK-Anleitungen, die in Clientseitige Ablaufverfolgungen mit dem Microsoft Foundry SDK (Python) verknüpft sind.
Sensible Inhalte werden in Ablaufverfolgungen angezeigt. Eingabeaufforderungen, Toolargumente oder Ausgaben enthalten vertrauliche Daten. Vertrauliche Daten verbergen, bevor sie in die Telemetrie gelangen und den Anweisungen in Sicherheit und Datenschutz folgen.

Verwandte Inhalte

Jetzt, da Sie die Ablaufverfolgung eingerichtet haben, erkunden Sie diese Ressourcen, um Ihr Verständnis zu vertiefen und Ihre Observability-Funktionen zu erweitern:

  • Last updated on