# danvega/ot architecture

> Architecture diagram of the GitHub repository danvega/ot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/danvega/ot
- Repository: https://github.com/danvega/ot

## Overview

#### Purpose and runtime
This is a Java 17+ Spring Boot 4 demo of the official OpenTelemetry starter. It exposes simple HTTP endpoints while demonstrating automatic OTLP export of traces, metrics, and logs to a vendor-neutral observability backend. Maven is the build/runtime entry point; the application is launched through `src/main/java/dev/danvega/ot/Application.java`.

#### HTTP application surface
`HomeController` is the primary business-facing boundary, serving `GET /`, `GET /greet/{name}`, and `GET /slow`. The greeting and delayed paths create observable request work and application logs, allowing generated telemetry to be inspected end-to-end.
- `src/main/java/dev/danvega/ot/HomeController.java`
- `src/main/java/dev/danvega/ot/Application.java`

#### Spring Boot observability pipeline
Spring Boot auto-configuration, driven by the OpenTelemetry starter declared in `pom.xml`, instruments inbound HTTP requests and integrates Micrometer tracing with OpenTelemetry. Requests become traces/spans; framework/application metrics are emitted through OTLP; trace context is made available to logging.
- `pom.xml`
- `src/main/resources/application.yaml`

#### Logging-to-OTLP bridge
Logback writes both normal console output and events to the OpenTelemetry Logback appender. The appender requires the Spring-managed `OpenTelemetry` SDK instance, so a lifecycle bean installs that instance after context initialization. This is the explicit custom integration required beyond starter auto-configuration.
- `src/main/resources/logback-spring.xml`
- `src/main/java/dev/danvega/ot/InstallOpenTelemetryAppender.java`

#### Telemetry configuration boundary
`application.yaml` establishes the application identity and telemetry behavior, including full development trace sampling and OTLP exporter configuration when not supplied by Compose integration. The key boundary is OTLP/HTTP: metrics, traces, and logs leave the process through collector endpoints rather than application-specific vendor SDKs.
- `src/main/resources/application.yaml`

#### Local infrastructure and external services
`compose.yaml` provides the local Grafana LGTM observability stack. Spring Boot Docker Compose integration can detect this service and configure OTLP connectivity automatically. Grafana is the visualization entry point; its backing components are Loki for logs, Tempo for traces, and Mimir/Prometheus-compatible metrics storage.
- `compose.yaml`
- `pom.xml`

#### End-to-end control flow
1. Spring starts `Application`, creates the web server, OpenTelemetry SDK, exporters, and the appender installation bean.
2. An HTTP request reaches `HomeController`; automatic server instrumentation creates request spans and timing metrics.
3. Controller logs inherit active trace/span context; Logback sends them to console and the OTEL appender.
4. OTLP exporters transmit traces, metrics, and logs to the LGTM collector.
5. Grafana queries Tempo, Loki, and metrics storage for correlated inspection by service and trace identifiers.

Main entry points: [`compose.yaml`](https://github.com/danvega/ot/blob/master/compose.yaml) (LGTM collector), [`pom.xml`](https://github.com/danvega/ot/blob/master/pom.xml) (Boot observability auto-config), [`src/main/resources/application.yaml`](https://github.com/danvega/ot/blob/master/src/main/resources/application.yaml) (OTLP/HTTP export), [`src/main/java/dev/danvega/ot/Application.java`](https://github.com/danvega/ot/blob/master/src/main/java/dev/danvega/ot/Application.java) (Application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Spring Boot application"]
  node_application{{"Application<br/>Spring Boot entry point<br/>[Application.java]"}}
  node_controller["HomeController<br/>HTTP controller"]
  node_app_config["Application telemetry config<br/>Spring configuration<br/>[application.yaml]"]
end

subgraph group_telemetry["OpenTelemetry pipeline"]
  node_boot_observability["Boot observability auto-config<br/>instrumentation<br/>[pom.xml]"]
  node_otel_sdk["OpenTelemetry SDK<br/>telemetry runtime"]
  node_appender_installer["Appender installer<br/>lifecycle bean"]
  node_logback["Logback OTEL appender<br/>logging bridge<br/>[logback-spring.xml]"]
  node_otlp_export["OTLP/HTTP export<br/>telemetry boundary<br/>[application.yaml]"]
end

subgraph group_observability["Local LGTM stack"]
  node_compose{{"Docker Compose integration<br/>local infrastructure<br/>[compose.yaml]"}}
  node_lgtm_collector["LGTM collector<br/>OTLP collector<br/>[compose.yaml]"]
  node_grafana["Grafana<br/>visualization UI<br/>[compose.yaml]"]
  node_tempo[("Tempo<br/>trace store<br/>[compose.yaml]")]
  node_loki[("Loki<br/>log store<br/>[compose.yaml]")]
  node_mimir[("Mimir metrics store<br/>[compose.yaml]")]
end

node_maven{{"Maven build &amp; runtime<br/>build entry point<br/>[pom.xml]"}}

node_maven -->|"launches"| node_application
node_maven -->|"declares starter"| node_boot_observability
node_application -->|"routes HTTP requests"| node_controller
node_application -->|"creates lifecycle bean"| node_appender_installer
node_app_config -->|"configures"| node_boot_observability
node_app_config -->|"sets identity and endpoints"| node_otlp_export
node_boot_observability -->|"creates and uses"| node_otel_sdk
node_controller -->|"request instrumentation"| node_boot_observability
node_controller -->|"application logs"| node_logback
node_appender_installer -->|"installs SDK"| node_logback
node_otel_sdk -->|"provides SDK instance"| node_appender_installer
node_boot_observability -->|"traces and metrics"| node_otlp_export
node_logback -->|"log events"| node_otlp_export
node_compose -->|"provisions"| node_lgtm_collector
node_compose -.->|"may supply connectivity"| node_otlp_export
node_otlp_export -->|"OTLP traces, metrics, logs"| node_lgtm_collector
node_lgtm_collector -->|"stores traces"| node_tempo
node_lgtm_collector -->|"stores logs"| node_loki
node_lgtm_collector -->|"stores metrics"| node_mimir
node_grafana -->|"queries"| node_tempo
node_grafana -->|"queries"| node_loki
node_grafana -->|"queries"| node_mimir

click node_maven "https://github.com/danvega/ot/blob/master/pom.xml"
click node_application "https://github.com/danvega/ot/blob/master/src/main/java/dev/danvega/ot/Application.java"
click node_controller "https://github.com/danvega/ot/blob/master/src/main/java/dev/danvega/ot/HomeController.java"
click node_app_config "https://github.com/danvega/ot/blob/master/src/main/resources/application.yaml"
click node_boot_observability "https://github.com/danvega/ot/blob/master/pom.xml"
click node_appender_installer "https://github.com/danvega/ot/blob/master/src/main/java/dev/danvega/ot/InstallOpenTelemetryAppender.java"
click node_logback "https://github.com/danvega/ot/blob/master/src/main/resources/logback-spring.xml"
click node_otlp_export "https://github.com/danvega/ot/blob/master/src/main/resources/application.yaml"
click node_compose "https://github.com/danvega/ot/blob/master/compose.yaml"
click node_lgtm_collector "https://github.com/danvega/ot/blob/master/compose.yaml"
click node_grafana "https://github.com/danvega/ot/blob/master/compose.yaml"
click node_tempo "https://github.com/danvega/ot/blob/master/compose.yaml"
click node_loki "https://github.com/danvega/ot/blob/master/compose.yaml"
click node_mimir "https://github.com/danvega/ot/blob/master/compose.yaml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_application,node_controller,node_app_config toneBlue
class node_boot_observability,node_otel_sdk,node_appender_installer,node_logback,node_otlp_export toneAmber
class node_compose,node_lgtm_collector,node_grafana,node_tempo,node_loki,node_mimir toneMint
class node_maven toneNeutral
```

## Components

### Spring Boot application

- [Application](https://github.com/danvega/ot/blob/master/src/main/java/dev/danvega/ot/Application.java): Spring Boot entry point · Bootstraps the application context and web server. · `src/main/java/dev/danvega/ot/Application.java`
- [HomeController](https://github.com/danvega/ot/blob/master/src/main/java/dev/danvega/ot/HomeController.java): HTTP controller · Serves /, /greet/{name}, and /slow. · `src/main/java/dev/danvega/ot/HomeController.java`
- [Application telemetry config](https://github.com/danvega/ot/blob/master/src/main/resources/application.yaml): Spring configuration · Defines service identity, sampling, and OTLP behavior. · `src/main/resources/application.yaml`

### OpenTelemetry pipeline

- [Boot observability auto-config](https://github.com/danvega/ot/blob/master/pom.xml): instrumentation · Creates HTTP spans, metrics, and trace-aware logging context. · `pom.xml`
- **OpenTelemetry SDK**: telemetry runtime · Spring-managed SDK used by instrumentation and exporters.
- [Appender installer](https://github.com/danvega/ot/blob/master/src/main/java/dev/danvega/ot/InstallOpenTelemetryAppender.java): lifecycle bean · Installs the Spring-managed SDK into the Logback appender. · `src/main/java/dev/danvega/ot/InstallOpenTelemetryAppender.java`
- [Logback OTEL appender](https://github.com/danvega/ot/blob/master/src/main/resources/logback-spring.xml): logging bridge · Writes application logs to console and OpenTelemetry. · `src/main/resources/logback-spring.xml`
- [OTLP/HTTP export](https://github.com/danvega/ot/blob/master/src/main/resources/application.yaml): telemetry boundary · Exports traces, metrics, and logs without a vendor SDK. · `src/main/resources/application.yaml`

### Local LGTM stack

- [Docker Compose integration](https://github.com/danvega/ot/blob/master/compose.yaml): local infrastructure · Provides and discovers the local observability service. · `compose.yaml`
- [LGTM collector](https://github.com/danvega/ot/blob/master/compose.yaml): OTLP collector · Receives process telemetry for the local stack. · `compose.yaml`
- [Grafana](https://github.com/danvega/ot/blob/master/compose.yaml): visualization UI · Correlates telemetry by service and trace identifiers. · `compose.yaml`
- [Tempo](https://github.com/danvega/ot/blob/master/compose.yaml): trace store · `compose.yaml`
- [Loki](https://github.com/danvega/ot/blob/master/compose.yaml): log store · `compose.yaml`
- [Mimir metrics store](https://github.com/danvega/ot/blob/master/compose.yaml): metrics store · Prometheus-compatible metrics storage. · `compose.yaml`

### Other components

- [Maven build & runtime](https://github.com/danvega/ot/blob/master/pom.xml): build entry point · Supplies Spring Boot and OpenTelemetry starter dependencies. · `pom.xml`

## Connections

- Maven build & runtime → Application: launches
- Maven build & runtime → Boot observability auto-config: declares starter
- Application → HomeController: routes HTTP requests
- Application → Appender installer: creates lifecycle bean
- Application telemetry config → Boot observability auto-config: configures
- Application telemetry config → OTLP/HTTP export: sets identity and endpoints
- Boot observability auto-config → OpenTelemetry SDK: creates and uses
- HomeController → Boot observability auto-config: request instrumentation
- HomeController → Logback OTEL appender: application logs
- Appender installer → Logback OTEL appender: installs SDK
- OpenTelemetry SDK → Appender installer: provides SDK instance
- Boot observability auto-config → OTLP/HTTP export: traces and metrics
- Logback OTEL appender → OTLP/HTTP export: log events
- Docker Compose integration → LGTM collector: provisions
- Docker Compose integration → OTLP/HTTP export: may supply connectivity
- OTLP/HTTP export → LGTM collector: OTLP traces, metrics, logs
- LGTM collector → Tempo: stores traces
- LGTM collector → Loki: stores logs
- LGTM collector → Mimir metrics store: stores metrics
- Grafana → Tempo: queries
- Grafana → Loki: queries
- Grafana → Mimir metrics store: queries