# Spannweiten, Ereignisaufzeichnungen und Telemetriesignale
<a name="supported-frameworks-telemetry"></a>

Amazon Bedrock AgentCore Evaluations verarbeitet zwei Telemetriesignale, um das Verhalten Ihres Agenten zu verstehen:
+  **Spans beschreiben einzelne** Operationen. Eine Spanne enthält Metadaten zu einer Operation: ihren Namen, Umfang, Zeitstempel und Attribute. Ein Bereich kann auch den Inhalt der Konversation enthalten, oder dieser Inhalt kann sich in einem separaten Ereignisdatensatz befinden.
+  **Ereignisdatensätze** enthalten Nutzdateninhalte in einem `body` Feld: die Eingaben und Ausgaben von Modellen, Tools und dem Agenten. Ein Ereignisdatensatz wird mit seiner Spanne durch ein gemeinsames `traceId` und korreliert. `spanId` Für die Aufzeichnung von OpenTelemetry Ereignissen gelten die üblichen Regeln. Weitere Informationen finden Sie unter [Referenzen](#supported-frameworks-telemetry-references).

Um eine Sitzung auszuwerten, benötigt der Service sowohl die Zeitspannen als auch gegebenenfalls die zugehörigen Ereignisdatensätze. Für jede Spanne führt der Service Folgendes aus:

1. Identifiziert den Typ der Spanne anhand von Framework-spezifischen Attributen. Einzelheiten finden Sie auf den einzelnen Framework-Seiten.

1. Liest die benötigten Werte, z. B. die Benutzeraufforderung, die Antwort des Agenten sowie die Eingaben und Ausgaben des Tools. Diese Werte stammen aus den Attributen der Spanne oder aus dem zugehörigen Ereignisdatensatz.

 **Topics** 
+  [Wie teilt ADOT Telemetrie](#supported-frameworks-telemetry-collection) 
+  [Wo Spans und Ereignisaufzeichnungen gespeichert werden](#supported-frameworks-telemetry-location) 
+  [Wo der Dienst Inhalte liest](#supported-frameworks-telemetry-extraction) 
+  [Referenzen](#supported-frameworks-telemetry-references) 

## Wie teilt ADOT Telemetrie
<a name="supported-frameworks-telemetry-collection"></a>

**Wenn Ihr Agent mit der AWS Distribution for OpenTelemetry (ADOT) ausgeführt wird, wird die Telemetrie aufgeteilt.** **Beim Export von Spans extrahiert ADOT den umfangreichen Inhalt der Konversation (Eingabeaufforderungen und -abschlüsse im Modell, Eingaben und Ausgaben von Tools) aus den Span-Attributen und gibt ihn als separate Ereignisdatensätze aus.** Die resultierende Spanne enthält nur Metadaten und kleine Attribute.

Durch diese Aufteilung wird die Anzahl der Dokumente klein gehalten, obwohl der gesamte Inhalt der Konversation in den Ereignisdatensätzen erhalten bleibt.

```
                          ADOT collection (split)

   Instrumented agent
          |
          |  span with attributes + content
          v
   +--------------------+
   |       ADOT         |  extracts conversation content
   +--------------------+
          |                          |
          | span                     | event record(s)
          | (metadata, attributes)   | (body: input / output messages)
          v                          v
   +--------------------+   +-----------------------+
   |  aws/spans         |   |  event-record         |
   |  log group         |   |  log group            |
   +--------------------+   +-----------------------+
          |                          |
          +-----------+--------------+
                      v
            Evaluation service
       (joins span + event record by traceId / spanId)
```

Nach der Aufteilung befindet sich der Inhalt der Konversation im Ereignisdatensatz `body` (z. B. `body.input.messages` und`body.output.messages`), und der Bereich enthält die identifizierenden Attribute, mit denen er klassifiziert wurde.

## Wo Zeitspannen und Ereignisdatensätze gespeichert werden
<a name="supported-frameworks-telemetry-location"></a>

**Wenn ADOT Telemetriedaten erfasst, exportiert es Spannweiten und Ereignisaufzeichnungen nach Amazon CloudWatch, jedoch an verschiedene Standorte.**
+  **Spans** werden in der Protokollgruppe gespeichert. `aws/spans` Diese Protokollgruppe wird erstellt, wenn die **Transaktionssuche** aktiviert ist. Dies ist eine Voraussetzung für die Auswertung. Einzelheiten zur Aktivierung der Transaktionssuche finden Sie unter [AgentCore Observability](observability-telemetry.md).
+  **Ereignisdatensätze** werden in einer Protokollgruppe gespeichert, die davon abhängt, wo Ihr Agent gehostet wird:
  +  **Auf Amazon Bedrock AgentCore Runtime**: Die Runtime gibt Ereignisdatensätze an ihre Protokollgruppe im `otel-rt-logs` Protokollstream aus und konfiguriert diesen Export für Sie. `/aws/bedrock-agentcore/runtimes/<agent_id>-<endpoint_name>`
  +  **Außerhalb von AgentCore Runtime gehostet** (z. B. auf Amazon Elastic Container Service (Amazon ECS), Amazon Elastic Kubernetes Service (Amazon EKS) oder AWS Lambda): Ihr Agent sendet Ereignisdatensätze an die Protokollgruppe, die Sie über die Umgebungsvariable konfigurieren. `OTEL_EXPORTER_OTLP_LOGS_HEADERS`

Um eine Sitzung auszuwerten, liest der Service Spans aus `aws/spans` und verknüpft sie mit ihren korrelierten Ereignisdatensätzen aus der entsprechenden Protokollgruppe.

## Wo der Dienst Inhalte liest
<a name="supported-frameworks-telemetry-extraction"></a>

Konversationsinhalte können sich je nach Framework und Instrumentierungsbibliothek an verschiedenen Orten befinden. Der Bewertungsdienst liest sie von dem Ort aus, an dem sie gespeichert sind:
+  **Hauptteil des Ereignisdatensatzes**: Wenn ADOT den Inhalt in einen separaten Ereignisdatensatz aufteilt (oben beschrieben), liest der Dienst ihn aus dem Ereignisdatensatz, der der Spanne `body` entspricht.
+  **Span-Attribute**: In einigen Instrumentierungsbibliotheken wird der Inhalt des Bereichs als Attribute gespeichert.
+  **Inline-Span-Ereignisse**: Einige Instrumentierungsbibliotheken fügen den Inhalt dem Span als Inline-Ereignisse hinzu.

Die identifizierenden Attribute, die zur Klassifizierung einer Spanne verwendet werden, verbleiben in jedem Fall in der Span. Dazu gehört auch das Attribut, das einen Bereich als Span für Invoke Agent oder Execute Tool kennzeichnet. Lediglich der Speicherort der größeren Konversationsinhalte unterscheidet sich. Auf den Framework-Seiten werden sowohl die identifizierenden Attribute als auch die Inhaltsverzeichnisse für jede Instrumentierungsbibliothek aufgeführt.

## Referenzen
<a name="supported-frameworks-telemetry-references"></a>

Diese OpenTelemetry Spezifikationen beschreiben die Konventionen, auf denen AgentCore Evaluationen aufbauen:
+  [Semantische Konventionen im Trace](https://opentelemetry.io/docs/specs/semconv/general/trace/): Struktur und Semantik von Spans und Traces.
+  [Semantische Konventionen für Ereignisse](https://opentelemetry.io/docs/specs/semconv/general/events/): Struktur und Semantik von Ereignisaufzeichnungen.
+  [Generative-AI Semantische Konventionen](https://github.com/open-telemetry/semantic-conventions-genai): die `gen_ai.*` Attribute, die zur Beschreibung von Agenten-, Modell- und Werkzeugoperationen verwendet werden.