Acesse o painel da sua conta

Não tem uma conta? Registrar

Entrar em contato

Visite também nosso site craftxp.com.br

  • img
  • img
  • img
  • img
  • img
  • img

Entre em contato

OpenTelemetry na Prática: Guia Completo de Observabilidade com Rastreamento, Métricas e Logs

OpenTelemetry na Prática: Guia Completo de Observabilidade com Rastreamento, Métricas e Logs

O que é OpenTelemetry?

OpenTelemetry (OTel) é um conjunto de APIs, SDKs, bibliotecas e integrações de código aberto, criado pela Cloud Native Computing Foundation (CNCF), que padroniza a coleta e exportação de dados de telemetria — traces, métricas e logs — de aplicações. Seu objetivo é fornecer uma forma única, independente de fornecedor, para instrumentar softwares e enviar dados de observabilidade para qualquer plataforma de análise.

Antes do OpenTelemetry, cada ferramenta de observabilidade (Datadog, New Relic, Jaeger, Prometheus) exigia sua própria instrumentação proprietária. O resultado era vendor lock-in, SDKs conflitantes e uma manutenção dolorosa. O OTel unifica tudo isso em uma única especificação aberta, suportada por dezenas de fornecedores.

Os Três Pilares da Observabilidade

O OpenTelemetry abrange os três pilares fundamentais para entender o comportamento de sistemas em produção:

1. Rastreamento Distribuído (Distributed Tracing)

O tracing permite acompanhar uma requisição à medida que ela atravessa múltiplos serviços — de um gateway API até bancos de dados, filas de mensagens e microsserviços internos. Cada requisição é representada por um trace, composto por spans (unidades de trabalho individuais).

  • Trace: O caminho completo de uma requisição pelo sistema distribuído.
  • Span: Uma operação individual dentro de um trace (ex: consulta ao banco, chamada HTTP, processamento de fila).
  • Contexto de Propagação: Mecanismo que carrega o ID do trace entre serviços via headers HTTP ou mensagens.

Com o tracing, você consegue responder perguntas como: "Qual microsserviço está causando lentidão na minha aplicação?" ou "Qual query ao banco de dados está consumindo mais tempo?"

2. Métricas (Metrics)

Métricas são medições numéricas coletadas ao longo do tempo — uso de CPU, consumo de memória, latência de requisições, taxa de erros, número de requisições por segundo. O OpenTelemetry suporta três tipos principais:

  • Counter: Valor acumulativo que só aumenta (ex: total de requisições).
  • Gauge: Valor que pode aumentar ou diminuir (ex: uso de memória atual).
  • Histogram: Distribuição estatística de valores (ex: latência de requisições em percentis p50, p95, p99).

As métricas são essenciais para alertas automatizados e dashboards de visão geral do sistema.

3. Logs

Logs são registros textuais com timestamp que documentam eventos específicos — erros, avisos, informações de depuração. O OTel padroniza a estrutura dos logs com campos como severity, trace_id e span_id, permitindo correlacionar logs diretamente com traces e métricas.

A grande inovação do OTel é permitir a correlação entre os três pilares: você pode olhar uma métrica de alta latência, clicar no trace correspondente e ver os logs daquele span específico — tudo integrado.

Arquitetura do OpenTelemetry

A arquitetura do OTel é composta por componentes modulares que podem ser implantados de forma flexível:

  1. Instrumentação (Instrumentation): Bibliotecas específicas para cada linguagem (Java, Python, Go, Node.js, .NET, Ruby, PHP, Rust, C++) que capturam automaticamente dados de frameworks populares (Express, Spring Boot, Django, gRPC, etc.).
  2. OTel SDK: API de alto nível que permite instrumentação manual, criação de spans personalizados, registro de atributos e eventos.
  3. OTel Collector: Componente independente (sidecar, agente ou gateway) que recebe, processa e exporta dados de telemetria. Suporta recepção via OTLP (OpenTelemetry Protocol), processamento (batching, filtragem, sampling) e exportação para múltiplos backends.
  4. Exporters: Conectores que enviam dados para plataformas de observabilidade: Jaeger, Zipkin, Prometheus, Datadog, New Relic, Grafana Tempo, AWS X-Ray, Azure Monitor, GCP Cloud Trace, entre outros.

Implementação Prática em Node.js com Express

Vamos implementar tracing em uma aplicação Express usando a instrumentação automática do OpenTelemetry:

import { NodeSDK } from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { Resource } from '@opentelemetry/resources';
import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions';

// Configurar o exportador OTLP
const traceExporter = new OTLPTraceExporter({
  url: 'http://otel-collector:4318/v1/traces',
});

// Configurar o SDK
const sdk = new NodeSDK({
  resource: new Resource({
    [SemanticResourceAttributes.SERVICE_NAME]: 'meu-servico-express',
    [SemanticResourceAttributes.SERVICE_VERSION]: '1.0.0',
  }),
  traceExporter,
  instrumentations: [getNodeAutoInstrumentations()],
});

// Iniciar o SDK (deve ser feito antes de qualquer import de framework)
sdk.start();

// Process.env.OTEL_RESOURCE_ATTRIBUTES tambem pode ser usado

// Graceful shutdown
process.on('SIGTERM', () => {
  sdk.shutdown()
    .then(() => console.log('Tracing encerrado'))
    .catch((err) => console.error('Erro ao encerrar tracing', err))
    .finally(() => process.exit(0));
});

Com essa configuração, todas as requisições HTTP, chamadas a banco de dados, operações de cache Redis e consultas gRPC serão automaticamente rastreadas e enviadas ao OTel Collector.

OTel Collector: O Cérebro da Arquitetura

O OpenTelemetry Collector é um componente fundamental que atua como intermediário entre sua aplicação e as plataformas de análise. Ele oferece:

  • Batching e Retry: Agrupa spans e métricas para envio eficiente, com retry automático em falhas.
  • Sampling: Coleta apenas uma amostra representativa dos traces (ex: 10% das requisições), reduzindo custos e volume de dados.
  • Processamento e Filtragem: Remove atributos sensíveis (senhas, tokens), enriquece dados com metadados do ambiente.
  • Múltiplos Destinos: Envia para Prometheus + Jaeger + Datadog simultaneamente, sem modificar a aplicação.

Exemplo de configuração do Collector (config.yaml):

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:
    timeout: 1s
    send_batch_size: 1024
  memory_limiter:
    check_interval: 1s
    limit_mib: 512
  attributes:
    actions:
      - key: environment
        value: production
        action: upsert

exporters:
  prometheus:
    endpoint: 0.0.0.0:8889
  otlp:
    endpoint: jaeger:4317
    tls:
      insecure: true
  debug:
    verbosity: detailed

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter, batch]
      exporters: [otlp, debug]
    metrics:
      receivers: [otlp]
      processors: [memory_limiter, batch]
      exporters: [prometheus, debug]

Python com Flask e OpenTelemetry

Para aplicações Python com Flask ou Django, a instrumentação é igualmente simples:

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.instrumentation.flask import FlaskInstrumentor
from opentelemetry.instrumentation.requests import RequestsInstrumentor
from flask import Flask

# Configurar o provider de tracing
provider = TracerProvider()
processor = BatchSpanProcessor(OTLPSpanExporter(
    endpoint="http://otel-collector:4318/v1/traces"
))
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)

# Instrumentar automaticamente Flask e requests
app = Flask(__name__)
FlaskInstrumentor().instrument_app(app)
RequestsInstrumentor().instrument()

tracer = trace.get_tracer(__name__)

@app.route('/api/pedidos')
def listar_pedidos():
    # Criar span manual para lógica de negócio
    with tracer.start_as_current_span("consultar-banco") as span:
        span.set_attribute("db.sistema", "PostgreSQL")
        span.set_attribute("db.consulta", "SELECT * FROM pedidos")
        # Sua logica de consulta aqui
        pedidos = buscar_pedidos_no_banco()
    return {"pedidos": pedidos}

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000)

Métricas Customizadas

Além das métricas automáticas, você pode criar métricas customizadas para monitorar regras de negócio específicas:

from opentelemetry import metrics
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter

# Configurar o provider de metrics
reader = PeriodicExportingMetricReader(
    OTLPMetricExporter(endpoint="http://otel-collector:4318/v1/metrics")
)
provider = MeterProvider(metric_readers=[reader])
metrics.set_meter_provider(provider)
meter = metrics.get_meter("meu-servico", "1.0.0")

# Contador de pedidos criados
pedidos_criados = meter.create_counter(
    "pedidos.criados.total",
    description="Total de pedidos criados",
    unit="pedidos",
)

# Histograma de valor de pedidos
valor_pedido = meter.create_histogram(
    "pedidos.valor",
    description="Distribuicao do valor dos pedidos",
    unit="BRL",
)

# Gauge de usuarios online
usuarios_online = meter.create_up_down_counter(
    "usuarios.online",
    description="Numero de usuarios online no momento",
)

# Em uso:
pedidos_criados.add(1, {"metodo_pagamento": "credito"})
valor_pedido.record(299.90, {"categoria": "eletronicos"})

Integração com o Ecossistema CNCF

O OpenTelemetry se integra nativamente com outras ferramentas da Cloud Native Computing Foundation:

  • Prometheus: Exporte métricas OTel para o Prometheus via OTel Collector e visualize no Grafana.
  • Jaeger: Receba traces via OTLP ou Jaeger Proto. Visualize árvores de spans, latências e dependências entre serviços.
  • Grafana Tempo: Armazenamento de traces escalável, com busca por serviceName, duration e tags.
  • Kubernetes: Implante o OTel Collector como DaemonSet em cada nó ou como Deployment centralizado.
  • Kiali (Service Mesh): Visualize traces em malhas Istio/Linkerd integradas ao OTel.

Boas Práticas e Pitfalls

Para uma implementação bem-sucedida de observabilidade com OTel, siga estas recomendações:

  1. Comece pela instrumentação automática: As bibliotecas auto-instrumentadoras cobrem 80% dos casos sem esforço manual.
  2. Use sampling inteligente: Em produção, colete 100% dos traces de erro e uma amostra (5-10%) dos traces bem-sucedidos. Configure o head_sampling no SDK ou tail_sampling no Collector.
  3. Nomeie spans de forma consistente: Use semântica padronizada (HTTP.method + route, db.system + db.operation).
  4. Adicione atributos de negócio: Enriqueça spans com IDs de usuário, IDs de pedido, versão do deploy para correlação com eventos reais.
  5. Não insira dados sensíveis: Nunca coloque senhas, tokens, CPF ou dados pessoais em atributos de spans.
  6. Monitore o próprio OTel: O Collector expõe métricas internas sobre spans processados, erros de exportação e uso de memória.
  7. Configure alertas baseados em SLOs: Use as métricas de latência e erro exportadas pelo OTel para disparar alertas quando SLOs forem violados.

Conclusão

O OpenTelemetry está rapidamente se tornando o padrão universal para observabilidade em sistemas modernos. Adotado por gigantes como Google, Microsoft, AWS, Datadog e New Relic, o OTel resolve o problema crônico de fragmentação de ferramentas de monitoramento.

Com uma única instrumentação, você envia traces, métricas e logs para qualquer backend — ou para vários simultaneamente — sem vendor lock-in. A curva de aprendizado é pequena, o retorno é imediato, e o ecossistema só cresce.

Se você ainda não começou a implementar observabilidade na sua aplicação, o OpenTelemetry é o ponto de partida ideal. Comece hoje com instrumentação automática, adicione o Collector, e conecte ao Jaeger ou Grafana Tempo. Seus futuros debugs agradecerão!

Craft XP
Craft XP