aws / aws/bedrock-agentcore-sdk-python
feat: Observability Client — Delivery, Query & Trace Analysis
- 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
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