Ingestão com OpenTelemetry

Todos os dados são enviados ao ClickStack por meio de uma instância do OpenTelemetry (OTel) collector, que atua como ponto de entrada principal para logs, métricas, traces e dados de sessão. Recomendamos usar a distribuição oficial do ClickStack do collector para essa instância.

Os usuários enviam dados para esse collector a partir de SDKs de linguagem ou por meio de agentes de coleta de dados que coletam métricas e logs de infraestrutura (como OTel collectors na função de agent ou outras tecnologias, como Fluentd ou Vector). Para equipes que desejam um pipeline OpenTelemetry gerenciado, o Bindplane oferece uma solução nativa de OpenTelemetry com um destino nativo do ClickStack, simplificando a coleta, o processamento e o roteamento da telemetria.

Enviando dados de OpenTelemetry

Instalando o ClickStack OpenTelemetry collector

Para enviar dados ao Managed ClickStack, um OTel collector deve ser implantado em uma função de gateway. Instrumentação compatível com OTel enviará eventos para esse collector via OTLP por HTTP ou gRPC.

Para mais detalhes, consulte "Implantando o collector".

Enviando dados para o collector

Para enviar dados ao Managed ClickStack, aponte sua instrumentação OpenTelemetry para os seguintes endpoints disponibilizados pelo OpenTelemetry collector:

HTTP (OTLP): http://localhost:4318
gRPC (OTLP): localhost:4317

Para SDKs de linguagem e bibliotecas de telemetria compatíveis com OpenTelemetry, você pode simplesmente definir a variável de ambiente OTEL_EXPORTER_OTLP_ENDPOINT na sua aplicação:

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

Se estiver implantando uma distribuição contrib do OTel collector na função de agent, você pode usar o exporter OTLP para enviar dados ao ClickStack collector. Um exemplo de config de agent que consome este arquivo de log estruturado é mostrado abaixo.

# clickhouse-agent-config.yaml
receivers:
  filelog:
    include:
      - /opt/data/logs/access-structured.log
    start_at: beginning
    operators:
      - type: json_parser
        timestamp:
          parse_from: attributes.time_local
          layout: '%Y-%m-%d %H:%M:%S'
exporters:
  # HTTP setup
  otlphttp/hdx:
    endpoint: 'http://localhost:4318'
    compression: gzip
 
  # gRPC setup (alternative)
  otlp/hdx:
    endpoint: 'localhost:4317'
    compression: gzip
processors:
  batch:
    timeout: 5s
    send_batch_size: 10000
service:
  telemetry:
    metrics:
      address: 0.0.0.0:9888 # Modified as 2 collectors running on same host
  pipelines:
    logs:
      receivers: [filelog]
      processors: [batch]
      exporters: [otlphttp/hdx]

O ClickStack OpenTelemetry collector está incluído na maioria das distribuições do ClickStack, incluindo:

Instalando o ClickStack OpenTelemetry collector

O ClickStack OTel collector também pode ser implantado de forma independente, sem depender dos outros componentes da stack.

Se você estiver usando a distribuição HyperDX-only, será responsável por enviar os dados ao ClickHouse por conta própria. Isso pode ser feito das seguintes formas:

Executando seu próprio OpenTelemetry collector e apontando-o para o ClickHouse — veja abaixo.
Enviando diretamente para o ClickHouse usando ferramentas alternativas, como Vector, Fluentd etc., ou até mesmo a distribuição padrão do collector contrib do OTel.

Para mais detalhes, consulte "Implantando o collector".

Enviando dados para o collector

Para enviar dados ao ClickStack, aponte sua instrumentação OpenTelemetry para os seguintes endpoints disponibilizados pelo OpenTelemetry collector:

HTTP (OTLP): http://localhost:4318
gRPC (OTLP): localhost:4317

Para SDKs de linguagem e bibliotecas de telemetria compatíveis com OpenTelemetry, você pode simplesmente definir a variável de ambiente OTEL_EXPORTER_OTLP_ENDPOINT na sua aplicação:

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

Além disso, é necessário um header de autorização contendo a chave de ingestão da API. Você pode encontrar a chave no app HyperDX em Team Settings → API Keys.

Para SDKs de linguagem, isso pode ser definido em uma função init ou por meio da variável de ambiente OTEL_EXPORTER_OTLP_HEADERS, por exemplo:

OTEL_EXPORTER_OTLP_HEADERS='authorization=<YOUR_INGESTION_API_KEY>'

Da mesma forma, os agents também devem incluir esse cabeçalho de autorização em qualquer comunicação OTLP. Por exemplo, ao implantar uma distribuição contrib do OTel collector no papel de agent, eles podem usar o exportador OTLP. Abaixo, é mostrada uma configuração de exemplo de agent que consome este arquivo de log estruturado. Observe que é necessário especificar uma chave de autorização — consulte <YOUR_API_INGESTION_KEY>.

# clickhouse-agent-config.yaml
receivers:
  filelog:
    include:
      - /opt/data/logs/access-structured.log
    start_at: beginning
    operators:
      - type: json_parser
        timestamp:
          parse_from: attributes.time_local
          layout: '%Y-%m-%d %H:%M:%S'
exporters:
  # HTTP setup
  otlphttp/hdx:
    endpoint: 'http://localhost:4318'
    headers:
      authorization: <YOUR_API_INGESTION_KEY>
    compression: gzip
 
  # gRPC setup (alternative)
  otlp/hdx:
    endpoint: 'localhost:4317'
    headers:
      authorization: <YOUR_API_INGESTION_KEY>
    compression: gzip
processors:
  batch:
    timeout: 5s
    send_batch_size: 10000
service:
  telemetry:
    metrics:
      address: 0.0.0.0:9888 # Modified as 2 collectors running on same host
  pipelines:
    logs:
      receivers: [filelog]
      processors: [batch]
      exporters: [otlphttp/hdx]