registrystack / registrystack/registry-stack
Add a safe OpenTelemetry integration profile for product operations
- Dominant language
- Rust
- Stars
- 2
- Forks
- 0
- Avg merge
- 2h 55m
- Merged PRs (30d)
- 130
Description
## Outcome
Registry Relay and Registry Notary can participate in an institution-operated OpenTelemetry pipeline for correlation and performance diagnosis without making an external collector part of product correctness or exposing secrets, subject data, private configuration, or high-cardinality values.
Roadmap default: 1.2. Reprioritize only when a release-scoped deployment requirement mandates OpenTelemetry or end-to-end trace correlation.
## Scope
- Define server-side W3C Trace Context extraction, validation, propagation, and replacement rules.
- Retain a product-generated request identifier as the authoritative product audit handle.
- Propagate a bounded correlation context from Notary to Relay without accepting caller-controlled identity or authorization.
- Provide optional OTLP export for reviewed spans and resource attributes, or document a collector-based log/metric bridge where native export is unnecessary.
- Define stable span names, bounded route templates, outcome classes, dependency classes, and safe attributes.
- Keep chained audit records separate from traces, logs, and metrics.
- Treat collector unavailability as observability degradation, not permission to lose correctness state or block unrelated traffic unless a documented evidence-grade profile explicitly requires otherwise.
## Security requirements
Never export:
- credentials, tokens, keys, request or response bodies;
- source rows, claim values, subject identifiers, or offline-guessable derived values;
- raw URLs, query strings, filesystem paths, secret names, private provider labels, or unbounded error text;
- high-cardinality country, caller, route-parameter, database, or configuration values; or
- raw audit records.
Untrusted baggage and malformed trace context must be dropped or bounded before propagation.
## Definition of Done
- [ ] A public telemetry schema defines every span, attribute, cardinality bound, sensitivity class, and compatibility promise.
- [ ] Relay and Notary validate and propagate approved trace context while retaining independent server-owned request IDs.
- [ ] Synthetic end-to-end tests correlate a Notary operation with its Relay consultation through an institution-operated test collector.
- [ ] Malformed, oversized, repeated, conflicting, and attacker-controlled context cannot influence authorization, audit identity, routing, policy, or generated evidence.
- [ ] Adversarial leakage tests cover headers, URLs, errors, source values, claim values, configuration, and secret material.
- [ ] Collector timeout, backpressure, outage, and restart behavior are bounded and tested.
- [ ] Documentation covers enablement, sampling, redaction, collector ownership, troubleshooting, and the distinction between telemetry and audit evidence.
- [ ] The base deployment remains fully supported with OpenTelemetry disabled.
## Non-goals
- Shipping or operating an OpenTelemetry Collector or observability backend.
- Making distributed tracing a 1.0 correctness dependency.
- Replacing Prometheus metrics, product logs, or chained audit.
- Trusting an external trace identifier as product authentication or authorization evidence.
## Related work
- #315
- #500
Contributor guide
Research direction
Start by reading related issues #315 and #500, then map the Relay and Notary request paths and their existing audit, logging, and metrics boundaries. Use the Definition of Done to scope the public telemetry schema, validation and propagation tests, leakage tests, and collector failure behavior; completion requires all listed security, compatibility, and disabled-by-default requirements.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- backend-api-design, distributed-systems, observability-sre, security
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100