aws-samples / aws-samples/sample-autonomous-cloud-coding-agents
chore(agent): expose or remove the _debug_cw_failures counter — incremented, never read
- Ngôn ngữ chính
- TypeScript
- Star
- 143
- Fork
- 46
- Merge trung bình
- 3 ngày 10 giờ
- Pull request đã merge (30 ngày)
- 24
Mô tả
## Problem
`agent/src/server.py` maintains a module-global `_debug_cw_failures` counter, incremented under a lock on every failed CloudWatch write (`:197`, `:226`). Nothing ever reads it.
Three docstrings describe it as an operator-facing signal — `:145` and `:176` call it *"a single alarm surface"* — but there is no metric emission, no CloudWatch alarm, and no `/ping` or `/validate` exposure. The value dies with the process.
## Why it matters
The counter exists to answer "is the debug/diagnostic path blind?" — i.e. is the agent failing to write the very lines an operator would use to diagnose a task. That is a genuinely useful signal on a substrate where the guest is otherwise unobservable, and it is currently unobtainable. Worse, the docstrings promise it, so a reader debugging a silent task may go looking for an alarm that does not exist.
Surfaced during the ADR-021 P2 review (PR #733, non-blocking item 6). Pre-existing, not introduced by that PR. Note that #733 removed the one place that *depended* on the counter rhetorically: `_build_hook_log`'s reason #1 previously argued a build-role write would "poison the signal", and now argues from IAM namespace scoping instead. So there is no longer anything blocking a decision either way.
## Options
1. **Expose it** (smallest useful change): include it in the `/ping` and/or `/validate` response body. `/validate` already has a `warnings` array and, as of #733, logs named warnings to the build log group — the same shape would work here.
2. **Emit it as a metric** (most useful): an EMF line or a `PutMetricData` call at task finalize, which gives operators something alarmable. Note the ordering constraint: the emitter must not itself be a CloudWatch write on the path it is measuring, and it must respect the pre-`platform_config` AWS-silence rule (see `_aws_silent_log`).
3. **Remove it** and correct the three docstrings. Legitimate if nobody wants the signal — the failures are already logged individually to stdout.
## Acceptance criteria
- `_debug_cw_failures` is either read by something an operator can observe, or removed.
- The docstrings at `server.py:145` and `:176` describe what actually exists.
- If exposed: a test asserts a non-zero counter is visible after a forced write failure, and that the exposure path does not itself perform a CloudWatch write.
- If removed: no docstring anywhere references an alarm surface.
Hướng dẫn đóng góp
Hướng nghiên cứu
Bắt đầu trong agent/src/server.py, xung quanh các lần tăng _debug_cw_failures ở dòng 197 và 226, sau đó kiểm tra các phản hồi /ping và /validate cũng như quy tắc sắp xếp của _aws_silent_log. Quyết định xem bộ đếm nên được hiển thị, phát ra hay loại bỏ, đồng thời xác minh đường dẫn lỗi liên quan và các docstring. Hoàn tất khi hành vi của bộ đếm khớp với tùy chọn đã chọn và không có tài liệu nào hứa hẹn một bề mặt cảnh báo không khả dụng.
Do mô hình lập chỉ mục viết ra từ nội dung của issue.
Đánh giá
- Công nghệ
- aws, python
- Lĩnh vực
- backend, cloud, observability
- Loại issue
- Tái cấu trúc
- Độ khó
- 5/5
- Thời gian dự kiến
- Hơn một tuần
- Mức độ hoạt động
- Sôi nổi
- Độ rõ ràng
- Khá rõ ràng
- Mức phù hợp với người mới
- 45/100