Skip to main content

Monitoramento com colibri-sdk-go e OpenTelemetry

· 3 min read
Rafael Ramos de Oliveira
Rafael Ramos de Oliveira
Colibri project dev

Aprenda, em minutos, a instrumentar seus serviços Go com colibri-sdk-go e OpenTelemetry. Suba o stack com docker-compose, configure as variáveis de ambiente e visualize seus traces no Jaeger — com exemplos práticos, módulos reais e dicas de melhores práticas para observabilidade de ponta a ponta.

Estrutura do exemplo​

  • github

  • Módulos de exemplo:

    • school-module
    • finantial-module

  • Serviços de apoio (dev/):

    • otel-collector
    • localstack
    • postgres

Pré‑requisitos​

  • Docker e Docker Compose
  • Go 1.24+
  • Make

Como subir o ambiente de observabilidade​

O projeto de exemplo já fornece um docker-compose com os serviços necessários prontos para uso.

  1. Faça o clone do repositório
git clone https://github.com/colibriproject-dev/colibri-sdk-go-examples.git
  1. Compile os projetos com o comando:
make build
  1. Suba os serviços de infraestrutura com o comando:
make start
  1. Acesse o Jeager na url http://localhost:16686/

Configuração OpenTelemetry no SDK​

O SDK colibri-sdk-go já inclui integração com OTel. Veja o arquivo:

Os módulos de exemplo consomem essa configuração. Ao iniciar cada serviço, o SDK inicializa o provedor de traces e exportadores conforme as variáveis de ambiente.

Variáveis de ambiente relevantes (exemplos)​

  • OTEL_EXPORTER_OTLP_ENDPOINT: apontar para o Collector (ex.: http://otel-collector:4317)
  • OTEL_SERVICE_NAME: nome do serviço (ex.: school-api)
  • OTEL_RESOURCE_ATTRIBUTES: atributos extras (ex.: deployment.environment=dev)
  • COLIBRI_LOG_LEVEL: nível de log

Confira os arquivos .env em cada módulo:

  • school-module/.env
  • finantial-module/.env

Gerando tracing​

  • Crie um curso no school-module:
curl --request POST \
  --url http://localhost:8080/public/v1/courses \
  --header 'Content-Type: application/json' \
  --data '{"name": "Course 001","value": 100}'
  • Com o id retornado na criação do curso, execute uma busca:
curl --request GET --url http://localhost:8080/public/v1/courses/fe6fa672-8ce0-11f0-a8e8-a3ca18a3537e

Explorando métricas e traces​

Exemplo de tracing para a chamada REST de busca de curso por id: tracing

Boas práticas​

  • Nomeie OTEL_SERVICE_NAME por módulo para facilitar filtros.
  • Propague context.Context em toda a call stack.
  • Anexe atributos-chave (user_id, order_id) como span attributes quando relevante.
  • Defina sampling apropriado no Collector para ambientes de produção.