Monitoramento com Colibri SDK Go e OpenTelemetry

O Colibri SDK Go exporta traces e métricas por OTLP HTTP. Neste guia, usamos o repositório de exemplos para iniciar dois serviços, o OpenTelemetry Collector, Jaeger e Prometheus.

Pré-requisitos

• Docker e Docker Compose;
• Go 1.26.2;
• Make.

Iniciar o ambiente

git clone https://github.com/colibriproject-dev/colibri-sdk-go-examples.git
cd colibri-sdk-go-examples
make build
make start

Os principais endereços são:

Serviço	URL
School Module	http://localhost:8080
Financial Module	http://localhost:8081
Jaeger	http://localhost:16686
Prometheus	http://localhost:9090

Configuração OTLP HTTP

O SDK espera a URL base do collector:

OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
OTEL_SERVICE_NAME=school-module

Não inclua /v1/traces ou /v1/metrics; o SDK adiciona o caminho correto para cada sinal.

Quando o endpoint está configurado, a inicialização prepara:

• traces de servidor e cliente HTTP;
• traces e métricas de PostgreSQL;
• instrumentação de mensageria;
• métricas de runtime do Go.

Gerar um trace

Crie um curso:

curl --fail --request POST \
  --url http://localhost:8080/public/v1/courses \
  --header 'Content-Type: application/json' \
  --data '{"name":"Course 001","value":100}'

Use o ID retornado para consultar o curso:

curl --fail http://localhost:8080/public/v1/courses/SEU_ID

Abra http://localhost:16686, selecione school-module e busque os traces recentes.

Diagnóstico

Se nenhum trace aparecer:

1. confirme que o collector está em execução com docker compose ps;
2. verifique se o endpoint usa a porta HTTP 4318;
3. consulte os logs do serviço e do collector;
4. confirme que OTEL_SERVICE_NAME corresponde ao nome buscado no Jaeger.

Evite adicionar IDs únicos ou dados pessoais como atributos. Eles aumentam cardinalidade e podem expor informações sensíveis.

Consulte a referência de observabilidade para traces e métricas personalizados.