OpenTelemetry Collector¶

O OTel Collector é um componente proxy que recebe, processa e exporta dados de telemetria (métricas, logs e traces). Ele funciona como uma pipeline de dados baseada em uma arquitetura de plugins.

1. Instalação (download e preparação)¶

Existem várias formas de instalar o Collector, mas para rodar nativamente via systemd, o método mais direto é baixando o binário oficial tarball (ou pacotes .deb/.rpm). Abaixo está o passo a passo baixando a versão Contrib (que inclui a maioria dos plugins de infraestrutura como o host_metrics).

OTEL_VERSION="0.156.0"

# 2. Baixa o binário
curl -L -O "https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v${OTEL_VERSION}/otelcol-contrib_${OTEL_VERSION}_linux_amd64.tar.gz"

# 3. Extrai o conteúdo
tar -xvf otelcol-contrib_${OTEL_VERSION}_linux_amd64.tar.gz

# 4. Move o binário para o diretório de executáveis do sistema
sudo mv otelcol-contrib /usr/local/bin/

# 5. Cria o diretório de configuração padrão
sudo mkdir -p /etc/otelcol

2. Modelos de arquitetura de configuração¶

Dependendo de onde o Collector está rodando, ele assumirá o papel de Agent (instalado no host da aplicação) ou de Gateway (Centralizador).

Cenário A: coletores em hosts (Agents)¶

Esta configuração roda localmente nas suas máquinas/servidores. O objetivo dela é coletar dados locais da infraestrutura e despachar para o coletor central o mais rápido possível.

receivers:
  host_metrics:
    collection_interval: 60s
    scrapers:
      cpu:
      memory:
      disk:
      network:
      load:

processors:
  batch:
    timeout: 10s
    send_batch_size: 1024
  resource:
    attributes:
      - key: service.name
        value: "so"
        action: insert
      - key: host.name
        value: "melville"
        action: insert

exporters:
  otlp_grpc:
    endpoint: "192.168.15.15:4317"
    tls:
      insecure: true

service:
  pipelines:
    metrics:
      receivers: [host_metrics]
      processors: [resource, batch]
      exporters: [otlp_grpc]

Explicação dos componentes do agent:¶

• Receivers (Receptores): são a porta de entrada. O scraper host_metrics roda a cada 60 segundos coletando métricas de hardware diretamente do Sistema Operacional. Eles padronizam dados de diversas origens para o formato interno do OTel.
• Processors (Processadores): manipulam e limpam os dados. O batch agrupa registros para economizar overhead de rede (enviando pacotes a cada 10s ou 1024 registros).
• Resource: o "RG" do seu dado. O processador resource injeta chaves fixas como service.name: "so" e host.name: "melville" para que você saiba exatamente de qual servidor veio aquela métrica quando for olhar no Grafana.
• Exporters (Exportadores): a ponta final. No Agent, usa-se apenas um exporter (otlp_grpc) apontando para o IP centralizado. Isso garante abstração (o host não precisa saber onde os dados são salvos) e economiza CPU/Rede da máquina cliente.

Cenário B: coletor centralizado (Gateway)¶

Esta configuração roda em um servidor dedicado (192.168.15.15), atuando como um Gateway. Ele funciona como um funil de tráfego: recebe a telemetria de todos os agentes espalhados na rede, consolida as pipelines e distribui inteligentemente para os destinos corretos.

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

  hostmetrics:
    collection_interval: 10s
    scrapers:
      cpu:
      memory:
      load:
      disk:
      network:

processors:
  batch:
  resource:
    attributes:
      - key: service.name
        value: "collector-metrics"
        action: insert
      - key: host.name
        value: "metrics"
        action: insert

exporters:
  otlphttp/metrics:
    endpoint: "http://localhost:8428/opentelemetry"
    tls:
      insecure: true

  otlphttp/logs:
    endpoint: "http://localhost:9428/insert/opentelemetry"
    tls:
      insecure: true

  otlphttp/traces:
    endpoint: "http://localhost:3428/insert/opentelemetry"
    tls:
      insecure: true

service:
  pipelines:
    metrics:
      receivers: [otlp, hostmetrics]
      processors: [resource, batch]
      exporters: [otlphttp/metrics]

    logs:
      receivers: [otlp]
      processors: []
      exporters: [otlphttp/logs]

    traces:
      receivers: [otlp]
      processors: []
      exporters: [otlphttp/traces]

O que muda na arquitetura centralizada?¶

• Escuta Aberta (0.0.0.0): o receiver otlp do centralizador abre as portas 4317 (gRPC) e 4318 (HTTP) para toda a rede. Ele se torna o endpoint unificado para onde todos os Agents vão apontar.
• Multi-pipeline: O centralizador cria 3 pipelines distintas (metrics, logs, traces). O OTel Collector sabe discernir o tipo de dado recebido na porta OTLP e separa o fluxo nativamente.
• Roteamento por Sub-tipos (Sintaxe tipo/nome): como bancos de dados de métricas (ex: VictoriaMetrics na porta 8428), logs (ex: Loki na porta 9428) e traces (ex: Tempo na porta 3428) funcionam de formas completamente diferentes, usamos múltiplos exporters especializados para pulverizar os dados nos lugares certos.
• Auto-Monitoramento: centralizador usa seu próprio hostmetrics para monitorar a saúde do servidor Gateway, marcando esses dados com o nome "collector-metrics".

⚠️ Nota de Performance: A ordem dos processadores dentro de service.pipelines importa. Coloque o batch sempre como o último processador antes dos exporters para garantir que ele agrupe os dados já devidamente modificados pelos processadores anteriores.

3. Gerenciamento e execução com systemd¶

Para garantir que o OpenTelemetry Collector rode continuamente em segundo plano e seja reiniciado automaticamente em caso de falhas, configure-o como um serviço do sistema.

Criação do arquivo de serviço¶

Crie o arquivo de configuração em /etc/systemd/system/otelcol.service:

[Unit]
Description=OpenTelemetry Collector Contrib
After=network.target

[Service]
Type=simple
User=root
Group=root
ExecStart=/usr/local/bin/otelcol-contrib --config=/etc/otelcol/config.yaml
Restart=always
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

Anatomia do serviço (O que cada linha faz?)¶

-After=network.target: garante que o OTel Collector só vai iniciar depois que a stack de rede do SO estiver ativa, prevenindo erros de portas indisponíveis no boot. - User / Group**: define os privilégios de execução. Em produção restrita, recomenda-se criar um usuário dedicado e sem privilégios administrativos (ex: User=otelcol). - **ExecStart: o comando exato que inicia o Collector, apontando o parâmetro --config para o arquivo yaml que criamos. - Restart=always: se o processo do Collector morrer por falta de memória (OOM) ou crash estrutural, o systemd vai levantá-lo novamente de forma automática. - LimitNOFILE=65536: eleva o limite de File Descriptors (arquivos abertos). Como o Collector lida com milhares de conexões HTTP/gRPC simultâneas dos clientes, isso previne o erro Too many open files. - WantedBy=multi-user.target: garante que o Collector iniciará automaticamente sempre que o servidor ligar.

4. Comandos úteis de operação¶

Após salvar o arquivo de configuração em /etc/otelcol/config.yaml e o arquivo do serviço no systemd, utilize os comandos abaixo para operar o ecossistema:

# 1. Recarrega o systemd para reconhecer o novo arquivo .service
sudo systemctl daemon-reload

# 2. Ativa o serviço para iniciar automaticamente junto com o boot do sistema
sudo systemctl enable otelcol

# 3. Inicia o serviço imediatamente
sudo systemctl start otelcol

# 4. Verifica o status de execução atual
sudo systemctl status otelcol

# 5. Acompanha os logs de telemetria e erros em tempo real (Troubleshooting)
sudo journalctl -u otelcol -f

Links úteis:

• Repositório Oficial de Releases do OTel
• Manual do systemd.service