# blueswen/spring-boot-observability architecture

> Architecture diagram of the GitHub repository blueswen/spring-boot-observability, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-02-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/blueswen/spring-boot-observability
- Repository: https://github.com/blueswen/spring-boot-observability

## Overview

##### Main Components
- Spring Boot Applications: Represent “app” as the central service codebase. Note that although the code is shared, the demo runs three instances (app-a, app-b, app-c) to illustrate distributed behavior and cross-service communication.
- Observability Pipeline:
- Tracing: OpenTelemetry instrumentation that sends span data to Tempo.
- Metrics: Prometheus scrapes metrics (exposed via Spring Boot Actuator and Micrometer) and handles exemplars.
- Logs: Loki collects container logs enriched with trace details using the Loki Docker Driver.
- Grafana: Acts as the unified dashboard that queries all three data sources (Prometheus, Tempo, Loki) to correlate traces, metrics, and logs.
- Supporting Configuration and Orchestration: Include Docker Compose (which orchestrates containerized services) and configuration directories (etc for dashboards, grafana datasource configurations, Prometheus config, etc).

##### Relationships and Data Flows
- The Spring Boot applications serve client HTTP requests and expose endpoints (including Swagger endpoints and /actuator/prometheus for metrics).
- Outbound instrumentation flows:
- For traces: The OpenTelemetry Java Agent automatically intercepts and forwards spans to Tempo.
- For metrics: Actuator/Micrometer expose Prometheus-format metrics which are scraped by Prometheus.
- For logs: The configured Logback (with modified logging pattern that includes trace context) is sent via the Loki Docker Driver to Loki.
- Grafana sits as the front-end dashboard and pulls data from Prometheus (with exemplars linking to Tempo), Tempo (for traces), and Loki (for logs), and orchestrates the correlations between these systems.

##### Architectural Patterns and Components
- Containerized Microservices: Though the code is shared, the demo involves multiple instances to simulate distributed tracing across services.
- Use of External Agents and Auto-Instrumentation: Indicate that the OpenTelemetry agent enriches the application without code changes.
- Integration with External Monitoring Tools: Show how Prometheus scrapes endpoints, Tempo receives spans, and Loki aggregates logs—all configured in the “etc” folder.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Compose["Docker Compose\n(Orchestration)"]:::orchestrate

    subgraph "Spring Boot App Instances"
        AppA["Spring Boot App Instance (app-a)"]:::app
        AppB["Spring Boot App Instance (app-b)"]:::app
        AppC["Spring Boot App Instance (app-c)"]:::app
    end

    subgraph "Observability Backends"
        Prometheus["Prometheus\n(Metrics)"]:::prometheus
        Tempo["Tempo\n(Tracing)"]:::tempo
        Loki["Loki\n(Logs)"]:::loki
    end

    Grafana["Grafana\n(Dashboard)"]:::grafana

    subgraph "Configurations"
        MetricsAppConfig["Application Config\n(application.yaml)"]:::config
        MetricsPromConfig["Prometheus Exemplar Config\n(PrometheusExemplarSamplerConfiguration.java)"]:::config
        GrafanaDatasource["Grafana Datasource\n(datasource.yml)"]:::config
        GrafanaDash["Grafana Dashboards\n(dashboards.yaml)"]:::config
        GrafanaObservability["Grafana Observability Dashboard\n(spring-boot-observability.json)"]:::config
        PromConf["Prometheus Config\n(prometheus.yml)"]:::config
    end

    %% Orchestration: Docker Compose deploys all services
    Compose --> AppA
    Compose --> AppB
    Compose --> AppC
    Compose --> Prometheus
    Compose --> Tempo
    Compose --> Loki
    Compose --> Grafana

    %% Inter-service communication (chain calls)
    AppA -->|"chain"| AppB
    AppB -->|"chain"| AppC

    %% Data flows from Spring Boot apps to observability systems
    AppA -->|"metrics(/actuator/prometheus)"| Prometheus
    AppB -->|"metrics(/actuator/prometheus)"| Prometheus
    AppC -->|"metrics(/actuator/prometheus)"| Prometheus

    AppA -->|"spans(OpenTelemetry)"| Tempo
    AppB -->|"spans(OpenTelemetry)"| Tempo
    AppC -->|"spans(OpenTelemetry)"| Tempo

    AppA -->|"logs(Logback)"| Loki
    AppB -->|"logs(Logback)"| Loki
    AppC -->|"logs(Logback)"| Loki

    %% Grafana queries observability data sources
    Grafana -->|"queries"| Prometheus
    Grafana -->|"queries"| Tempo
    Grafana -->|"queries"| Loki

    %% Link configuration files to relevant components (dotted connections)
    MetricsAppConfig --- AppA
    MetricsPromConfig --- AppA
    PromConf --- Prometheus
    GrafanaDatasource --- Grafana
    GrafanaDash --- Grafana
    GrafanaObservability --- Grafana

    %% Styles for different components
    classDef app fill:#ADD8E6,stroke:#0000FF,stroke-width:2px
    classDef prometheus fill:#90EE90,stroke:#008000,stroke-width:2px
    classDef tempo fill:#FFD700,stroke:#FF8C00,stroke-width:2px
    classDef loki fill:#DDA0DD,stroke:#800080,stroke-width:2px
    classDef grafana fill:#FF6347,stroke:#B22222,stroke-width:2px
    classDef orchestrate fill:#D3D3D3,stroke:#808080,stroke-width:2px
    classDef config fill:#F0E68C,stroke:#B8860B,stroke-width:2px

    %% Click Events for component mapping
    click AppA "https://github.com/blueswen/spring-boot-observability/tree/main/app/"
    click AppB "https://github.com/blueswen/spring-boot-observability/tree/main/app/"
    click AppC "https://github.com/blueswen/spring-boot-observability/tree/main/app/"
    click Compose "https://github.com/blueswen/spring-boot-observability/blob/main/docker-compose.yaml"
    click MetricsAppConfig "https://github.com/blueswen/spring-boot-observability/blob/main/app/src/main/resources/application.yaml"
    click MetricsPromConfig "https://github.com/blueswen/spring-boot-observability/blob/main/app/src/main/java/com/example/app/PrometheusExemplarSamplerConfiguration.java"
    click GrafanaDatasource "https://github.com/blueswen/spring-boot-observability/blob/main/etc/grafana/datasource.yml"
    click GrafanaDash "https://github.com/blueswen/spring-boot-observability/blob/main/etc/dashboards.yaml"
    click GrafanaObservability "https://github.com/blueswen/spring-boot-observability/blob/main/etc/dashboards/spring-boot-observability.json"
    click PromConf "https://github.com/blueswen/spring-boot-observability/blob/main/etc/prometheus/prometheus.yml"
```
