aws / aws/bedrock-agentcore-sdk-python

feat: Observability Client — Delivery, Query & Trace Analysis

Offen
#395 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
enhancement
Vorherrschende Sprache
Python
Sterne
761
Forks
147
Ø Merge
1 T. 23 Std.
Gemergte PRs (30 T.)
7

Beschreibung

## Problem

The SDK has no observability surface area. On the delivery side, memory and gateway resources require manual CloudWatch vended log delivery setup — customers must call `PutDeliverySource`, `PutDeliveryDestination`, and `CreateDelivery` with the correct naming conventions, ARN formats, and source types. On the query side, the SDK's `CloudWatchSpanHelper` is internal to the evaluation module and not exposed as public API — customers who programmatically query traces for debugging, monitoring, or custom dashboards have no SDK path. The starter toolkit provides both: an `ObservabilityDeliveryManager` for enabling/disabling logs and traces per resource, and an `ObservabilityClient` with a full query→parse→analyze pipeline for spans and traces.

## Acceptance Criteria

- [ ] Customers can enable CloudWatch logs and traces for memory and gateway resources with a single method call
- [ ] Customers can enable traces for runtime resources
- [ ] Customers can disable observability and optionally clean up log groups
- [ ] Customers can check observability status (whether delivery sources exist) for a resource
- [ ] Customers can query spans by session ID or trace ID from CloudWatch Logs Insights
- [ ] Customers can query runtime logs by trace ID(s) from agent-specific log groups
- [ ] Customers can find the most recent session ID for an agent
- [ ] Query results are parsed into typed `Span` and `RuntimeLog` objects
- [ ] Customers can reconstruct trace trees (parent-child span hierarchy) from query results
- [ ] Customers can compute trace duration, count error spans, and filter to error-only traces
- [ ] All functionality is verified via integration tests running in CI

## Relevant Links

- [`ObservabilityDeliveryManager`](https://github.com/aws/bedrock-agentcore-starter-toolkit/blob/4b9387f0d48cb6639633437b669fc6cc09ef07be/src/bedrock_agentcore_starter_toolkit/operations/observability/delivery.py#L30)
- [`enable_observability_for_resource()`](https://github.com/aws/bedrock-agentcore-starter-toolkit/blob/4b9387f0d48cb6639633437b669fc6cc09ef07be/src/bedrock_agentcore_starter_toolkit/operations/observability/delivery.py#L101)
- [`enable_for_memory()`](https://github.com/aws/bedrock-agentcore-starter-toolkit/blob/4b9387f0d48cb6639633437b669fc6cc09ef07be/src/bedrock_agentcore_starter_toolkit/operations/observability/delivery.py#L531)
- [`enable_for_gateway()`](https://github.com/aws/bedrock-agentcore-starter-toolkit/blob/4b9387f0d48cb6639633437b669fc6cc09ef07be/src/bedrock_agentcore_starter_toolkit/operations/observability/delivery.py#L553)
- [`enable_traces_for_runtime()`](https://github.com/aws/bedrock-agentcore-starter-toolkit/blob/4b9387f0d48cb6639633437b669fc6cc09ef07be/src/bedrock_agentcore_starter_toolkit/operations/observability/delivery.py#L241)
- [`disable_observability_for_resource()`](https://github.com/aws/bedrock-agentcore-starter-toolkit/blob/4b9387f0d48cb6639633437b669fc6cc09ef07be/src/bedrock_agentcore_starter_toolkit/operations/observability/delivery.py#L426)
- [`get_observability_status()`](https://github.com/aws/bedrock-agentcore-starter-toolkit/blob/4b9387f0d48cb6639633437b669fc6cc09ef07be/src/bedrock_agentcore_starter_toolkit/operations/observability/delivery.py#L493)
- [`ObservabilityClient`](https://github.com/aws/bedrock-agentcore-starter-toolkit/blob/4b9387f0d48cb6639633437b669fc6cc09ef07be/src/bedrock_agentcore_starter_toolkit/operations/observability/client.py#L14)
- [`query_spans_by_session()`](https://github.com/aws/bedrock-agentcore-starter-toolkit/blob/4b9387f0d48cb6639633437b669fc6cc09ef07be/src/bedrock_agentcore_starter_toolkit/operations/observability/client.py#L44)
- [`query_spans_by_trace()`](https://github.com/aws/bedrock-agentcore-starter-toolkit/blob/4b9387f0d48cb6639633437b669fc6cc09ef07be/src/bedrock_agentcore_starter_toolkit/operations/observability/client.py#L79)
- [`query_runtime_logs_by_traces()`](https://github.com/aws/bedrock-agentcore-starter-toolkit/blob/4b9387f0d48cb6639633437b669fc6cc09ef07be/src/bedrock_agentcore_starter_toolkit/operations/observability/client.py#L114)
- [`TraceProcessor`](https://github.com/aws/bedrock-agentcore-starter-toolkit/blob/4b9387f0d48cb6639633437b669fc6cc09ef07be/src/bedrock_agentcore_starter_toolkit/operations/observability/trace_processor.py#L12)
- [`build_span_hierarchy()`](https://github.com/aws/bedrock-agentcore-starter-toolkit/blob/4b9387f0d48cb6639633437b669fc6cc09ef07be/src/bedrock_agentcore_starter_toolkit/operations/observability/trace_processor.py#L32)
- [`CloudWatchQueryBuilder`](https://github.com/aws/bedrock-agentcore-starter-toolkit/blob/4b9387f0d48cb6639633437b669fc6cc09ef07be/src/bedrock_agentcore_starter_toolkit/operations/observability/query_builder.py#L4)
- [`CloudWatchResultBuilder`](https://github.com/aws/bedrock-agentcore-starter-toolkit/blob/4b9387f0d48cb6639633437b669fc6cc09ef07be/src/bedrock_agentcore_starter_toolkit/operations/observability/builders.py#L9)

Beitragsleitfaden

Beitragsleitfaden öffnen

Rechercherichtung

Beginnen Sie mit den referenzierten Implementierungen von delivery.py, client.py, trace_processor.py, query_builder.py und builders.py und vergleichen Sie anschließend deren APIs mit der bestehenden Struktur des SDK für Evaluationen und Integrationstests. Führen Sie die relevanten Integrationstests in CI aus und überprüfen Sie die aufgeführten Akzeptanzkriterien für delivery, query, parsing, trace-reconstruction, duration und error-analysis.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
aws, python
Bereich
cloud, observability-sre
Issue-Typ
Feature
Schwierigkeit
5/5
Geschätzter Aufwand
Über eine Woche
Aktivitätsstatus
Ruhig
Klarheit
Größtenteils klar
Anfängerfreundlichkeit
35/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.