[Backend] Wire Up Prometheus Metrics Endpoint in Observability Module

[llinsss]

⚠️ This is a backend issue — work is done inside the backend/ folder

Description

backend/src/modules/observability/ contains metrics.service.ts, performance-monitoring.service.ts, http-metrics.interceptor.ts, and tracing.service.ts, but none of these are wired to an actual /metrics endpoint. The ObservabilityController exists but exposes no Prometheus-compatible scrape endpoint. Monitoring infrastructure cannot collect metrics without this.

Current State

• metrics.service.ts — collects internal metrics but exposes no HTTP endpoint
• http-metrics.interceptor.ts — records request durations but data goes nowhere
• observability.controller.ts — exists but has no /metrics route
• No prom-client or @willsoto/nestjs-prometheus integration

What Needs to Be Built

1. Install and Configure prom-client

npm install prom-client @willsoto/nestjs-prometheus

• Register PrometheusModule in ObservabilityModule
• Expose GET /metrics (Prometheus text format)
• Secure endpoint: only accessible from internal network or with METRICS_TOKEN header

2. HTTP Request Metrics (via existing interceptor)

Update HttpMetricsInterceptor to record:

• http_requests_total — counter by method, route, status code
• http_request_duration_seconds — histogram by method and route

3. Custom Business Metrics

Add to MetricsService:

• petchain_pets_total — gauge: total registered pets
• petchain_medical_records_total — gauge: total medical records
• petchain_blockchain_syncs_total — counter: successful/failed Stellar syncs
• petchain_active_sessions_total — gauge: active user sessions

4. Apply Interceptor Globally

• Register HttpMetricsInterceptor as a global interceptor in AppModule

5. Health Check Endpoint

GET /health

• Return { status: 'ok', uptime, db: 'connected' | 'error', redis: 'connected' | 'error' }
• Use @nestjs/terminus for DB and Redis health indicators

Acceptance Criteria

• GET /metrics returns valid Prometheus text format
• HTTP request counter and duration histogram are populated after requests
• Business metrics reflect real DB counts
• GET /health returns DB and Redis status
• Metrics endpoint is protected by token or IP allowlist
• HttpMetricsInterceptor is applied globally

Files to Modify / Create

• backend/src/modules/observability/observability.module.ts
• backend/src/modules/observability/observability.controller.ts
• backend/src/modules/observability/metrics.service.ts
• backend/src/modules/observability/http-metrics.interceptor.ts
• backend/src/app.module.ts (register interceptor globally)

Priority

Medium — required for production monitoring and alerting

Estimated Effort

2 days

[yosemite01]

@yosemite01 has applied to work on this issue as part of the Stellar Wave Program's 5th wave.

Hello Maintainer
I'll like to work on this Issue

ℹ️ Repo Maintainers: To accept this application, review their application or assign @yosemite01 to this issue.

[drips-wave]

Congratulations, @yosemite01! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on June 2, 2026.

🧑‍💻 @yosemite01: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊