📊 Observability Stack with OpenTelemetry, Prometheus, Grafana & FastAPI (Docker)

📊 Pilha de observabilidade com OpenTelemetry, Prometheus, Grafana e FastAPI (Docker)

15 de abril de 2025 Pedro Martins

Este projeto configura um pipeline de observabilidade completo usando o Docker Compose, incluindo:

OpenTelemetry Collector – Recebe e processa dados de telemetria (métricas e rastros)
Prometheus – Coleta e armazena dados de métricas
Grafana – Visualiza as métricas com painéis
Aplicativo FastAPI – Um aplicativo da web instrumentado que envia dados de rastreamento para o Coletor

Para exemplos adicionais e soluções OpenTelemetry estendidas, confira o repositório Open-Telemetry-Solutions .

📁 Estrutura do Projeto

O repositório está organizado da seguinte forma:

docker-compose.yml: define todos os quatro serviços (Collector, Prometheus, Grafana, FastAPI).
otel-collector-config.yaml: Configura o Collector para receber telemetria OTLP e exportar métricas e rastreamentos.
prometheus.yml: Configura o Prometheus para extrair métricas do Coletor.
datasource.yml: Provisiona o Grafana com uma fonte de dados do Prometheus.
fastapi-app/: Contém o aplicativo FastAPI que envia dados de rastreamento para o Coletor.

🚀 Começando

1. Clone o Repositório

2. Execute o Docker Compose

Inicie todos os serviços com:

Este comando iniciará:

OpenTelemetry Collector nas portas 4317 (gRPC) e 4318 (HTTP)
Prometheus na porta 9090
Grafana na porta 3000
Aplicação FastAPI na porta 8000

🛠️ Arquivos de configuração

docker-compose.yml

O arquivo Compose integra todos os serviços. Observe que o serviço FastAPI é criado a partir do diretório local e configurado para enviar dados de rastreamento para o endpoint do Coletor:

inhame

version: '3.8'
services:
  otel-collector:
    image: otel/opentelemetry-collector-contrib:latest
    volumes:
      - ./otel-collector-config.yaml:/etc/otelcol-contrib/config.yaml
    ports:
      - "1888:1888"   # pprof for performance profiling
      - "4317:4317"   # OTLP gRPC receiver
      - "4318:4318"   # OTLP HTTP receiver 
- "8890:8890" # Métricas do Prometheus exportadas pelo Coletor
 - "8889:8889" # Métricas do exportador Prometheus (se necessário)
 - "13133:13133" # Ponto de extremidade de verificação de integridade

 Prometeu:
 imagem: prom/prometheus:latest
 volumes:
 - ./prometheus.yml:/etc/prometheus/prometheus.yml
 portas:
 - "9090:9090"

 grafana: 
imagem: grafana/grafana:latest
 volumes:
 - ./grafana/provisionamento:/etc/grafana/provisionamento
 ambiente:
 - GF_SECURITY_ADMIN_PASSWORD=admin
 portas:
 - "3000:3000"

 aplicativo fastapi:
 construir: ./fastapi-app
 portas:
 - "8000:8000"
 ambiente:
 - OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318/v1/traces 
depende_de:
 - colecionador de hotéis

otel-collector-config.yaml

Este arquivo configura o Coletor para receber dados OTLP para métricas e rastreamentos e enviar métricas ao Prometheus. Os rastreamentos são enviados para um exportador de depuração que os registra para facilitar a verificação.

prometheus.yml

Este arquivo instrui o Prometheus a extrair métricas do exportador Prometheus do Collector:

grafana/provisionamento/fontes de dados/fonte de dados.yml

O Grafana é provisionado automaticamente com o Prometheus como sua fonte de dados padrão:

🚀 Aplicação FastAPI

O serviço FastAPI é instrumentado com OpenTelemetry para enviar dados de rastreamento ao Collector.

fastapi-app/Dockerfile

fastapi-app/requisitos.txt

fastapi-app/main.py

pitão

from fastapi import FastAPI
 from opentelemetry import trace

de opentelemetry.instrumentation.fastapi importar FastAPIInstrumentor de opentelemetry.sdk.resources importar SERVICE_NAME, Recurso de opentelemetry.sdk.trace importar TracerProvider de opentelemetry.sdk.trace.export importar BatchSpanProcessor de opentelemetry.exporter.otlp.proto.http.trace_exporter importar OTLPSpanExporter aplicativo = FastAPI() # Configurar OpenTelemetry para FastAPI recurso = Recurso(atributos={SERVICE_NAME: "fastapi-service" }) provedor = TracerProvider(recurso=recurso) trace.set_tracer_provider(provedor) # Configure o exportador OTLP para enviar rastreamentos ao Coletor. otlp_exporter = OTLPSpanExporter( endpoint= "http://otel-collector:4318/v1/traces" ) span_processor = BatchSpanProcessor(otlp_exporter) provedor.add_span_processor(processador_span) # Instrumento FastAPI encaminha automaticamente FastAPIInstrumentor.instrument_app(app) @app.get( "/" ) async def read_root (): retornar { "mensagem" : "Olá da FastAPI" } @app.get( "/gatilho" ) async def trigger_trace (): rastreador = trace.get_tracer(__nome__) com tracer.start_as_current_span( "manual-span" ): return { "message" : "Intervalo de rastreamento manual enviado ao coletor" }

🖥️ Acesse as Interfaces

Grafana : http://localhost:3000
Login: admin / admin
Prometeu : http://localhost:9090
Aplicação FastAPI : http://localhost:8000
O endpoint / retorna uma mensagem de boas-vindas e /trigger gera um rastreamento manual.

📡 Enviando Telemetria

Seu aplicativo FastAPI instrumentado envia automaticamente dados de rastreamento para o Coletor em:

http://otel-collector:4318/v1/traces (dentro de redes Docker)

Fora do Docker, você pode testar usando:

http://localhost:4318/v1/traces (se você mapear a porta externamente)

Para métricas, envie para:

http://localhost:4318/v1/metrics (HTTP) ou
grpc://localhost:4317 (gRPC)

Você pode usar seus próprios aplicativos ou ferramentas instrumentadas, como otel-cli .

⚠️ Correção do erro da porta 55679 (zPages)

Se você encontrar este erro:

Soluções:

Opção 1 : remova a porta de mapeamento de linha 55679 do docker-compose.yml se você não estiver usando o zPages.
Opção 2 : Altere para uma porta livre, por exemplo:

inhame

- "55678:55679"

Em seguida reinicie com:

🧱 Crie painéis no Grafana

Assim que suas métricas estiverem chegando:

Efetue login no Grafana em http://localhost:3000 .
Crie novos painéis para visualizar métricas importantes, como:
- Solicitar taxas
- Métricas de aplicativos personalizados
- Contagens de erros
- E muito mais!

📚 Recursos adicionais

Explore mais soluções para OpenTelemetry e observabilidade consultando o repositório Open-Telemetry-Solutions . Ele contém exemplos detalhados, integrações e práticas recomendadas que podem ser úteis para seus projetos.