Enviando OpenTelemetry para o ClickStack com Odigos

Odigos é um plano de controle de instrumentação para Kubernetes e VMs que instrumenta aplicações diretamente no kernel usando eBPF. Como a coleta é executada no kernel, a sobrecarga nas aplicações permanece baixa, enquanto a visibilidade continua alta. Você obtém traces, métricas, logs e perfis do OpenTelemetry prontos para produção sem precisar adicionar novos agentes ao código da aplicação nem esperar por atualizações de bibliotecas em cada serviço.

Essa camada de eBPF é o que torna possível uma telemetria detalhada e consistente em escala. O Odigos pode ativar e desativar automaticamente uma instrumentação mais aprofundada quando necessário para ajudar na depuração ou na solução de problemas:

• Contexto em nível de código — atributos vinculados a funções e ao comportamento em tempo de execução
• Tráfego HTTP — requisições e respostas entre seus serviços
• Sistemas de mensageria — payloads e mensagens do Kafka e de brokers semelhantes
• Detalhes dos erros — stack traces quando algo falha
• Instrumentação personalizada — amplie a cobertura onde a instrumentação automática não alcança, sem exigir alterações no código nem reinicializações

Nos bastidores, o Odigos cria e gerencia um pipeline OpenTelemetry completo para seu cluster: coletores que escalam com a carga, roteamento para os backends que você escolher e lógica de pipeline que você controla pela UI. Defina sampling para gerenciar o volume, mascaramento de PII para manter dados sensíveis fora das exportações e regras OTTL para filtrar, transformar ou enriquecer a telemetria antes que ela saia do cluster.

Implantar o OpenTelemetry em muitos serviços costuma ser demorado e oferece apenas visibilidade superficial das aplicações. O Odigos cuida da instrumentação com eBPF para uma telemetria mais profunda e da operação dos collectors no Kubernetes; o ClickStack fornece armazenamento no ClickHouse e a UI do HyperDX para consultar a telemetria em escala.

• ClickStack instalado e acessível a partir do seu cluster Kubernetes. Consulte Primeiros passos com o ClickStack open source ou Primeiros passos com o ClickStack gerenciado.
• Seu endpoint HTTP OTLP do ClickStack (porta 4318) e o valor de autenticação que o Odigos passará no header Authorization. No ClickStack open source, isso corresponde à chave de ingestão da API em Team Settings → API Keys na UI do HyperDX. No ClickStack gerenciado, isso corresponde ao OTLP_AUTH_TOKEN que você definiu ao iniciar seu próprio ClickStack collector standalone.
• Um cluster Kubernetes (nós Linux com kernel 4.18 ou posterior para instrumentação eBPF)
• Helm, kubectl e credenciais do cluster para instalar no espaço de nomes odigos-system
• Um token on-prem do Odigos Enterprise — entre em contato com a equipe do Odigos para obter acesso

export ODIGOS_ONPREM_TOKEN="<your-enterprise-token>"

helm repo add odigos https://odigos-io.github.io/odigos/
helm repo update

helm upgrade --install odigos odigos/odigos \
  --namespace odigos-system \
  --create-namespace \
  --set onPremToken=$ODIGOS_ONPREM_TOKEN

kubectl get pods -n odigos-system

kubectl port-forward svc/ui -n odigos-system 3000:3000

Se você exportar diretamente para o ClickHouse com o destino ClickHouse nativo do Odigos (em vez de OTLP HTTP para o ClickStack), habilite o normalizador de logs do HyperDX (HYPERDX_LOG_NORMALIZER: true). Ele faz o parse do conteúdo JSON dos logs e normaliza os atributos para melhorar as consultas na UI do ClickStack.

Quando o ClickHouse estiver diretamente acessível a partir do seu cluster, você poderá usar o destino ClickHouse nativo do Odigos em vez de OTLP HTTP. Configure o endpoint do ClickHouse, o nome do banco de dados e as opções de esquema na UI ou com um manifesto — consulte destino ClickHouse do Odigos.

• Esquema de produção: defina CLICKHOUSE_CREATE_SCHEME como false e aplique sua própria DDL.
• TLS / autenticação: use CLICKHOUSE_TLS_ENABLED, CLICKHOUSE_USERNAME e um Secret do Kubernetes para a senha.

OTLP HTTP (ClickStack)

apiVersion: odigos.io/v1alpha1
kind: Destination
metadata:
  name: clickstack
  namespace: odigos-system
spec:
  type: otlphttp
  destinationName: otlphttp
  signals:
    - TRACES
    - METRICS
    - LOGS
  data:
    OTLP_HTTP_ENDPOINT: 'http://clickstack.example.com:4318'
    # Chave de ingestão de API para o ClickStack open source, ou OTLP_AUTH_TOKEN para o Managed ClickStack
    OTLP_HTTP_HEADERS: 'Authorization:<YOUR_AUTHORIZATION_VALUE>'

ClickHouse (direto)

apiVersion: odigos.io/v1alpha1
kind: Destination
metadata:
  name: clickhouse
  namespace: odigos-system
spec:
  type: clickhouse
  destinationName: clickhouse
  signals:
    - TRACES
    - METRICS
    - LOGS
  data:
    CLICKHOUSE_ENDPOINT: 'http://clickstack.example.com:8123'
    CLICKHOUSE_DATABASE_NAME: 'otel'
    CLICKHOUSE_CREATE_SCHEME: 'true'

Aplique o manifesto:

kubectl apply -f destination.yaml

O Odigos VM Agent instrumenta processos Linux, serviços do systemd e/ou contêineres Docker usando eBPF. A telemetria é exportada para os mesmos destinos do Odigos baseado em cluster, incluindo o ClickStack via OTLP HTTP.

O VM Agent faz parte do Odigos Pro. Consulte a visão geral do VM Agent para ver a configuração, as fontes e a configuração de destinos.

Odigos Central é um plano de controle centralizado para gerenciar a instrumentação, os destinos e a configuração de pipelines em vários clusters Kubernetes a partir de uma única UI, em vez de configurar cada cluster separadamente.

O Odigos Central está disponível no Odigos Enterprise. Consulte a visão geral do Odigos Central para gerenciamento de múltiplos clusters, SSO e regras unificadas de sampling.

• Explore traces nos serviços instrumentados no ClickStack
• Crie dashboards com as métricas exportadas pelo Odigos
• Ajuste o esquema e o TTL do ClickHouse de acordo com sua retenção e seus padrões de consulta

• Instalação do Odigos Enterprise
• Destino ClickHouse do Odigos
• Visão geral do Odigos VM Agent
• Visão geral do Odigos Central
• Chega de adivinhar em produção: tracing com fidelidade total em escala com ClickHouse e Odigos
• Primeiros passos com o ClickStack de código aberto