Freigeben über

Microsoft-Agenten-Framework-Workflows – Observierbarkeit

Observability bietet Einblicke in den internen Zustand und das Verhalten von Workflows während der Ausführung. Dazu gehören Protokollierungs-, Metrik- und Ablaufverfolgungsfunktionen, mit denen Workflows überwacht und gedebuggt werden können.

Tipp

Observability ist ein frameworkweites Feature und ist nicht auf Workflows beschränkt. Weitere Informationen finden Sie unter Observability.

Neben der standardmäßigen GenAI-Telemetrie emittiert Agent Framework-Workflows zusätzliche Spannen, Protokolle und Metriken, um tiefere Einblicke in die Workflowausführung zu erhalten. Diese Observability-Features helfen Entwicklern, den Nachrichtenfluss, die Leistung von Executoren und alle möglicherweise auftretenden Fehler zu verstehen.

Beobachtbarkeit aktivieren

Anweisungen zum Aktivieren der Observierbarkeit in Ihren Anwendungen finden Sie unter " Aktivieren der Observierbarkeit ".

Anweisungen zum Aktivieren der Observierbarkeit in Ihren Anwendungen finden Sie unter " Aktivieren der Observierbarkeit ".

Workflow-Bereiche

Die folgenden Spannen werden während der Workflowausführung ausgegeben:

SpanName Description
workflow.build Wird für jeden Workflow-Build ausgegeben.
workflow.session Äußere Spanne, die die gesamte Lebensdauer einer Workflowausführung darstellt, von Anfang bis Ende oder Fehler.
workflow_invoke Wird für jeden Eingabe-Stopp-Zyklus innerhalb einer Workflowsitzung ausgegeben.
executor.process {executor_id} Wird für jeden Executor ausgegeben, der eine Nachricht verarbeitet. Die Executor-ID wird an den Span-Namen angefügt.
edge_group.process Wird für jede Edge-Gruppe ausgegeben, die eine Nachricht bearbeitet.
message.send Wird für jede Nachricht ausgegeben, die von einem Executor an einen anderen Executor gesendet wurde.

Die folgenden Spannen werden während der Workflowausführung ausgegeben:

SpanName Description
workflow.build Wird für jeden Workflow-Build ausgegeben.
workflow.run Wird für jede Workflowausführung ausgegeben.
executor.process {executor_id} Wird für jeden Executor ausgegeben, der eine Nachricht verarbeitet. Die Executor-ID wird an den Span-Namen angefügt.
edge_group.process {edge_group_type} Wird für jede Edge-Gruppe ausgegeben, die eine Nachricht verarbeitet. Der Randgruppentyp wird an den Span-Namen angefügt.
message.send Wird für jede Nachricht ausgelöst, die von einem Executor an einen anderen Executor gesendet wurde.

Span-Attribut

Spans tragen Attribute, die zusätzlichen Kontext zu dem Vorgang bereitstellen. Die folgenden Attribute werden für Workflowspannen festgelegt:

Merkmal Spannweite(n) Description
workflow.id workflow.build, workflow.session Der eindeutige Bezeichner des Workflows.
workflow.name workflow.session Der Name des Workflows.
workflow.description workflow.session Die Beschreibung des Workflows.
workflow.definition workflow.build Die JSON-Definition des Workflowdiagramms.
session.id workflow.session Der eindeutige Sitzungsbezeichner.
executor.id executor.process Der eindeutige Bezeichner des Executors.
executor.type executor.process Der Typname des Executors.
executor.input executor.process Die Eingabemeldung. Nur festgelegt, wenn vertrauliche Daten aktiviert sind.
executor.output executor.process Die Ausgabe des Executors. Nur festgelegt, wenn vertrauliche Daten aktiviert sind.
message.type executor.process, message.send Der Typname der Nachricht.
message.content message.send Der Nachrichteninhalt. Nur festgelegt, wenn vertrauliche Daten aktiviert sind.
message.source_id message.send Die ID des Ausführenden, der die Nachricht gesendet hat.
message.target_id message.send Die ID des Zielausführers, sofern angegeben.
edge_group.type edge_group.process Der Typ der Randgruppe.
edge_group.delivered edge_group.process Gibt an, ob die Nachricht zugestellt wurde (boolescher Wert).
edge_group.delivery_status edge_group.process Das Übermittlungsergebnis (siehe Edge-Gruppen-Übermittlungsstatus).
error.type Ein beliebiger Abschnitt mit Fehler Der Name des Ausnahmetyps.
Merkmal Spanne(n) Description
workflow.id workflow.build, workflow.run Der eindeutige Bezeichner des Workflows.
workflow.name workflow.run Der Name des Workflows.
workflow.description workflow.run Die Beschreibung des Workflows.
workflow.definition workflow.build Die JSON-Definition des Workflowdiagramms.
workflow_builder.name workflow.build Der Name des Workflow-Generators.
workflow_builder.description workflow.build Die Beschreibung des Workflow-Generators.
executor.id executor.process Der eindeutige Bezeichner des Ausführenden.
executor.type executor.process Der Typname des Executors.
message.type executor.process, message.send Der Typname der Nachricht.
message.payload_type executor.process Der Datentyp der Nachrichtennutzlast.
message.destination_executor_id message.send Die ID des Zielausführers, sofern angegeben.
message.source_id edge_group.process Die ID des Ausführenden, der die Nachricht gesendet hat.
message.target_id edge_group.process Die ID des Zielausführers, sofern angegeben.
edge_group.type edge_group.process Der Typ der Randgruppe.
edge_group.id edge_group.process Der eindeutige Bezeichner der Edge-Gruppe.
edge_group.delivered edge_group.process Gibt an, ob die Nachricht zugestellt wurde (boolescher Wert).
edge_group.delivery_status edge_group.process Das Übermittlungsergebnis (siehe Edge-Gruppen-Übermittlungsstatus).

Span-Ereignisse

Span-Ereignisse sind strukturierte Protokolleinträge, die an eine Spanne angefügt werden. Sie stellen eine Zeitachse bereit, die wichtige Momente innerhalb jeder Spanne aufzeigt.

Ereignisname Spanne(n) Description
build.started workflow.build Wird ausgegeben, wenn der Buildprozess beginnt.
build.validation_completed workflow.build Wird ausgegeben, wenn die Buildvalidierung erfolgreich ist.
build.completed workflow.build Wird ausgegeben, wenn der Build erfolgreich abgeschlossen wurde.
build.error workflow.build Wird ausgegeben, wenn der Build fehlschlägt.
session.started workflow.session Wird ausgegeben, wenn eine Workflowsitzung beginnt.
session.completed workflow.session Wird ausgegeben, wenn eine Workflowsitzung abgeschlossen ist.
session.error workflow.session Wird ausgegeben, wenn bei einer Workflowsitzung ein Fehler auftritt.
workflow.started workflow_invoke Wird ausgegeben, wenn ein Workflowaufruf beginnt.
workflow.completed workflow_invoke Wird ausgegeben, wenn ein Workflowaufruf abgeschlossen ist.
workflow.error workflow_invoke Wird ausgegeben, wenn bei einem Workflowaufruf ein Fehler auftritt.
Ereignisname Spanne(n) Description
build.started workflow.build Wird ausgegeben, wenn der Buildprozess beginnt.
build.validation_completed workflow.build Wird ausgelöst, wenn die Build-Validierung bestanden wird.
build.completed workflow.build Wird ausgegeben, wenn der Build erfolgreich abgeschlossen wurde.
build.error workflow.build Wird ausgelöst, wenn der Build fehlschlägt.
workflow.started workflow.run Wird ausgegeben, wenn eine Workflowausführung beginnt.
workflow.completed workflow.run Wird ausgegeben, wenn eine Workflowausführung abgeschlossen ist.
workflow.error workflow.run Wird ausgegeben, wenn eine Workflowausführung auf einen Fehler stößt.

Wenn ein Executor eine Nachricht an einen anderen Executor sendet, wird die message.send Spanne als untergeordnetes Element der executor.process Spanne erstellt. Der executor.process Spanne des Ziel-Executors ist jedoch kein Kind der message.send Spanne, da die Ausführung nicht geschachtelt ist. Stattdessen wird der executor.process Bereich des Zielausführers mit der Spanne des Quellausführers message.send. Diese Verknüpfung erstellt einen nachverfolgbaren Pfad durch die Workflowausführung, ohne eine geschachtelte Aufrufhierarchie implizieren zu müssen.

Der gleiche Verknüpfungsansatz gilt für edge_group.process Spannen, die mit der Quellspanne message.send für die Kausalitätsnachverfolgung verknüpft sind. Dies unterstützt Fan-In-Szenarien, in denen mehrere Quellspannen zu einer einzelnen Verarbeitungsspanne beitragen.

Edge-Gruppe Zustellungsstatus

Die Verarbeitung von Edge-Gruppen umfasst Übermittlungsstatusattribute, die das Ergebnis der Nachrichtenweiterleitung durch jede Edge-Gruppe angeben. Das edge_group.delivery_status Attribut wird auf einen der folgenden Werte festgelegt:

Status Description
delivered Die Nachricht wurde an den ausführenden Zielrechner übermittelt.
dropped type mismatch Der Zielausführer kann den Nachrichtentyp nicht verarbeiten.
dropped target mismatch Die Nachricht hat ein Ziel angegeben, das nicht mit diesem Rand übereinstimmt.
dropped condition false Die Randverbindungsbedingung wurde als falsch ausgewertet.
exception Eine Ausnahme trat während der Edge-Verarbeitung auf.
buffered Die Nachricht wurde gepuffert und wartet auf zusätzliche Nachrichten (Fan-In).

Das edge_group.delivered boolesche Attribut stellt eine schnelle Überprüfung bereit, ob die Nachricht erfolgreich zugestellt wurde.

Telemetriekonfiguration

Workflow-Telemetrie kann über die WithOpenTelemetry Erweiterungsmethode im Workflow-Generator aktiviert werden. Die WorkflowTelemetryOptions Klasse bietet eine feinkörnige Kontrolle darüber, welche Spannen ausgegeben werden:

Auswahl Vorgabe Description
EnableSensitiveData false Umfasst unformatierte Eingaben, Ausgaben und Nachrichteninhalte in Span-Attributen.
DisableWorkflowBuild false workflow.build Deaktiviert Spannweiten.
DisableWorkflowRun false workflow.session und workflow_invoke deaktivieren.
DisableExecutorProcess false executor.process Deaktiviert Spannweiten.
DisableEdgeGroupProcess false edge_group.process Deaktiviert Spannweiten.
DisableMessageSend false message.send Deaktiviert Spannweiten.

Warnung

Durch Aktivieren sensibler Daten werden rohe Nachrichteninhalte, Executor-Eingaben und Executor-Ausgaben in die Telemetrie einbezogen. Aktivieren Sie dies nur in sicheren Umgebungen, in denen Telemetriedaten entsprechend geschützt sind.

Workflow-Telemetrie wird über die globale enable_instrumentation() Funktion aktiviert. Wenn die Instrumentierung aktiviert ist, werden alle Workflow-Spans automatisch ausgegeben. Die configure_otel_providers() Funktion kann zum Konfigurieren von Exportern für Traces, Metriken und Protokolle verwendet werden.

Warnung

Überprüfen Sie Ihre Telemetriepipelinekonfiguration, um sicherzustellen, dass vertrauliche Daten beim Exportieren von Traces angemessen geschützt sind.

Nächste Schritte

  • Last updated on