Implementando Observabilidade com OpenTelemetry e Grafana: Guia Prático

Introdução

A observabilidade se tornou um requisito não opcional para aplicações modernas. Ela permite que equipes de desenvolvimento e operação entendam, em tempo real, o que está acontecendo dentro dos seus sistemas, identifiquem gargalos e reduzam o MTTR (Mean Time to Recovery). Neste artigo vamos construir, do zero, uma stack de observabilidade usando OpenTelemetry para instrumentação e Grafana Cloud como backend de métricas, logs e traces.

Por que Observabilidade é Crucial

1. Visibilidade completa – Métricas, logs e traces fornecem diferentes camadas de informação.
2. Detecção precoce – Alertas baseados em métricas evitam incidentes críticos.
3. Diagnóstico rápido – Traces mostram a jornada de uma requisição entre microserviços.
4. Custo-benefício – Ferramentas open source + SaaS reduzem a necessidade de infra própria.

Configurando OpenTelemetry no Python

Vamos começar instrumentando um pequeno serviço Flask. Primeiro, instale as dependências:

bash pip install flask opentelemetry-sdk opentelemetry-instrumentation-flask opentelemetry-exporter-otlp

Crie o arquivo instrumentation.py:

python

instrumentation.py

from opentelemetry import trace, metrics from opentelemetry.sdk.resources import Resource from opentelemetry.sdk.trace import TracerProvider from opentelemetry.sdk.metrics import MeterProvider from opentelemetry.sdk.trace.export import BatchSpanProcessor from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter from opentelemetry.exporter.otlp.proto.grpc.metric_exporter import OTLPMetricExporter

Defina recursos que identificam seu serviço

resource = Resource.create({"service.name": "demo-flask", "service.version": "1.0.0"})

Configura o tracer

trace.set_tracer_provider(TracerProvider(resource=resource)) tracer_provider = trace.get_tracer_provider() otlp_exporter = OTLPSpanExporter(endpoint="https://otlp-gateway.grafana.net:4317", headers={"Authorization": "Bearer $GRAFANA_API_KEY"}) span_processor = BatchSpanProcessor(otlp_exporter) tracer_provider.add_span_processor(span_processor)

Configura o meter (métricas)

metrics.set_meter_provider(MeterProvider(resource=resource)) metric_reader = PeriodicExportingMetricReader(OTLPMetricExporter(endpoint="https://otlp-gateway.grafana.net:4317", headers={"Authorization": "Bearer $GRAFANA_API_KEY"})) metrics.get_meter_provider().start_pipeline(metric_reader)

Nota: Substitua $GRAFANA_API_KEY por uma chave de API com permissões de ingestão OTLP.

Exportando Métricas e Traces para Grafana Cloud

Grafana Cloud aceita dados no formato OTLP (gRPC ou HTTP). A configuração acima já aponta para o endpoint público. Agora basta iniciar o Flask com a instrumentação automática:

bash opentelemetry-instrument python app.py

O comando opentelemetry-instrument injeta interceptores nas bibliotecas padrão (HTTP, SQL, etc.) e envia os dados para o Grafana.

Exemplos Práticos

1. Instrumentando um serviço Flask

Crie app.py:

python

app.py

from flask import Flask, request from opentelemetry.instrumentation.flask import FlaskInstrumentor

app = Flask(name) FlaskInstrumentor().instrument_app(app)

@app.route('/') def hello(): return "Olá, observabilidade!"

@app.route('/process') def process(): # Simula carga de trabalho import time, random time.sleep(random.uniform(0.1, 0.5)) return "Processado"

if name == 'main': app.run(host='0.0.0.0', port=5000)

Execute o serviço:

bash opentelemetry-instrument python app.py

Acesse http://localhost:5000/ e http://localhost:5000/process. Cada requisição gera um span que será enviado ao Grafana Tempo.

2. Consultando traces com Grafana Explore

1. Abra o Grafana Cloud e navegue até Explore.
2. Selecione o datasource Tempo.
3. Use a query service.name="demo-flask" para filtrar os traces do nosso serviço.
4. Clique em um trace para visualizar a timeline, durações e atributos personalizados.

3. Métricas customizadas

Podemos criar métricas de contagem de requisições usando o SDK:

python

metrics_example.py

from opentelemetry import metrics from opentelemetry.sdk.metrics import Counter

meter = metrics.get_meter(name) request_counter = meter.create_counter( name="http_requests_total", description="Total de requisições HTTP", unit="1", )

def record_request(method: str, status: int): request_counter.add(1, {"http.method": method, "http.status_code": str(status)})

Chame record_request dentro das rotas Flask para enviar contadores ao Grafana Prometheus.

Conclusão

Neste guia demonstramos como habilitar observabilidade end‑to‑end em uma aplicação Python usando OpenTelemetry e Grafana Cloud. Você aprendeu a:

• Instalar e configurar o SDK de OpenTelemetry;
• Exportar spans e métricas via OTLP;
• Visualizar traces no Grafana Tempo e métricas no Grafana Prometheus;
• Criar métricas customizadas para enriquecer seus dashboards.

Próximos passos recomendados:

1. Instrumentar bancos de dados (PostgreSQL, Redis) usando os pacotes opentelemetry-instrumentation-psycopg2, opentelemetry-instrumentation-redis.
2. Adicionar logs com o exporter OTLPLogExporter e enviá‑los ao Grafana Loki.
3. Automatizar a coleta usando agentes de sidecar (OpenTelemetry Collector) em ambientes Kubernetes.

Com esses componentes, sua equipe ganha a visibilidade necessária para operar sistemas resilientes e escaláveis.