Um sistema distribuído em Go com três microsserviços encadeados, demonstrando a implementação completa de observabilidade com OpenTelemetry para tracing e métricas. Os dados são coletados pelo OpenTelemetry Collector e visualizados com Jaeger, Zipkin, Prometheus e Grafana.
Este projeto ilustra uma arquitetura de microsserviços que se comunicam em cadeia, com uma camada robusta de observabilidade.
Cliente → goapp (8080) → goapp2 (8181) → goapp3 (8282)
↓ ↓ ↓
OpenTelemetry SDK (Traces & Metrics via OTLP)
↓
OpenTelemetry Collector (4317)
↓
├── Traces → Jaeger (16686)
└── Traces → Zipkin (9411)
├── Metrics → Prometheus (8889)
└── Metrics (direto) → Prometheus (8080, 8181, 8282)
↓
Grafana (3001) → Prometheus (Visualização)
- goapp (porta 8080): O microsserviço de entrada. Recebe requisições e faz uma chamada externa para goapp2.
- goapp2 (porta 8181): Microsserviço intermediário. Recebe requisições de goapp e faz uma chamada externa para goapp3.
- goapp3 (porta 8282): O microsserviço final na cadeia. Processa a requisição e retorna.
- otel-collector (portas 4317, 13133, 1888, 55679): O coração da observabilidade. Recebe traces e métricas via OTLP das aplicações Go, processa-os e os exporta para Jaeger, Zipkin e Prometheus.
- jaeger-all-in-one (porta 16686): Backend e UI para visualização de traces distribuídos.
- zipkin-all-in-one (porta 9411): Outro backend e UI popular para visualização de traces distribuídos.
- prometheus (porta 9090): Banco de dados de séries temporais para armazenamento e consulta de métricas. Coleta métricas do otel-collector e diretamente das goapps.
- grafana (porta 3001): Plataforma de visualização e dashboards para as métricas coletadas pelo Prometheus.
- Docker e Docker Compose instalados.
# Clone o repositório
git clone https://github.com/seu-usuario/Go-OpenTelemetry-Observability-Microservices-Demo.git
cd Go-OpenTelemetry-Observability-Microservices-Demo
# Inicia todos os serviços em segundo plano
docker-compose up --build -d
# Para parar e remover os serviços
docker-compose downAguarde alguns segundos para todos os serviços subirem!
Para testar o sistema, basta fazer uma requisição HTTP para o goapp (o serviço de entrada), que irá encadear as chamadas para goapp2 e goapp3.
curl http://localhost:8080Você deve receber uma resposta HTML simples, indicando que a requisição passou por todos os microsserviços. Faça várias requisições para gerar mais dados de telemetria.
- Acesse a interface do Jaeger em: http://localhost:16686
- No menu "Service", selecione microservice-demo (ou microservice-demo2, microservice-demo3).
- Clique em "Find Traces" para ver os traces.
- Clique em um trace individual para ver o fluxo completo da requisição através dos microsserviços, incluindo os spans de goapp, goapp2 e goapp3.
- Acesse a interface do Zipkin em: http://localhost:9411
- Clique em "Run Query" para ver os traces recentes.
- Clique em um trace para ver a visualização em cascata dos spans.
-
Acesse a interface do Prometheus em: http://localhost:9090
-
Na aba "Graph", no campo "Expression", você pode testar algumas queries:
-
up: Verifica a saúde dos alvos de scrape. Você deve verup{instance="otel-collector:8889", job="otel-collector"} 1eup{instance="goapp:8080", job="goapp"} 1(e para goapp2/goapp3). -
Use o autocomplete na caixa de expressão para descobrir outras métricas disponíveis (comece a digitar
http_ougo_).
-
-
Acesse a interface do Grafana em: http://localhost:3001
-
Faça login com as credenciais padrão: admin / admin (você será solicitado a criar uma nova senha).
-
Adicione o Prometheus como Data Source:
-
Vá em "Connections" (ou "Configuration" > "Data sources").
-
Clique em "Add data source" e selecione "Prometheus".
-
Em "URL", insira
http://prometheus:9090. -
Clique em "Save & test". Você deve ver "Data source is working".
Importe um Dashboard (opcional, mas recomendado):
- Você pode importar dashboards pré-existentes da comunidade Grafana para Go ou OpenTelemetry. Por exemplo, procure por "Go Application" ou "OpenTelemetry Collector" em Grafana Dashboards.
- Vá em "Dashboards" > "Import".
- Cole o ID ou o JSON do dashboard importado e selecione seu data source Prometheus.
-
Os principais arquivos de configuração estão localizados na pasta .docker/ e no docker-compose.yaml.
docker-compose.yaml Este arquivo orquestra todos os serviços. As variáveis de ambiente para cada goapp são cruciais para a configuração do OpenTelemetry SDK e a cadeia de chamadas:
- OTEL_SERVICE_NAME: Nome do serviço (ex: microservice-demo, microservice-demo2). Essencial para identificação nos traces e métricas.
- OTEL_EXPORTER_OTLP_ENDPOINT: Endereço do OpenTelemetry Collector para onde os dados de telemetria são enviados (ex: otel-collector:4317).
- EXTERNAL_CALL_URL: URL do próximo serviço na cadeia (ex: http://goapp2:8181).
- HTTP_PORT: Porta interna do container para o serviço (ex: :8080).
.docker/otel-collector-config.yaml Define como o OpenTelemetry Collector recebe, processa e exporta os dados de telemetria.
- receivers.otlp.protocols.grpc.endpoint: Configurado para 0.0.0.0:4317 para permitir que outros containers se conectem.
- exporters.zipkin: Envia traces para o Zipkin.
- exporters.otlp: Envia traces para o Jaeger (que também suporta OTLP).
- exporters.prometheus: Expõe métricas para o Prometheus na porta 8889. pipelines.traces e pipelines.metrics: Definem o fluxo dos dados de traces e métricas.
.docker/prometheus.yaml Configura o Prometheus para raspar métricas de seus alvos:
- job_name: "otel-collector": Raspa métricas do otel-collector na porta 8889.
- job_name: "goapp" (e goapp2, goapp3): Raspam métricas diretamente das aplicações Go nas suas respectivas portas (8080, 8181, 8282).
Go-OpenTelemetry-Observability-Microservices-Demo/
├── .docker/
│ ├── otel-collector-config.yaml # Configuração do OpenTelemetry Collector
│ └── prometheus.yaml # Configuração do Prometheus
├── cmd/ # Aplicações Go (goapp, goapp2, goapp3 usam o mesmo código base)
│ └── main.go
├── internal/web/\*
│ └── server.go # Instancia do servidor
├── docker-compose.yaml # Orquestração de todos os serviços
├── Dockerfile # Dockerfile para as aplicações Go
└── go.mod # Dependências do projeto Go
Sem traces no Jaeger/Zipkin
- Faça requisições ao goapp:8080 para gerar traces.
- Verifique os logs do otel-collector para mensagens de "Exporting traces".
- Certifique-se de que Jaeger (http://localhost:16686) e Zipkin (http://localhost:9411) estão acessíveis.
Sem métricas no Prometheus/Grafana
- No Prometheus (http://localhost:9090), execute a query up e verifique se todos os alvos (otel-collector:8889, goapp:8080, etc.) estão com 1. Se algum estiver 0, há um problema de conectividade ou o serviço não está expondo métricas.
- Verifique o prometheus.yaml para garantir que os alvos de scrape estão configurados corretamente.
- Confirme se o Grafana está configurado com http://prometheus:9090 como data source.
Este projeto é uma excelente demonstração de:
- Microserviços em Go: Construção de aplicações distribuídas e sua comunicação.
- OpenTelemetry: Instrumentação de aplicações para coletar traces e métricas de forma padronizada.
- OpenTelemetry Collector: A central de processamento de telemetria, desacoplando a instrumentação dos backends.
- Distributed Tracing (Jaeger & Zipkin): Como rastrear requisições através de múltiplos serviços.
- Métricas de Monitoramento (Prometheus): Coleta, armazenamento e consulta de métricas de performance e saúde.
- Visualização de Dados (Grafana): Criação de dashboards interativos para monitorar o sistema.
- Docker e Docker Compose: Orquestração e gerenciamento de ambientes de desenvolvimento e produção.
- Context Propagation: Como o contexto de tracing é passado entre os serviços.
- Observabilidade End-to-End: Uma visão completa do comportamento do sistema.
Desenvolvido com ❤️ em Go para aprendizado de Microserviços com Observabilidade