aws-samples / aws-samples/sample-autonomous-cloud-coding-agents

chore(agent): expose or remove the _debug_cw_failures counter — incremented, never read

Ouverte
#810 0 commentaires 0 réactions 0 personnes assignées Voir sur GitHub
Langage dominant
TypeScript
Étoiles
143
Forks
46
Merge moyen
3 j 10 h
PR mergées (30 j)
24

Description

## 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.

Guide de contribution

Ouvrir le guide de contribution

Piste de recherche

Commencez dans agent/src/server.py autour des incréments de _debug_cw_failures aux lignes 197 et 226, puis examinez les réponses /ping et /validate ainsi que la règle d’ordre de _aws_silent_log. Décidez si le compteur doit être exposé, émis ou supprimé, et vérifiez le chemin d’échec concerné ainsi que les docstrings. C’est terminé lorsque le comportement du compteur correspond à l’option choisie et qu’aucune documentation ne promet une surface d’alarme indisponible.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Évaluation

Stack technique
aws, python
Domaine
backend, cloud, observability
Type d'issue
Refactorisation
Difficulté
5/5
Temps estimé
Plus d'une semaine
Activité
Active
Clarté
Plutôt claire
Accessibilité débutants
45/100

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.