finos / finos/architecture-as-code
Add OpenTelemetry observability (traces, metrics, structured logs) in Calm Hub
- Dominant language
- TypeScript
- Stars
- 399
- Forks
- 138
- Avg merge
- 2d 14h
- Merged PRs (30d)
- 37
Description
## Feature Proposal
Add production-grade observability to calm-hub using OpenTelemetry auto-instrumentation via the Quarkus OTEL extension. This provides distributed traces, metrics, and structured JSON logging from a single,
unified setup — with zero code needed for the common path.
**Motivation**
calm-hub currently has no metrics, no distributed tracing, and only basic console logging. As we add the GitHub storage backend and scale deployments (HPA, multi-pod), operators need:
- Traces — end-to-end request visibility across HTTP → store → GitHub API calls
- Metrics — sync health, API latency percentiles, cache hit rates, session operations
- Structured logs — JSON format with trace correlation (traceId/spanId in every log line) for log aggregation (ELK, Grafana Loki, CloudWatch)
Design Principles
- Disabled by default — CALM_OTEL_ENABLED=false. No collector required for dev/test.
- OTLP exporter — sends to any OTEL Collector (Jaeger, Grafana Tempo, Datadog, Splunk, etc.)
- No -javaagent — Quarkus extension handles everything natively
- No unbounded cardinality — file paths and user IDs are NOT used as metric tags
- No secrets in spans — tokens never appear in trace attributes
- Progressive instrumentation — use @WithSpan annotations as features are built, don't front-load
### Target Project:
...which existing project in the monorepo will this feature be added to?
### Description of Feature:
...what capabilities will the new feature provide, and why is it needed?
### User Stories:
...describe the feature from an end-user perspective, using "As a [role], I want [feature] so that [benefit]" format...
### Current Limitations:
...describe why this functionality isn't possible with the current implementation...
### Proposed Implementation:
...provide details of the intended implementation approach, including:
- Technical design considerations
- API changes (if applicable)
- Data model changes (if applicable)
- Dependencies on other components
### Alternatives Considered:
...what other approaches were considered and why were they rejected?
### Testing Strategy:
...how will this feature be tested? Include unit, integration, and any other testing considerations...
### Documentation Requirements:
...what documentation will need to be created or updated?
### Implementation Checklist:
- [ ] Design reviewed and approved
- [ ] Implementation completed
- [ ] Tests written and passing
- [ ] Documentation updated
- [ ] Relevant workflows updated (if needed)
- [ ] Performance impact assessed
### Additional Context:
...add any other context, diagrams, mockups, or screenshots about the feature request here...
Contributor guide
Research direction
Start by locating the calm-hub project and its Quarkus configuration, then review how the Quarkus OTEL extension can provide traces, metrics, and structured logs. Use CALM_OTEL_ENABLED=false and the OTLP exporter requirements as configuration constraints. Done should include production-ready observability, testing, documentation, and the checklist items described in the issue.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java
- Domain
- backend, observability
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100