# Erweitern Sie Ihre Amazon AgentCore Bedrock-Ressourcen um Beobachtbarkeit Amazon Bedrock AgentCore bietet eine Reihe integrierter Metriken zur Überwachung der Leistung von Ressourcen für die Typen AgentCore Runtime, Memory, Gateway, integrierte Tools und Identitätsressourcen. Diese Standarddaten sind in Amazon verfügbar CloudWatch. Um das gesamte Spektrum der Observability-Daten in der CloudWatch Konsole anzuzeigen oder benutzerdefinierte Laufzeitmetriken für Agenten auszugeben, müssen Sie Ihren Code mit dem AWS Distro for Open Telemetry (ADOT) SDK instrumentieren. Um das Observability-Dashboard in aufzurufen CloudWatch, öffnen Sie die [Amazon CloudWatch GenAi Observability-Seite](https://console.aws.amazon.com/cloudwatch/home#gen-ai-observability). In den folgenden Abschnitten erfahren Sie mehr über die Konfiguration Ihrer Ressourcen zur Anzeige von Observability-Metriken auf der generativen KI-Observability-Seite der CloudWatch Konsole und in Logs. CloudWatch **Tipp** Die Verwendung des ADOT SDK zur Ausgabe benutzerdefinierter Metriken wird auch für Agenten unterstützt, die außerhalb der Laufzeit ausgeführt werden. AgentCore Informationen zum Aktivieren der Observability für diese Agenten finden Sie unter [Observability für Agenten aktivieren, die außerhalb von gehostet werden](#observability-configure-3p). AgentCore **Topics** + [Observability aktivieren AgentCore](#observability-configure-builtin) + [Aktivierung der Beobachtbarkeit im Agentencode für Agenten AgentCore-hosted](#observability-configure-custom) + [Aktivierung der Beobachtbarkeit für Agenten, die außerhalb von gehostet werden AgentCore](#observability-configure-3p) + [Aktivierung von Observability für AgentCore Laufzeit-, Speicher-, Gateway-, integrierte Tools und Identitätsressourcen](#observability-configure-cloudwatch) + [Verbesserte AgentCore Laufzeitbeobachtbarkeit mit benutzerdefinierten Headern](#observability-configure-invoke) + [Verbesserte Beobachtbarkeit der AgentCore integrierten Tools mit benutzerdefinierten Headern](#observability-configure-built-in) + [Verbesserte AgentCore Identitätserkennbarkeit mit benutzerdefinierten Headern](#observability-configure-identity) + [Bewährte Verfahren zur Beobachtbarkeit](#observability-configure-best-practice) + [Verwendung anderer Observability-Plattformen](#observability-configure-3p-platforms) ## Observability aktivieren AgentCore Um die vom AgentCore Service generierten Metriken, Spans und Traces anzuzeigen, müssen Sie zunächst eine einmalige Einrichtung durchführen, um Amazon CloudWatch Transaction Search zu aktivieren. Um die vom Service bereitgestellten Spans für Speicherressourcen anzuzeigen, müssen Sie bei der Erstellung eines Speichers auch die Ablaufverfolgung aktivieren. Weitere Informationen finden Sie unter [Aktivieren von Observability für AgentCore Laufzeit-, Speicher-, Gateway-, integrierte Tools und Identitätsressourcen](#observability-configure-cloudwatch). In den folgenden Abschnitten wird beschrieben, wie Sie diese Setup-Aktionen ausführen und Observability in Ihrem Agentencode aktivieren. ### CloudWatch Transaktionssuche aktivieren Sie können die CloudWatch Transaktionssuche entweder mithilfe der CloudWatch Konsole oder mithilfe einer API über die AWS Befehlszeilenschnittstelle (AWS CLI) oder eines der AWS SDKs aktivieren. Verwenden Sie eines der folgenden Verfahren, um die Transaktionssuche zu aktivieren. **Example** 1. ====== Um die CloudWatch Transaktionssuche in der CloudWatch Konsole zu aktivieren 1. Öffnen Sie die [CloudWatch-Konsole](https://console.aws.amazon.com/cloudwatch). 1. Erweitern Sie im Navigationsbereich **Application Signals (APM)** und wählen Sie **Transaktionssuche** aus. 1. Wählen Sie **Transaktionssuche aktivieren**. 1. Aktivieren Sie das Kontrollkästchen, um Spans als strukturierte Logs aufzunehmen. 1. Wählen Sie **Speichern**. 1. ====== Um die CloudWatch Transaktionssuche mithilfe einer API zu aktivieren 1. Wenn Sie die AWS CLI oder ein AWS SDK verwenden, um die Transaktionssuche zu aktivieren, konfigurieren Sie zunächst die erforderlichen Berechtigungen, um Spans in CloudWatch Logs aufzunehmen, indem Sie eine ressourcenbasierte Richtlinie mit hinzufügen. [PutResourcePolicy](https://docs.aws.amazon.com/xray/latest/api/API_PutResourcePolicy.html) Der folgende AWS CLI-Befehl fügt eine Ressourcenrichtlinie hinzu, die AWS X-Ray Berechtigungen zum Senden von Traces an CloudWatch Logs erteilt. ``` aws logs put-resource-policy --policy-name MyResourcePolicy --policy-document '{ "Version": "2012-10-17", "Statement": [ { "Sid": "TransactionSearchXRayAccess", "Effect": "Allow", "Principal": { "Service": "xray.amazonaws.com" }, "Action": "logs:PutLogEvents", "Resource": [ "arn:partition:logs:region:account-id:log-group:aws/spans:*", "arn:partition:logs:region:account-id:log-group:/aws/application-signals/data:*" ], "Condition": { "ArnLike": { "aws:SourceArn": "arn:partition:logs:region:account-id:*" }, "StringEquals": { "aws:SourceAccount": "account-id" } } } ]}' ``` Der Übersichtlichkeit halber wird die Inline-JSON-Richtlinie in diesem Befehl im folgenden Beispiel erweitert dargestellt: ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "TransactionSearchXRayAccess", "Effect": "Allow", "Principal": { "Service": "xray.amazonaws.com" }, "Action": "logs:PutLogEvents", "Resource": [ "arn:aws:logs:us-east-1:123456789012:log-group:aws/spans:*", "arn:aws:logs:us-east-1:123456789012:log-group:/aws/application-signals/data:*" ], "Condition": { "ArnLike": { "aws:SourceArn": "arn:aws:xray:us-east-1:123456789012:*" }, "StringEquals": { "aws:SourceAccount": "123456789012" } } } ] } ``` 1. Konfigurieren Sie das Ziel Ihrer Trace-Segmente mithilfe von [UpdateTraceSegmentDestination](https://docs.aws.amazon.com/xray/latest/api/API_UpdateTraceSegmentDestination.html). Führen Sie den folgenden Befehl aus, um die AWS CLI zu verwenden. ``` aws xray update-trace-segment-destination --destination CloudWatchLogs ``` 1. (Optional) Konfigurieren Sie den gewünschten Stichprobenprozentsatz mit [UpdateIndexingRule](https://docs.aws.amazon.com/xray/latest/api/API_UpdateIndexingRule.html). Führen Sie den folgenden Befehl aus, um die AWS CLI zu verwenden. ``` aws xray update-indexing-rule --name "Default" --rule '{"Probabilistic": {"DesiredSamplingPercentage": number}}' ``` ### Span-Ziel für Agenten, die in Amazon Bedrock AgentCore Runtime gehostet werden **Tipp** Sie können jetzt die gesamte Telemetrie eines Agenten — Spans, strukturierte Protokolle und Standardausgabe — in einer einzigen Protokollgruppe für jeden Agenten konsolidieren. Mit AgentCore Runtime, einer Funktion von Amazon Bedrock AgentCore, können Sie einen Agenten so konfigurieren, dass er seine Spans an dieselbe CloudWatch Amazon-Protokollgruppe übermittelt wie die Protokolle des Agenten. Bei dieser Konfiguration werden die Spans in den `spans` Log-Stream übertragen und nicht in `/aws/bedrock-agentcore/runtimes/-` die gemeinsam genutzte `aws/spans` Protokollgruppe. Sie können Spans, strukturierte Protokolle und Standardausgaben in einer Protokollgruppe für jeden Agenten zusammenfassen, die Zugriffskontrolle und Verschlüsselung auf einen einzelnen Agenten beschränken und Telemetrie von einem einzigen Standort aus exportieren. In unterstützten AWS Regionen verwenden neu erstellte Agenten die Protokollgruppe des Agenten als Standard-Span-Ziel. Agenten, die erstellt wurden, bevor eine Region das einheitliche Span-Ziel unterstützt, behalten die gemeinsame `aws/spans` Protokollgruppe als Standard bei. Sie können den Standard für einen einzelnen Agenten mit der `UNIFIED_TRACES_DESTINATION_ENABLED` Umgebungsvariablen in Ihrer Agenten-Laufzeit außer Kraft setzen: + Um einen vorhandenen Agenten zu aktivieren, der die gemeinsame `aws/spans` Protokollgruppe verwendet, legen Sie fest`UNIFIED_TRACES_DESTINATION_ENABLED=true`. AgentCore übermittelt dann die Spans des Agenten an seine eigene Protokollgruppe. + Um einen Agenten zu deaktivieren, der standardmäßig seine eigene Protokollgruppe verwendet, legen Sie fest`UNIFIED_TRACES_DESTINATION_ENABLED=false`. AgentCore übermittelt dann die Spans des Agenten an die gemeinsam genutzte `aws/spans` Protokollgruppe. Damit AgentCore die Spans an die Protokollgruppe des Agenten übermittelt werden können, muss Folgendes zutreffen: + Aktivieren Sie die CloudWatch Transaktionssuche in Ihrem Konto und senden Sie Trace-Segmente an Amazon CloudWatch Logs. Ohne Transaktionssuche AgentCore können keine Spans an die Protokollgruppe des Agenten übermittelt werden. Weitere Informationen finden Sie unter [ CloudWatch Transaktionssuche aktivieren](#observability-configure-builtin-cw). + Erteilen Sie die `logs:PutResourcePolicy` Aktion in der Protokollgruppe des Agenten der Ausführungsrolle des Agenten. AgentCore verwendet diese Berechtigung, um die Übermittlung von Spans an die Protokollgruppe zu ermöglichen AWS X-Ray . Weitere Informationen finden Sie unter [Ausführungsrolle für die Ausführung eines Agenten zur AgentCore Laufzeit](runtime-permissions.md#runtime-permissions-execution). + Der Agent verwendet ADOT Version 0.18.0 oder höher (). `aws-opentelemetry-distro>=0.18.0` Frühere Versionen ignorieren die Span-Zielkonfiguration und liefern Spans an die gemeinsam genutzte Protokollgruppe. `aws/spans` Durch das Ändern des Span-Ziels werden vorhandene Span-Daten nicht verschoben. Spans, die AgentCore bereits übermittelt wurden, verbleiben in ihrer ursprünglichen Protokollgruppe. ## Aktivierung der Beobachtbarkeit im Agentencode für Agenten AgentCore-hosted Zusätzlich zu den vom Service generierten Metriken können AgentCore Sie damit auch Span- und Trace-Daten sowie benutzerdefinierte Messwerte sammeln, die aus Ihrem Agentencode stammen. Wenn Sie Agenten-Frameworks wie [Strands](https://strandsagents.com/latest/) oder [CrewAI](https://www.crewai.com/) mit unterstützten Instrumentierungsbibliotheken von Drittanbietern verwenden, bietet das Framework selbst integrierte Unterstützung für die semantischen Konventionen von OTEL und GenAI und kann auch mit einem automatischen Instrumentierungspaket wie instrumentiert werden. [LangChain](https://www.langchain.com/agents)`opentelemetry-instrument-langchain` [Es ist auch möglich, semantische Konventionen von Generative AI, [Telemetrie](https://opentelemetry.io/docs/specs/semconv/gen-ai/) und Spannweiten zu senden, indem ein benutzerdefinierter Tracer definiert wird.](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-agent-spans/) AgentCore unterstützt die Verwendung der folgenden Instrumentierungsbibliotheken in Ihrem Agenten-Framework: + [OpenInference](https://github.com/Arize-ai/openinference) + [Openolmetrie](https://github.com/traceloop/openllmetry) + [OpenLit](https://github.com/openlit/openlit) + [Traceloop](https://www.traceloop.com/docs/introduction) Um diese Daten auf der generativen KI-Observabilitätsseite der CloudWatch Konsole und in Amazon anzuzeigen CloudWatch, müssen Sie Ihrem Agentencode das SDK AWS Distro for Open Telemetry (ADOT) hinzufügen. **Anmerkung** Mit AgentCore können Sie auch Metriken für Agenten anzeigen, die nicht in der Runtime laufen. AgentCore Zusätzliche Einrichtungsschritte sind erforderlich, um Telemetrieausgänge für AgentCore Nicht-Agenten zu konfigurieren. Weitere Informationen finden Sie in den Anweisungen [unter Observability für Agenten aktivieren, die außerhalb von gehostet AgentCore](#observability-configure-3p) werden. Gehen Sie wie folgt vor, um ADOT-Unterstützung hinzuzufügen und AgentCore Observability zu aktivieren. **Fügen Sie Ihrem Agenten Observability hinzu AgentCore ** 1. Stellen Sie sicher, dass Ihr Framework so konfiguriert ist, dass es Traces ausgibt. Im Strands-Framework muss das Tracer-Objekt beispielsweise so konfiguriert sein, dass Strands angewiesen wird, Open Telemetry (OTEL) -Protokolle (Open Telemetry) auszugeben. 1. Fügen Sie das ADOT SDK und boto3 zu den Abhängigkeiten Ihres Agenten hinzu. Für Python fügen Sie Ihrer `requirements.txt` Datei Folgendes hinzu: ``` aws-opentelemetry-distro>=0.10.0 boto3 ``` Alternativ können Sie die Abhängigkeiten direkt installieren: ``` pip install aws-opentelemetry-distro>=0.10.0 boto3 ``` 1. Führen Sie Ihren Agentencode mit dem Befehl OpenTelemetry auto-instrumentation aus: ``` opentelemetry-instrument python my_agent.py ``` Dieser automatische Instrumentierungsansatz fügt das SDK automatisch zum Python-Pfad hinzu. Möglicherweise verwenden Sie diesen Ansatz bereits als Teil Ihrer OpenTelemetry Standardimplementierung. Fügen Sie für eine containerisierte Umgebung (wie Docker) den folgenden Befehl hinzu: ``` CMD ["opentelemetry-instrument", "python", "main.py"] ``` Wenn Sie ADOT verwenden und die Sitzungs-ID korrekt weitergeben möchten, definieren Sie das `X-Amzn-Bedrock-AgentCore-Runtime-Session-Id` im Anforderungsheader. ADOT setzt dann die session\_id korrekt in den Downstream-Headern. Um eine Trace-ID zu propagieren, rufen Sie die Laufzeit mit dem Parametersatz auf. AgentCore `traceId=` Sie können Ihren Agenten auch mit zusätzlichen Headern aufrufen, um zusätzliche Observability-Optionen zu erhalten. Weitere Informationen finden Sie unter [Verbesserte AgentCore Laufzeitbeobachtbarkeit mit benutzerdefinierten Headern](#observability-configure-invoke). ## Aktivierung der Beobachtbarkeit für Agenten, die außerhalb von gehostet werden AgentCore Um Observability für Agenten zu aktivieren, die außerhalb der AgentCore Runtime gehostet werden, folgen Sie zunächst den Schritten in den vorherigen Abschnitten, um die CloudWatch Transaktionssuche zu aktivieren, und fügen Sie Ihrem Code das ADOT-SDK hinzu. Wenn Sie Ihren Agenten auf AWS Lambda hosten, verwenden Sie den [AWS Lambda-Layer für OpenTelemetry](https://aws-otel.github.io/docs/getting-started/lambda) auf der AWS Distro for -Website. OpenTelemetry Fügen Sie die Ebene zu Ihrer Funktion hinzu und setzen Sie dann die `AWS_LAMBDA_EXEC_WRAPPER` Umgebungsvariable auf. `/opt/otel-instrument` Die Ebene instrumentiert dann automatisch Ihre Funktion. Bei diesem Ansatz müssen Sie das `aws-opentelemetry-distro` Paket nicht hinzufügen oder den zuvor beschriebenen `opentelemetry-instrument` Befehl ausführen. **ADOT Collector wird für die Agentenbeobachtbarkeit nicht unterstützt** Der ADOT Collector wird für die Beobachtbarkeit durch Agenten nicht unterstützt. Um Telemetrie von einem außerhalb der AgentCore Laufzeit gehosteten Agenten zu senden, müssen Sie entweder das ADOT SDK oder den AWS Lambda Layer for verwenden. OpenTelemetry Für Agenten, die außerhalb der AgentCore Runtime ausgeführt werden, müssen Sie außerdem eine Agenten-Protokollgruppe erstellen, die Sie in Ihre Umgebungsvariablen aufnehmen. Konfigurieren Sie Ihre AWS Umgebungsvariablen und legen Sie dann Ihre Open Telemetrie-Umgebungsvariablen fest, wie im Folgenden gezeigt. AWS Umgebungsvariablen ``` AWS_ACCOUNT_ID= AWS_DEFAULT_REGION= AWS_REGION= AWS_ACCESS_KEY_ID= AWS_SECRET_ACCESS_KEY= ``` OTEL-Umgebungsvariablen ``` AGENT_OBSERVABILITY_ENABLED=true OTEL_PYTHON_DISTRO=aws_distro OTEL_PYTHON_CONFIGURATOR=aws_configurator # required for ADOT Python only OTEL_RESOURCE_ATTRIBUTES=service.name=,aws.log.group.names=/aws/bedrock-agentcore/runtimes/,cloud.resource_id= # endpoint is optional OTEL_EXPORTER_OTLP_LOGS_HEADERS=x-aws-log-group=/aws/bedrock-agentcore/runtimes/,x-aws-log-stream=runtime-logs,x-aws-metric-namespace=bedrock-agentcore OTEL_EXPORTER_OTLP_TRACES_HEADERS=x-aws-log-group=/aws/bedrock-agentcore/runtimes/,x-aws-log-stream=spans # (Optional) Directs spans to your log group instead of the aws/spans log group. Requires ADOT version 0.18.0 or later. OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf OTEL_TRACES_EXPORTER=otlp OTEL_AWS_APPLICATION_SIGNALS_ENABLED=false # AWS Lambda Layer for OpenTelemetry only: disables Application Signals OTEL_LOGS_EXPORTER=otlp # AWS Lambda Layer for OpenTelemetry only: exports logs over OTLP OTEL_METRICS_EXPORTER=awsemf # AWS Lambda Layer for OpenTelemetry only: exports metrics as CloudWatch EMF ``` ``Ersetzen Sie es durch den Namen Ihres Agenten und `` durch eine eindeutige Kennung für Ihren Agenten. **Anmerkung** Wenn Sie festlegen`OTEL_EXPORTER_OTLP_TRACES_HEADERS`, dass Spans an Ihre eigene Protokollgruppe gesendet werden, müssen Sie auch eine Amazon CloudWatch Logs-Ressourcenrichtlinie hinzufügen. Die Richtlinie muss es X-Ray (`xray.amazonaws.com`) ermöglichen, diese Protokollgruppe `logs:PutLogEvents` aufzurufen. Verwenden Sie dieselbe Richtlinie wie unter [ CloudWatch Transaktionssuche aktivieren](#observability-configure-builtin-cw), und geben Sie den ARN Ihrer Protokollgruppe ein`Resource`. Ohne diese Richtlinie X-Ray können keine Spans an Ihre Protokollgruppe übermittelt werden. **Anmerkung** (Optional) Für andere Agenten-Frameworks als Strands LangChain, und CrewAI: Möglicherweise müssen Sie ein zusätzliches SDK und Code hinzufügen, um semantische Generative AI-Konventionen, Telemetrie und Spans zu senden. AgentCore [Observability, eine Funktion von Amazon Bedrock AgentCore, unterstützt die Verwendung der folgenden Instrumentierungsbibliotheken in Ihrem Agenten-Framework: \* \* [Openllmetry \* [OpenInference](https://github.com/Arize-ai/openinference)\* Traceloop [OpenLit](https://github.com/openlit/openlit)](https://github.com/traceloop/openllmetry)](https://www.traceloop.com/docs/introduction) ### Unterstützung für Sitzungs-IDs Um die Sitzungs-ID weiterzugeben, müssen Sie den Aufruf mit der Sitzungs-ID im OTEL-Backage aufrufen: ``` from opentelemetry import baggage ctx = baggage.set_baggage("session.id", session_id) # Set the session.id in baggage attach(ctx) # Attach the context to make it active token ``` ## Aktivierung von Observability für AgentCore Laufzeit-, Speicher-, Gateway-, integrierte Tools und Identitätsressourcen Wenn Sie eine AgentCore Laufzeitressource (Agent) erstellen, erstellt AgentCore Runtime standardmäßig eine CloudWatch Protokollgruppe für die vom Dienst bereitgestellten Protokolle. Für Speicher-, Gateway- und integrierte Toolressourcen werden Protokollziele jedoch AgentCore nicht automatisch für Sie konfiguriert. Für Speicher- und Gatewayressourcen können Sie Protokollziele entweder in der Konsole oder mithilfe eines AWS SDK konfigurieren. Wenn Sie die Konsole verwenden, um ein CloudWatch Logs-Ziel zu konfigurieren, hat der Standard-Protokollgruppenname für Speicher- und Gateway-Ressourcen die Form`/aws/vendedlogs/bedrock-agentcore/{resource-type}/APPLICATION_LOGS/{resource-id}`, wobei entweder `memory` oder `{resource-type}` steht`gateway`. Für Speicher- und Gateway-Protokolle können Sie mithilfe der AgentCore Konsole auch Protokollziele in Amazon S3 S3-Protokollen oder Firehose-Stream-Protokollen konfigurieren. Weitere Informationen zum Speichern von Protokollen in Amazon S3 oder Firehose finden Sie unter [Hochladen, Herunterladen und Arbeiten mit Objekten in Amazon S3 und Erstellen eines Amazon](https://docs.aws.amazon.com/AmazonS3/latest/userguide/uploading-downloading-objects.html) [Data Firehose-Lieferdatenstroms](https://docs.aws.amazon.com/firehose/latest/dev/basic-create.html). Weitere Informationen zu den Protokolldaten, die von AgentCore Arbeitsspeicher- und Gateway-Ressourcen ausgegeben werden, finden Sie unter [Bereitgestellte Protokolldaten (Speicher) oder Bereitgestellte](observability-memory-metrics.md#memory_logs_summary) [Protokolldaten (](observability-gateway-metrics.md#observability-gateway-logs-provided)Gateway). Für integrierte Toolressourcen stellt der AgentCore Dienst standardmäßig keine Protokolle bereit, aber Sie können Ihre eigenen Protokolle anhand Ihres Codes ausgeben. Wenn Sie Ihre eigenen Protokollausgaben bereitstellen, müssen Sie die Protokollziele zum Speichern dieser Daten manuell konfigurieren. Informationen darüber, was Observability-Daten standardmäßig für jeden Ressourcentyp AgentCore bieten, finden Sie unter Von [Amazon Bedrock AgentCore generierte Observabilitätsdaten](observability-service-provided.md). ### Konfigurieren Sie Protokollziele mithilfe der Konsole Gehen Sie wie folgt vor, um Protokollziele für Speicher- oder Gateway-Protokolle in der AgentCore Konsole zu konfigurieren. **Example** 1. ====== So konfigurieren Sie die Protokollzustellung für Speicherressourcen (Konsole) 1. Öffnen Sie die [Speicherseite](https://console.aws.amazon.com/bedrock-agentcore/memory) in der AgentCore Konsole. 1. Wählen Sie im Bereich **Speicher** den Speicher aus, für den Sie ein Protokollziel konfigurieren möchten. 1. Scrollen Sie nach unten zum Bereich „**Protokollzustellung**“ und wählen Sie „**Hinzufügen**“. 1. Wählen Sie aus der Drop-down-Liste den Typ des Protokollziels aus, den Sie hinzufügen möchten (CloudWatch Logs-Gruppe, Amazon S3 S3-Bucket oder Amazon Data Firehose). 1. **Wählen Sie als **Protokolltyp APPLICATION\_LOGS** aus.** 1. Geben Sie für Amazon S3- und Firehose-Ziele einen **Lieferziel-ARN** ein. Für CloudWatch Protokolle ist die **Zielprotokollgruppe** bereits mit einem Standardwert gefüllt. 1. (Optional) Um die Standardprotokollgruppe für CloudWatch Protokollziele zu ändern, geben Sie einen neuen Protokollgruppennamen ein oder wählen Sie unter **Zielprotokollgruppe eine vorhandene Protokollgruppe** aus. 1. (Optional) Um die Felder, die in den einzelnen Protokolldatensätzen erfasst werden, oder das Ausgabeformat der Protokolle zu ändern, erweitern Sie **Zusätzliche Einstellungen — optional** und passen Sie die **Feldauswahl**, das **Ausgabeformat** und das **Feldtrennzeichen** an die gewünschte Konfiguration an. 1. Wählen Sie **Hinzufügen** aus. 1. ====== So konfigurieren Sie die Protokollzustellung für Gateway-Ressourcen (Konsole) 1. Öffnen Sie die [Gateways-Seite](https://console.aws.amazon.com/bedrock-agentcore/toolsAndGateways) in der AgentCore Konsole. 1. Wählen Sie im Bereich **Gateways** das Gateway aus, für das Sie ein Protokollziel konfigurieren möchten. 1. Scrollen Sie nach unten zum Bereich für die **Protokollzustellung** und wählen Sie **Hinzufügen** aus. 1. Wählen Sie aus der Drop-down-Liste den Typ des Protokollziels aus, den Sie hinzufügen möchten (CloudWatch Logs-Gruppe, Amazon S3 S3-Bucket oder Amazon Data Firehose). 1. Geben Sie für Amazon S3- und Firehose-Ziele einen **Lieferziel-ARN** ein. Für CloudWatch Protokolle ist die **Zielprotokollgruppe** bereits mit einem Standardwert gefüllt. 1. (Optional) Um die Standardprotokollgruppe für CloudWatch Protokollziele zu ändern, geben Sie einen neuen Protokollgruppennamen ein oder wählen Sie unter **Zielprotokollgruppe eine vorhandene Protokollgruppe** aus. 1. (Optional) Um die Felder, die in den einzelnen Protokolldatensätzen erfasst werden, oder das Ausgabeformat der Protokolle zu ändern, erweitern Sie **Zusätzliche Einstellungen — optional** und passen Sie die **Feldauswahl**, das **Ausgabeformat** und das **Feldtrennzeichen** an die gewünschte Konfiguration an. 1. Wählen Sie **Hinzufügen** aus. 1. ====== So konfigurieren Sie die Protokollzustellung für Agenten-Runtime-Ressourcen (Konsole) 1. Öffnen Sie die [Agent-Runtime-Seite](https://console.aws.amazon.com/bedrock-agentcore/agents) in der AgentCore Konsole. 1. Wählen Sie im Bereich **Runtime-Agents** den Runtime-Agenten aus, für den Sie ein Protokollziel konfigurieren möchten. 1. Scrollen Sie nach unten zum Bereich **Protokollzustellung** und wählen Sie aus der Drop-down-Liste **Hinzufügen** das **Logging-Ziel** aus — entweder Amazon CloudWatch Logs, Amazon S3 oder Amazon Data Firehose. 1. Konfigurieren Sie die folgenden Details zur Protokollzustellung und wählen Sie dann **Hinzufügen** aus: + Wählen Sie als **Protokolltyp** die Option **APPLICATION\_LOGS** aus. + Wenn Sie Amazon CloudWatch Logs als Protokollierungsziel verwenden, geben Sie die Zielprotokollgruppe an. + Wenn Sie Amazon S3 als Logging-Ziel verwenden, geben Sie den Amazon S3-Ziel-Bucket an. + Wenn Sie Amazon Data Firehose als Logging-Ziel verwenden, geben Sie einen Ziel-Lieferstream an. 1. Stellen Sie sicher, dass der Status der Protokollzustellung auf **Versand aktiv** gesetzt ist. 1. ====== Um die Protokollzustellung für Ressourcen mit integrierten Tools zu konfigurieren (Konsole) 1. Öffnen Sie die [Built-in Tools-Seite](https://console.aws.amazon.com/bedrock-agentcore/builtInTools) in der AgentCore Konsole. 1. Wählen Sie im **Built-in Toolbereich** entweder auf den **Codeinterpreter-Tools** oder auf der Registerkarte **Browser-Tools** das Codeinterpreter-Tool oder das Browser-Tool aus, für das Sie ein Protokollziel konfigurieren möchten. 1. Scrollen Sie nach unten zum Bereich **Protokollzustellung** und wählen Sie aus der Drop-down-Liste **Hinzufügen** das **Logging-Ziel** aus — entweder Amazon CloudWatch Logs, Amazon S3 oder Amazon Data Firehose. 1. Konfigurieren Sie die folgenden Details zur Protokollzustellung und wählen Sie dann **Hinzufügen** aus: + Wählen Sie als **Protokolltyp** die Option **APPLICATION\_LOGS** aus. + Wenn Sie Amazon CloudWatch Logs als Protokollierungsziel verwenden, geben Sie die Zielprotokollgruppe an. + Wenn Sie Amazon S3 als Logging-Ziel verwenden, geben Sie den Amazon S3-Ziel-Bucket an. + Wenn Sie Amazon Data Firehose als Logging-Ziel verwenden, geben Sie einen Ziel-Lieferstream an. 1. Stellen Sie sicher, dass der Status der Protokollzustellung auf **Versand aktiv** gesetzt ist. 1. WorkloadIdentity Die Aktivierung der Protokollzustellung erfolgt auf der zugehörigen Ressourcenebene, einschließlich der Agenten-Laufzeit- oder Agent-Gateway-Ressourcen. **So konfigurieren Sie die WorkloadIdentity Protokollzustellung für zugehörige Ressourcen (Konsole)** 1. Öffnen Sie in der AgentCore Konsole entweder die Seite [Gateway](https://console.aws.amazon.com/bedrock-agentcore/toolsAndGateways) oder [Agent Runtime](https://console.aws.amazon.com/bedrock-agentcore/agents) und wählen Sie einen Agenten oder ein Gateway aus, für den Sie die WorkloadIdentity Protokollierung aktivieren möchten. 1. Scrollen Sie auf der Registerkarte **Identität** nach unten zum Bereich **Protokollzustellung** und wählen Sie im Drop-down-Menü **Hinzufügen** das **Protokollierungsziel** aus — entweder Amazon CloudWatch Logs, Amazon S3 oder Amazon Data Firehose. 1. Konfigurieren Sie die folgenden Details zur Protokollzustellung und wählen Sie dann **Hinzufügen** aus: + Wählen Sie als **Protokolltyp** die Option **APPLICATION\_LOGS** aus. + Wenn Sie Amazon CloudWatch Logs als Protokollierungsziel verwenden, geben Sie die Zielprotokollgruppe an. + Wenn Sie Amazon S3 als Logging-Ziel verwenden, geben Sie den Amazon S3-Ziel-Bucket an. + Wenn Sie Amazon Data Firehose als Logging-Ziel verwenden, geben Sie einen Ziel-Lieferstream an. 1. Stellen Sie sicher, dass der Status der Protokollzustellung auf **Versand aktiv** gesetzt ist. ### Konfigurieren Sie die Zustellung mit Ablaufverfolgung für die CloudWatch Verwendung der Konsole In diesem Abschnitt wird beschrieben, wie Sie Trace Delivery aktivieren CloudWatch , um den Fluss der Interaktionen in Ihrer Anwendung nachzuverfolgen. Auf diese Weise können Sie Anfragen visualisieren, Leistungsengpässe identifizieren, Fehler beheben und die Leistung optimieren. **Example** 1. ====== So konfigurieren Sie die Ablaufverfolgung für Speicherressourcen (Konsole) 1. Öffnen Sie die [Speicherseite](https://console.aws.amazon.com/bedrock-agentcore/memory) in der AgentCore Konsole. 1. Wählen Sie im Bereich **Speicher** die Speicherressource aus, für die Sie die Ablaufverfolgung aktivieren möchten. 1. **Wählen Sie im Bereich „**Protokollierung**“ die Option „**Bearbeiten**“, schalten Sie das Widget auf „**Aktivieren**“ um und wählen Sie dann „Speichern“.** 1. ====== Um die Ablaufverfolgung für Laufzeitressourcen zu konfigurieren (Konsole) 1. Öffnen Sie die [Agenten-Runtime-Seite](https://console.aws.amazon.com/bedrock-agentcore/agents) in der AgentCore Konsole. 1. Wählen Sie im Bereich **Runtime-Agenten** den Agenten aus, für den Sie die Ablaufverfolgung aktivieren möchten. 1. **Wählen Sie im Bereich **Tracing** die Option **Bearbeiten** aus, schalten Sie das Widget auf **Aktivieren** um und wählen Sie dann Speichern.** AgentCore aktiviert die Ablaufverfolgung für den ausgewählten Agenten. Spans erscheinen in der Protokollgruppe des Agenten (`/aws/bedrock-agentcore/runtimes/-`) oder in der `aws/spans` Protokollgruppe für Agenten, die das gemeinsame Span-Ziel verwenden. Weitere Informationen finden Sie unter [Span-Ziel für Agenten, die in Amazon Bedrock AgentCore Runtime gehostet](#observability-configure-unified-traces) werden. **So konfigurieren Sie die WorkloadIdentity Ablaufverfolgung für Runtime-Ressourcen (Konsole)** 1. Öffnen Sie die [Agenten-Runtime-Seite](https://console.aws.amazon.com/bedrock-agentcore/agents) in der AgentCore Konsole. 1. Wählen Sie im Bereich **Runtime-Agenten** die Registerkarte **Identität** und dann den Agenten aus, für den Sie die WorkloadIdentity Ablaufverfolgung aktivieren möchten. 1. **Wählen Sie im Bereich „**Tracing**“ die Option „**Bearbeiten**“, schalten Sie das Widget auf „**Aktivieren**“ und wählen Sie dann „Speichern“.** WorkloadIdentity Die Ablaufverfolgung wird für den ausgewählten Agenten aktiviert und die Spans sind in der Protokollgruppe verfügbar. `aws/spans` 1. ====== Um die Ablaufverfolgung für integrierte Tools zu konfigurieren (Konsole) 1. Öffnen Sie die [Built-in Tools-Seite](https://console.aws.amazon.com/bedrock-agentcore/builtInTools) in der AgentCore Konsole. 1. Wählen Sie im **Built-in Toolbereich** entweder auf den **Codeinterpreter-Tools** oder auf der Registerkarte **Browser-Tools** das Codeinterpreter-Tool oder das Browser-Tool aus, für das Sie die Ablaufverfolgung aktivieren möchten. 1. **Wählen Sie im Bereich **Tracing** die Option **Bearbeiten** aus, schalten Sie das Widget auf **Aktivieren** um und wählen Sie dann Speichern aus.** Die Ablaufverfolgung wird für den ausgewählten Codeinterpreter oder das ausgewählte Browsertool aktiviert, und die Spans sind in der Protokollgruppe verfügbar. `aws/spans` 1. ====== Um die Ablaufverfolgung für Gateway-Ressourcen zu konfigurieren (Konsole) 1. Öffnen Sie die [Gateways-Seite](https://console.aws.amazon.com/bedrock-agentcore/toolsAndGateways) in der Konsole. AgentCore 1. Wählen Sie im Bereich **Gateways** das Gateway aus, für das Sie die Ablaufverfolgung aktivieren möchten. 1. **Wählen Sie im Bereich **Tracing** die Option **Bearbeiten** aus, schalten Sie das Widget auf **Aktivieren** um und wählen Sie dann Speichern.** Die Ablaufverfolgung wird für das ausgewählte Gateway aktiviert und die Spans sind in der Protokollgruppe verfügbar. `aws/spans` **So konfigurieren Sie die WorkloadIdentity Ablaufverfolgung für Gateway-Ressourcen (Konsole)** 1. Öffnen Sie die Seite [Gateways](https://console.aws.amazon.com/bedrock-agentcore/toolsAndGateways) in der AgentCore Konsole. 1. Wählen Sie im Bereich **Gateways** die Registerkarte **Identität** und dann das Gateway aus, für das Sie die Ablaufverfolgung aktivieren WorkloadIdentity möchten. 1. **Wählen Sie im Bereich **Tracing** die Option **Bearbeiten** aus, schalten Sie das Widget auf **Aktivieren** um und wählen Sie dann Speichern aus.** WorkloadIdentity Die Ablaufverfolgung wird für das ausgewählte Gateway aktiviert und die Spans sind in der Protokollgruppe verfügbar. `aws/spans` **Anmerkung** Sie müssen die [CloudWatch Transaktionssuche](#observability-configure-builtin-cw) aktiviert haben, bevor Sie die Ablaufverfolgung aktivieren können. 1. ====== Um die Ablaufverfolgung für Identitätsressourcen zu konfigurieren (Konsole) 1. Öffnen Sie die [Identitätsseite](https://console.aws.amazon.com/bedrock-agentcore/identity) in der AgentCore Konsole. 1. Wählen Sie im Bereich **Identität** den OAuth-Client oder den API-Schlüssel aus, für den Sie die Ablaufverfolgung aktivieren möchten. 1. **Wählen Sie im Bereich **Tracing** die Option **Bearbeiten** aus, schalten Sie das Widget auf **Aktivieren** um und wählen Sie dann Speichern.** ### Konfigurieren Sie CloudWatch Ressourcen mithilfe eines AWS SDK **So konfigurieren Sie eine Zustellungsquelle für Logs and Traces (SDK)** + Führen Sie den folgenden Python-Code aus, CloudWatch um Ihre Speicher-, Gateway- und integrierten Toolressourcen zu konfigurieren. Beachten Sie, dass Zustellungsquellen und -ziele für die Ablaufverfolgung nur für Speicher- und Gateway-Ressourcen gelten. ``` import boto3 def enable_observability_for_resource(resource_arn, resource_id, account_id, region='us-east-1'): """ Enable observability for a Bedrock AgentCore resource (e.g., Memory Store) """ logs_client = boto3.client('logs', region_name=region) # Step 0: Create new log group for vended log delivery log_group_name = f'/aws/vendedlogs/bedrock-agentcore/{resource_id}' logs_client.create_log_group(logGroupName=log_group_name) log_group_arn = f'arn:aws:logs:{region}:{account_id}:log-group:{log_group_name}' # Step 1: Create delivery source for logs logs_source_response = logs_client.put_delivery_source( name=f"{resource_id}-logs-source", logType="APPLICATION_LOGS", resourceArn=resource_arn ) # Step 2: Create delivery source for traces traces_source_response = logs_client.put_delivery_source( name=f"{resource_id}-traces-source", logType="TRACES", resourceArn=resource_arn ) # Step 3: Create delivery destinations logs_destination_response = logs_client.put_delivery_destination( name=f"{resource_id}-logs-destination", deliveryDestinationType='CWL', deliveryDestinationConfiguration={ 'destinationResourceArn': log_group_arn, } ) # Traces required traces_destination_response = logs_client.put_delivery_destination( name=f"{resource_id}-traces-destination", deliveryDestinationType='XRAY' ) # Step 4: Create deliveries (connect sources to destinations) logs_delivery = logs_client.create_delivery( deliverySourceName=logs_source_response['deliverySource']['name'], deliveryDestinationArn=logs_destination_response['deliveryDestination']['arn'] ) # Traces required traces_delivery = logs_client.create_delivery( deliverySourceName=traces_source_response['deliverySource']['name'], deliveryDestinationArn=traces_destination_response['deliveryDestination']['arn'] ) print(f"Observability enabled for {resource_id}") return { 'logs_delivery_id': logs_delivery['id'], 'traces_delivery_id': traces_delivery['id'] } # Usage example resource_arn = "arn:aws:bedrock-agentcore:us-east-1:123456789012:memory/my-memory-id" resource_id = "my-memory-id" account_id = "123456789012" delivery_ids = enable_observability_for_resource(resource_arn, resource_id, account_id) ``` ## Verbesserte AgentCore Laufzeitbeobachtbarkeit mit benutzerdefinierten Headern Sie können Ihren Agenten mit zusätzlichen HTTP-Headern aufrufen, um erweiterte Observability-Optionen bereitzustellen. Das folgende Beispiel zeigt Aufrufe, einschließlich optionaler zusätzlicher Header-Anfragen für Agenten, die in der Runtime gehostet werden. AgentCore **Beispiel für einen Boto3-Aufruf** ``` def invoke_agent(agent_id, payload, session_id=None): client = boto3.client("bedrock-agentcore", region="us-west-2") response = client.invoke_agent_runtime( agentRuntimeArn="arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/test_agent_boto2-nIg2xk3VSR", runtimeSessionId="12345678-1234-5678-9abc-123456789012", payload='{"query": "Plan a weekend in Seattle"}', ) ``` Sie können die folgenden optionalen Header hinzufügen, wenn Sie Ihren Agenten aufrufen, um die Beobachtbarkeit und die Nachverfolgungsfunktionen zu verbessern: | Header | Description | Beispielwert | Technische Erklärung | | --- | --- | --- | --- | | X-Amzn-Trace-Id | Trace-ID für die Nachverfolgung von Anfragen (X-Ray Format) | root=1-5759E988-BD862E3FE1BE46A994272793; Eltern=53995C3F42CD8AD8; Sampled=1 | Wird für die verteilte Ablaufverfolgung über mehrere Dienste hinweg verwendet. AWS Enthält die Root-ID (Herkunft der Anfrage), die übergeordnete ID (vorheriger Dienst) und die Stichprobenentscheidung für die Ablaufverfolgung. Stichproben=1 bedeutet 100% ige Probenahme. Parent ist ebenfalls das X-Ray Trace-Format. OTEL generiert automatisch Trace-IDs, wenn sie nicht angegeben werden. | | TraceParent | W3C-Standard-Tracing-Header | 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01 | W3C-Format, das Version, Trace-ID, übergeordnete ID und Flags enthält. Erforderlich für die dienstübergreifende Trace-Korrelation bei Verwendung moderner Ablaufverfolgungssysteme. | | X-Amzn-Bedrock-AgentCore-Runtime-Session-Id | AgentCore Sitzungs-ID | A1B2C3D4-5678-90AB-CDEF-Beispiel AAAAA | Identifiziert eine Benutzersitzung innerhalb des Systems. AgentCore Hilft bei sitzungsbasierten Analysen und Problembehebungen. | | mcp-session-id | MCP-Sitzungskennung | MCP-A1B2C3D4-5678-90AB-CDEF-Beispiel AAAAA | Identifiziert eine Sitzung auf der Managed Cloud Platform. Ermöglicht die Rückverfolgung von Vorgängen im gesamten MCP-Ökosystem. | | trace/state | Zusätzliche Informationen zum Status der Ablaufverfolgung | congo=t61rc E, rojo=00f067aa0ba902b7 WkgMz | Vendor-specific Informationen nachverfolgen. Vermittelt zusätzlichen Kontext für Rückverfolgungssysteme, der über den Inhalt von traceparent hinausgeht. | | Gepäck | Weitergabe des Kontextes für verteiltes Tracing | userID=Alice, Serverregion=US-Ost-1 | Key-value Paare, die benutzerdefinierte Eigenschaften für die kontextbezogene Protokollierung und Analyse über Dienstgrenzen hinweg weitergeben. | ## Verbesserte Beobachtbarkeit der AgentCore integrierten Tools mit benutzerdefinierten Headern Sie können Ihre Built-in Tools mit zusätzlichen HTTP-Headern aufrufen, um erweiterte Observability-Optionen bereitzustellen. Sie können die folgenden optionalen Header hinzufügen, wenn Sie die folgenden Build-in Tools-APIs integrieren, um die Beobachtbarkeit und die Tracing-Funktionen zu verbessern: Die folgenden APIs unterstützen benutzerdefinierte Header: + StartCodeInterpreterSession + InvokeCodeInterpreter + StopCodeInterpreterSession + StartBrowserSession + StopBrowserSession | Header | Description | Beispielwert | Technische Erklärung | | --- | --- | --- | --- | | X-Amzn-Trace-Id | Trace-ID für die Nachverfolgung von Anfragen (X-Ray Format) | root=1-5759E988-BD862E3FE1BE46A994272793; Eltern=53995C3F42CD8AD8; Sampled=1 | Wird für die verteilte Ablaufverfolgung über mehrere Dienste hinweg verwendet. AWS Enthält die Root-ID (Herkunft der Anfrage), die übergeordnete ID (vorheriger Dienst) und die Stichprobenentscheidung für die Ablaufverfolgung. Stichproben=1 bedeutet 100% ige Probenahme. Parent ist ebenfalls das X-Ray Trace-Format. OTEL generiert automatisch Trace-IDs, wenn sie nicht angegeben werden. | | TraceParent | W3C-Standard-Tracing-Header | 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01 | W3C-Format, das Version, Trace-ID, übergeordnete ID und Flags enthält. Erforderlich für die dienstübergreifende Trace-Korrelation bei Verwendung moderner Ablaufverfolgungssysteme. | ## Verbesserte AgentCore Identitätserkennbarkeit mit benutzerdefinierten Headern Sie können Ihre Identitätsressourcen mit zusätzlichen HTTP-Headern aufrufen, um erweiterte Observability-Optionen bereitzustellen. Sie können bei der Integration der folgenden Identitäts-APIs die folgenden optionalen Header einbeziehen, um die Beobachtbarkeit und die Nachverfolgungsfunktionen zu verbessern: Die folgenden APIs unterstützen benutzerdefinierte Header: + GetWorkloadAccessToken + GetWorkloadAccessTokenForJWT + GetWorkloadAccessTokenForUserId + GetResourceOauth2Token + GetResourceAPIKey | Header | Description | Beispielwert | Technische Erklärung | | --- | --- | --- | --- | | X-Amzn-Trace-Id | Trace-ID für die Nachverfolgung von Anfragen (X-Ray Format) | root=1-5759E988-BD862E3FE1BE46A994272793; Eltern=53995C3F42CD8AD8; Sampled=1 | Wird für die verteilte Ablaufverfolgung über mehrere Dienste hinweg verwendet. AWS Enthält die Root-ID (Herkunft der Anfrage), die übergeordnete ID (vorheriger Dienst) und die Stichprobenentscheidung für die Ablaufverfolgung. Stichproben=1 bedeutet 100% ige Probenahme. Parent ist ebenfalls das X-Ray Trace-Format. OTEL generiert automatisch Trace-IDs, wenn sie nicht angegeben werden. | ## Bewährte Verfahren zur Beobachtbarkeit Beachten Sie die folgenden bewährten Methoden bei der Implementierung von Observability für Agenten in: AgentCore + Verwenden Sie konsistente Sitzungs-IDs — Verwenden Sie nach Möglichkeit dieselbe Sitzungs-ID für verwandte Anfragen, um den Kontext zwischen den Interaktionen aufrechtzuerhalten. + Implementieren Sie verteiltes Tracing — Verwenden Sie die bereitgestellten Header, um eine durchgängige Ablaufverfolgung für Ihre Anwendungskomponenten zu ermöglichen. + Fügen Sie benutzerdefinierte Attribute hinzu — Erweitern Sie Ihre Traces und Metriken mit benutzerdefinierten Attributen, die zusätzlichen Kontext für die Fehlerbehebung und Analyse bieten. + Überwachen Sie die Ressourcennutzung — Achten Sie auf die Kennzahlen zur Speichernutzung, um die Leistung Ihres Agenten zu optimieren. + Benachrichtigungen einrichten — Konfigurieren Sie CloudWatch Alarme, um Sie über potenzielle Probleme zu informieren, bevor sie sich auf Ihre Benutzer auswirken. ## Verwendung anderer Observability-Plattformen Um in der AgentCore Runtime gehostete Agenten in andere Observability-Plattformen zu integrieren, um Telemetrieausgaben zu erfassen und anzuzeigen, legen Sie die folgende Umgebungsvariable fest: ``` DISABLE_ADOT_OBSERVABILITY=true ``` Wenn Sie diese Variable auf setzen, `true` werden die standardmäßigen ADOT-Umgebungsvariablen der AgentCore Laufzeit deaktiviert, sodass sichergestellt ist, dass keine der ADOT-Standardkonfigurationen festgelegt ist.