docs(request-trace-uploader): document deployment and operations
Open
Nobody has claimed this yet.
- Dominant language
- Go
- Stars
- 218
- Forks
- 72
- Avg merge
- 1d 12h
- Merged PRs (30d)
- 427
Description
Why
The request-trace-uploader needs a clear deployment and operational contract before users deploy it.
Scope
- Document the minimum Dynamo version as v1.4.0 and why: v1.3.x emits a separate
AuditRecordtype the uploader does not parse. - Document the required Dynamo producer settings, and that the uploader cannot verify them because it cannot observe Dynamo's environment. Specifically:
DYN_REQUEST_TRACE_RECORDSmust includerequest_payloadfor payload capture;DYN_REQUEST_TRACE_HTTP_HEADER_CAPTURE_LISTmust include every header a suppression rule depends on, because Dynamo never reads a header absent from that allowlist; and deprecatedDYN_AUDIT_*variables must not be set, becauseDYN_AUDIT_FORCE_LOGGINGsilently enables payload capture for every request. - Document the single-file-family contract on v1.4.0 and that record classification comes from
event_type, not filenames. - Document the sidecar image, shared spool, read-only credential mount, state and quarantine directories, health probes, and configuration settings.
- Document both backends: the generic S3-compatible object store, and Kratos Bulk Upload including its build tag, environment vocabulary, and asynchronous terminal-status model.
- Document the uploader's own OTLP logs, traces, and metrics through BYOO signal-specific endpoints. Do not describe a Prometheus scrape path.
- Document source lifecycle, fault scoping, retry and failure behavior, quarantine bounds and eviction, suppression behavior, redaction, and safe credential rotation.
- Add operator guidance for backlog, oldest pending age, retries, terminal failures, quarantine growth and eviction, circuit-breaker trips, suppression coverage, stale success, configuration, and credential alerts.
- Document how to tell a broken header allowlist from ordinary no-match traffic using the suppression counters, since the uploader reports rather than adjudicates.
Tests
- Validate all configuration names, defaults, and behavior examples against the implementation.
- Render deployment examples and verify no secret values or request payloads appear.
Parent: #1004
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the request-trace-uploader implementation and its deployment and configuration examples, then compare every documented setting and default with the implementation. Validate deployment rendering and check that examples contain no secrets or request payloads. Done means the deployment, operations, lifecycle, backend, telemetry, suppression, failure, quarantine, and alert guidance is complete and verified.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go, kubernetes
- Domain
- devops, documentation, observability
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100