finos / finos/architecture-as-code

Add OpenTelemetry observability (traces, metrics, structured logs) in Calm Hub

Open
#2,945 1 comment 1 reaction 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.