Skip to content

Observability Architecture

Overview

This page documents the observability flow that is currently implemented in the repository and the role of Prometheus and Grafana in the local stack.

Repository Snapshot

Aspect Current State
Metrics producer user-service
Metrics endpoint /actuator/prometheus
Metrics collector Prometheus
Dashboard layer Grafana
Grafana repository configuration observability/grafana/

Implemented Flow

  • user-service exposes Prometheus-formatted metrics through Spring Boot Actuator.
  • Prometheus scrapes the exposed metrics endpoint and stores the resulting time-series locally.
  • Grafana uses Prometheus as its datasource and renders dashboard panels for operational inspection.

Interaction Diagram

No observability diagram available.

Configuration Layout

Path Purpose
observability/grafana/provisioning/datasources/prometheus.yml Grafana datasource provisioning for Prometheus.
observability/grafana/provisioning/dashboards/dashboards.yml Grafana dashboard provisioning configuration.
observability/grafana/dashboards/tyche-user-service-overview.json Initial dashboard definition for user-service.
docker-compose.yml Local container stack wiring for user-service, Prometheus, and Grafana.
docker/prometheus/entrypoint.sh Runtime generation of Prometheus config from local-only secrets.
docker/grafana/entrypoint.sh Runtime injection of Grafana admin credentials from local-only secrets.

Docker Stack

Aspect Current State
Compose file docker-compose.yml
user-service containerized Yes
prometheus containerized Yes
grafana containerized Yes
postgres profile always-on or not detected
Local bind for app 127.0.0.1:${USER_SERVICE_PORT:-8080}:8080
Local bind for Prometheus 127.0.0.1:${PROMETHEUS_PORT:-9090}:9090
Local bind for Grafana 127.0.0.1:${GRAFANA_PORT:-3001}:3000
  • The local stack is intended for workstation use and publishes the app, Prometheus, and Grafana only on loopback (127.0.0.1).
  • Prometheus and Grafana bootstrap local-only credentials through entrypoint scripts instead of storing resolved secrets in committed container environment values.
  • user-service currently connects to the host PostgreSQL instance for the main local workflow, while the Compose postgres service is retained as an optional profile-backed container.

Metrics Families

Metrics family What it covers
tyche_auth_* Auth-domain requests, outcomes, token lifecycle, and rate-limiting signals.
tyche_user_* User-domain requests, success outcomes, and domain-specific error signals.
http_server_requests_* Endpoint traffic, latency, and response status observations.
jvm_* JVM memory, threads, and runtime state.
jdbc_* Datasource and connection-pool state.

Business-facing tyche_auth_* and tyche_user_* counters are registered with explicit Micrometer descriptions in the service code so their purpose is visible through exported metric metadata as well as through dashboard panel titles.

Notes

  • The current repository contains one implemented service, so the observability flow is presently centered on user-service.
  • Dashboard panels are operational views over Prometheus data and should be interpreted together with the selected time range and generated traffic.