https://github.com/gabrielldn/java-api-with-otlp-sdk
It provides CRUD operations for user management, follows a layered architecture (Controller-Service-Repository), and uses JPA/Hibernate with an in-memory H2 database. Additionally, it automatically integrates metrics, traces, and logs via OpenTelemetry.
https://github.com/gabrielldn/java-api-with-otlp-sdk
api-rest java java-api-rest logs metrics opentelemetry traces
Last synced: about 2 months ago
JSON representation
It provides CRUD operations for user management, follows a layered architecture (Controller-Service-Repository), and uses JPA/Hibernate with an in-memory H2 database. Additionally, it automatically integrates metrics, traces, and logs via OpenTelemetry.
- Host: GitHub
- URL: https://github.com/gabrielldn/java-api-with-otlp-sdk
- Owner: gabrielldn
- License: mit
- Created: 2025-03-05T15:29:58.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-09T03:43:36.000Z (about 1 year ago)
- Last Synced: 2025-06-09T04:31:51.095Z (about 1 year ago)
- Topics: api-rest, java, java-api-rest, logs, metrics, opentelemetry, traces
- Language: Java
- Homepage: https://github.com/gabrielldn?tab=packages&repo_name=java-api-with-otlp-sdk
- Size: 42.4 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Java API with OTLP SDK
API REST em Spring Boot com exportacao OTLP de traces, metricas e logs, stack local de observabilidade com OpenTelemetry Collector + Grafana LGTM, e automacao de carga continua para gerar sinais observaveis.
## Conexao com a plataforma
Este repositório é o workload de referência do laboratório de plataforma:
- Deploy GitOps/canary: `secure-gitops-platform`
- https://github.com/gabrielldn/secure-gitops-platform
- Backend PostgreSQL HA/chaos: `postgres-ha-chaos-lab`
- https://github.com/gabrielldn/postgres-ha-chaos-lab
Fluxo integrado: app instrumentado -> build/scan/sign/attest -> Argo Rollouts com AnalysisTemplate -> Postgres HA.
## Objetivo do projeto
Entregar um laboratorio local reproduzivel para:
- Expor endpoints REST em `http://localhost:8080/api/v1/...`.
- Exportar traces, metricas e logs via OTLP HTTP.
- Visualizar sinais em Grafana/Prometheus/Tempo/Loki.
- Gerar trafego continuo com `make integration`.
## Stack principal
- Runtime/API: `Java 25`, `Spring Boot 3.5.11`, `Maven`.
- Persistencia: `H2` (fallback local) e `PostgreSQL` (ambiente GitOps/Kubernetes).
- Telemetria: `Micrometer + OpenTelemetry (OTLP)`.
- Metricas para canary analysis: endpoint `Prometheus` em `/actuator/prometheus`.
- Logs OTLP: `Logback OpenTelemetry appender`.
- Observabilidade local: `otel/opentelemetry-collector-contrib:0.146.1` + `grafana/otel-lgtm:0.19.0`.
- Automacao operacional: `Makefile`.
## Requisitos
Minimo para nao configurar tudo manualmente:
- `make` (GNU Make)
Com isso, execute:
```bash
make setup
```
Se for seguir setup manual completo, veja `docs/prerequisites.md`.
## Enderecos principais
- API base: `http://localhost:8080/api/v1`
- Swagger UI: `http://localhost:8080/api/v1/swagger-ui/index.html`
- ReDoc: `http://localhost:8080/api/v1/redoc`
- OpenAPI JSON: `http://localhost:8080/api/v1/api-docs`
- Grafana: `http://localhost:3000` (`admin/admin`)
- Collector health: `http://localhost:13133`
- Dashboard compativel RED classic: `http://localhost:3000/d/java-api-red-micrometer-classic`
- Dashboard compativel RED native: `http://localhost:3000/d/java-api-red-micrometer-native`
## Contratos do repositorio
- Operacao local: `Makefile`.
- Build de imagem multi-stage: `Dockerfile`.
- Stack docker observability: `docker/compose.observability.yml`.
- Config do collector: `docker/otel-collector-config.yaml`.
- Carga continua: `scripts/integration-loop.sh`.
- Compatibilidade de dashboards Grafana: `scripts/grafana-dashboard-compat.sh`.
- Codigo da API: `src/main/java`.
- Configuracoes: `src/main/resources`.
- Documentacao detalhada: `docs/`.
## Comecando rapido (fluxo recomendado)
1. Preparar ambiente:
```bash
make setup
```
2. Subir observabilidade:
```bash
make observability-up
make observability-smoke
```
3. Subir API:
```bash
make run
```
4. Em outro terminal, iniciar carga continua:
```bash
make integration
make integration-status
```
5. Abrir Grafana e usar os dashboards compativeis do projeto:
- `RED Metrics (Micrometer OTLP - classic)`
- `RED Metrics (Micrometer OTLP - native compatibility)`
6. Encerrar ambiente:
```bash
make integration-stop
make down
make observability-down
```
## Comandos make
- `make setup`: valida Java/Maven/Docker/Compose e baixa dependencias Maven.
- `make run`: sobe API local (foreground).
- `make down`: derruba processo da API na porta configurada.
- `make observability-up`: sobe Collector + LGTM e aplica dashboards compativeis.
- `make observability-down`: derruba stack de observabilidade.
- `make observability-logs`: tail dos logs de `otel-collector` e `lgtm`.
- `make observability-smoke`: valida health de Collector e Grafana.
- `make observability-dashboards`: cria/atualiza dashboards compativeis RED.
- `make integration`: inicia loop de trafego em background.
- `make integration-stop`: para loop de trafego.
- `make integration-status`: status do loop e ultimas linhas de log.
- `make test`: executa testes.
Variaveis uteis:
- `APP_PORT` (default: `8080`)
- `INTEGRATION_API_BASE_URL` (default: `http://localhost:${APP_PORT}/api/v1`)
- `INTEGRATION_INTERVAL_SECONDS` (default: `1`)
- `OTLP_TRACES_ENDPOINT` (default: `http://localhost:4318/v1/traces`)
- `OTLP_METRICS_ENDPOINT` (default: `http://localhost:4318/v1/metrics`)
- `OTLP_LOGS_ENDPOINT` (default: `http://localhost:4318/v1/logs`)
- `APP_ENV` (default: `local`)
- `APP_VERSION` (default: `0.0.1-SNAPSHOT`)
- `APP_INSTANCE_ID` (default: `${HOSTNAME}` ou `random UUID`)
- `SPRING_DATASOURCE_URL` (default: `jdbc:h2:mem:testdb`)
- `SPRING_DATASOURCE_USERNAME` (default: `sa`)
- `SPRING_DATASOURCE_PASSWORD` (default: vazio)
- `SPRING_DATASOURCE_DRIVER_CLASS_NAME` (default: `org.h2.Driver`)
- `SPRING_JPA_HIBERNATE_DDL_AUTO` (default: `update`)
- `SPRING_H2_CONSOLE_ENABLED` (default: `true`)
- `SERVER_PORT` (default: `8080`)
- `MANAGEMENT_SERVER_PORT` (default: mesmo valor de `SERVER_PORT`)
## Documentacao
- Indice: `docs/README.md`
- Pre-requisitos: `docs/prerequisites.md`
- Arquitetura: `docs/architecture.md`
- Operacoes: `docs/operations.md`
- API e contratos HTTP: `docs/api.md`
- Observabilidade e dashboards: `docs/observability.md`
- Troubleshooting: `docs/troubleshooting.md`
## Estrutura do projeto
```text
java-api-with-otlp-sdk/
|-- docker/
| |-- compose.observability.yml
| `-- otel-collector-config.yaml
|-- docs/
| |-- README.md
| |-- api.md
| |-- architecture.md
| |-- observability.md
| |-- operations.md
| |-- prerequisites.md
| `-- troubleshooting.md
|-- scripts/
| |-- grafana-dashboard-compat.sh
| `-- integration-loop.sh
|-- src/
| |-- main/
| `-- test/
|-- Dockerfile
|-- Makefile
|-- pom.xml
`-- README.md
```
## Escopo e seguranca
- Escopo focado em desenvolvimento local e testes.
- Credenciais padrao do Grafana (`admin/admin`) sao aceitaveis apenas para ambiente local.
- Nao usar esta composicao como baseline de producao.
## Licenca
MIT - veja `LICENSE`.