Logging Design Gate

logging-design-gate

Role

Support task-agent and review-agent for bounded logging decisions.

• Task mode (task-agent): Apply the accepted logging purpose, placement, and schema.
• Review mode (review-agent): Judge logging against purpose, safety, and signal criteria.

When To Use

• logging schema or redaction change
• diagnostic gap

Do Not Use

• no logging impact
• self review request

Required Inputs

• acceptance
• logging decision
• Task mode (task-agent): event boundary, logger policy, sensitive-field classification, and signal checks.
• Review mode (review-agent): changed event paths with safe-logging evidence.

Professional Decision Rules

• Log only for a named diagnostic, audit, security, or operational question; prefer another signal or no new signal when it answers better.
• Place one event at the boundary owning the outcome; do not duplicate intermediate retries, wrappers, and terminal failures.
• Select level and stable schema from current logger policy, event meaning, and reachable failure states.
• Allow only purpose-required fields; omit or transform secrets, credentials, sensitive payloads, and unnecessary personal data under current policy.
• Preserve only the correlation needed across affected request, trace, message, or job boundaries without exposing raw identity.
• Bound material rate, value-space, retention, access, sink, cost, cardinality, and audit risk with measured/platform evidence and an owner.

High-Value Gotchas

• Raw payload logging creates a durable privacy incident.
• Intermediate retry errors can create false incidents before the terminal outcome is known.
• High-cardinality fields, hot-path events, or an error without useful context can make the signal unusable.

Execution Checklist

1. Trace the named operational question to one owning event boundary and consumer action.
2. Choose level, schema, fields, redaction, correlation, and sink from current policy.
3. Verify failure visibility, duplicate emission, cardinality, rate, retention, and sensitive-data behavior.
4. Task mode: apply the logging decision at the owning event boundary.
5. Review mode: judge every changed event path against safe-logging criteria.
6. Stop when event purpose, owner, or data classification is unproven.

Stop / Escalation Conditions

• Stop without a named question, event owner, and placement; operational logs need an action, while audit evidence needs a consumer and protected meaning.
• Stop when fields, correlation, retention, access, or sinks can expose classified data without policy-consistent transformation and negative proof.
• Stop volume/cardinality risk without bounded rate or value-space evidence and an owned control or no-log outcome.
• Stop sensitive evidence actions without permission, sandbox, redaction, bounded scope, and rollback or cleanup.

Output Contract

• Task mode (task-agent): logging changes; placement and redaction evidence; signal risk.
• Review mode (review-agent): logging verdict; unsafe event findings; unproven signal behavior.

Targeted References