Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Ingestão com o Vector

View as MarkdownEdit this pageReport an issueSet up docs MCP

Vector é um pipeline de dados de observabilidade de alto desempenho e independente de fornecedor. Ele é comumente usado para coletar, transformar e rotear logs e métricas de uma ampla variedade de fontes, sendo especialmente popular para ingestão de logs devido à sua flexibilidade e baixo consumo de recursos.

Ao usar o Vector com o ClickStack, os usuários são responsáveis por definir seus próprios esquemas. Esses esquemas podem seguir as convenções do OpenTelemetry, mas também podem ser totalmente personalizados, representando estruturas de eventos definidas pelo usuário. Na prática, a ingestão com Vector é mais comumente usada para logs, quando os usuários querem controle total sobre parsing e enriquecimento antes de os dados serem gravados no ClickHouse.

Este guia se concentra no onboarding de dados para o ClickStack usando Vector, tanto no ClickStack Open Source quanto no Managed ClickStack. Para simplificar, ele não aborda em profundidade as fontes nem a configuração do pipeline do Vector. Em vez disso, concentra-se em configurar o sink que grava dados no ClickHouse e em garantir que o esquema resultante seja compatível com o ClickStack.

O único requisito estrito do ClickStack, seja em uma implantação open source ou gerenciada, é que os dados incluam uma coluna de timestamp (ou um campo de tempo equivalente), que pode ser declarada ao configurar a fonte de dados na UI do ClickStack.

Enviando dados com o Vector


O guia a seguir pressupõe que você já criou um serviço Managed ClickStack e anotou suas credenciais de serviço. Caso ainda não tenha feito isso, siga o guia de Getting Started para Managed ClickStack até ser solicitado a configurar o Vector.

Criar um banco de dados e uma tabela

O Vector exige que uma tabela e um schema sejam definidos antes da ingestão de dados.

Primeiro, crie um banco de dados. Isso pode ser feito por meio do ClickHouse Cloud console.

No exemplo abaixo, usamos logs:

CREATE DATABASE IF NOT EXISTS logs

Crie uma tabela para seus dados. Ela deve corresponder ao esquema de saída dos seus dados. O exemplo abaixo pressupõe uma estrutura clássica do Nginx. Ajuste conforme seus dados, seguindo as boas práticas de esquema. Recomendamos fortemente que você se familiarize com o conceito de chaves primárias, selecionando sua chave primária com base nas diretrizes descritas aqui.

CREATE TABLE logs.nginx_logs
(
    `time_local` DateTime,
    `remote_addr` IPv4,
    `remote_user` LowCardinality(String),
    `request` String,
    `status` UInt16,
    `body_bytes_sent` UInt64,
    `http_referer` String,
    `http_user_agent` String,
    `http_x_forwarded_for` LowCardinality(String),
    `request_time` Float32,
    `upstream_response_time` Float32,
    `http_host` String
)
ENGINE = MergeTree
ORDER BY (toStartOfMinute(time_local), status, remote_addr)

Adicione o sink do ClickHouse à configuração do Vector

Modifique a configuração do Vector para incluir o sink do ClickHouse, atualizando o campo inputs para receber eventos dos pipelines existentes.

Esta configuração pressupõe que o pipeline upstream do Vector já preparou os dados para corresponder ao schema de destino do ClickHouse, ou seja, que os campos já foram analisados, nomeados corretamente e tipados de forma adequada para inserção. Consulte o exemplo de Nginx abaixo para ver uma ilustração completa de como analisar e normalizar linhas brutas de log em um schema adequado para o ClickStack.

sinks:
  clickhouse:
    type: clickhouse
    inputs:
      - your_input
    endpoint: "<CLICKHOUSE_ENDPOINT>"
    database: logs
    format: json_each_row
    table: nginx_logs
    skip_unknown_fields: true
    auth:
      strategy: "basic"
      user: "default"
      password: "<CLICKHOUSE_PASSWORD>"

Por padrão, recomendamos usar o formato json_each_row, que codifica cada evento como um único objeto JSON por linha. Esse é o formato padrão e recomendado para o ClickStack na ingestão de dados JSON e deve ser priorizado em relação a formatos alternativos, como objetos JSON codificados como strings.

O sink do ClickHouse também oferece suporte à codificação de stream Arrow (atualmente em beta). Ela pode oferecer maior vazão, mas traz restrições importantes: o banco de dados e a tabela devem ser estáticos, pois o esquema é obtido uma única vez na inicialização, e o roteamento dinâmico não é compatível. Por isso, a codificação Arrow é mais adequada para pipelines de ingestão fixos e bem definidos.

Recomendamos revisar as opções de configuração de sink disponíveis na documentação do Vector:

Criar uma fonte de dados

Crie uma fonte de dados de logs. Se ainda não houver nenhuma fonte de dados, você será solicitado a criar uma no primeiro login. Caso contrário, vá para Team Settings e adicione uma nova fonte de dados.

Criar fonte de dados - vector

A configuração acima pressupõe um esquema no estilo Nginx, com uma coluna time_local usada como timestamp. Sempre que possível, essa deve ser a coluna de timestamp declarada na chave primária. Essa coluna é obrigatória.

Também recomendamos atualizar o Default SELECT para definir explicitamente quais colunas são retornadas na visualização de logs. Se houver campos adicionais disponíveis, como nome do serviço, nível de log ou uma coluna de corpo, eles também poderão ser configurados. A coluna exibida como timestamp também pode ser substituída, caso seja diferente da coluna usada na chave primária da tabela e configurada acima.

No exemplo acima, não existe uma coluna Body nos dados. Em vez disso, ela é definida usando uma expressão SQL que reconstrói uma linha de log do Nginx a partir dos campos disponíveis.

Para ver outras opções possíveis, consulte a referência de configuração.

Explore os dados

Acesse a visualização de logs para explorar os dados e começar a usar o ClickStack.

Logs do Nginx no ClickStack

Exemplo de conjunto de dados com Vector

Para um exemplo mais completo, usamos a seguir um arquivo de log do Nginx.

O guia a seguir pressupõe que você já criou um serviço Managed ClickStack e registrou suas credenciais de serviço. Caso ainda não tenha feito isso, siga o guia de Getting Started para Managed ClickStack até chegar à etapa de configuração do Vector.

Instalando o Vector

Antes de prosseguir, certifique-se de que o Vector esteja instalado no sistema em que você pretende executar seu pipeline de ingestão. Siga o guia oficial de instalação do Vector para instalar um binário pré-compilado ou um pacote adequado ao seu ambiente:

Depois de instalar, verifique se o binário vector está disponível no seu path antes de continuar com as etapas de configuração abaixo.

Ele pode ser instalado na mesma instância que o OTel collector do ClickStack.

Siga as melhores práticas de arquitetura e segurança ao colocar o Vector em produção.

Baixe os dados de exemplo

Se quiser testar com um conjunto de dados de exemplo, baixe o exemplo do nginx a seguir.

curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/access.log

Crie um banco de dados e uma tabela

O Vector exige que uma tabela e um schema sejam definidos antes da ingestão de dados.

Primeiro, crie um banco de dados. Isso pode ser feito no ClickHouse Cloud console.

Crie um banco de dados logs:

CREATE DATABASE IF NOT EXISTS logs

Crie uma tabela para os seus dados.

CREATE TABLE logs.nginx_logs
(
    `time_local` DateTime,
    `remote_addr` IPv4,
    `remote_user` LowCardinality(String),
    `request` String,
    `status` UInt16,
    `body_bytes_sent` UInt64,
    `http_referer` String,
    `http_user_agent` String,
    `http_x_forwarded_for` LowCardinality(String),
    `request_time` Float32,
    `upstream_response_time` Float32,
    `http_host` String
)
ENGINE = MergeTree
ORDER BY (toStartOfMinute(time_local), status, remote_addr)

Copie a configuração do Vector

Copie a configuração do Vector e crie um arquivo nginx.yaml, definindo CLICKHOUSE_ENDPOINT e CLICKHOUSE_PASSWORD.

data_dir: ./.vector-data
sources:
  nginx_logs:
    type: file
    include:
      - access.log
    read_from: beginning

transforms:
  decode_json:
    type: remap
    inputs:
      - nginx_logs
    source: |
      . = parse_json!(to_string!(.message))
      ts = parse_timestamp!(.time_local, format: "%d/%b/%Y:%H:%M:%S %z")
      # ClickHouse-friendly DateTime format
      .time_local = format_timestamp!(ts, format: "%F %T")

sinks:
  clickhouse:
    type: clickhouse
    inputs:
      - decode_json
    endpoint: "<CLICKHOUSE_ENDPOINT>"
    database: logs
    format: json_each_row
    table: nginx_logs
    skip_unknown_fields: true
    auth:
      strategy: "basic"
      user: "default"
      password: "<CLICKHOUSE_PASSWORD>"

Inicie o Vector

Inicie o Vector com o comando a seguir, criando primeiro o diretório de dados para registrar os offsets do arquivo.

mkdir ./.vector-data
vector --config nginx.yaml

Criar uma fonte de dados

Crie uma fonte de dados de logs. Se não houver nenhuma fonte de dados, você será solicitado a criar uma no primeiro acesso. Caso contrário, vá para Configurações da equipe e adicione uma nova fonte de dados.

Criar fonte de dados - vector

A configuração pressupõe o schema do Nginx, com uma coluna time_local usada como timestamp. Essa é a coluna de timestamp declarada na chave primária. Essa coluna é obrigatória.

Também especificamos a seleção padrão como time_local, remote_addr, status, request, que define quais colunas são retornadas na visualização de logs.

No exemplo acima, não há uma coluna Body nos dados. Em vez disso, ela é definida como a expressão SQL:

concat(
  remote_addr, ' ',
  remote_user, ' ',
  '[', formatDateTime(time_local, '%d/%b/%Y:%H:%M:%S %z'), '] ',
  '"', request, '" ',
  toString(status), ' ',
  toString(body_bytes_sent), ' ',
  '"', http_referer, '" ',
  '"', http_user_agent, '" ',
  '"', http_x_forwarded_for, '" ',
  toString(request_time), ' ',
  toString(upstream_response_time), ' ',
  '"', http_host, '"'
)

Isso recompõe a linha de log com base nos campos estruturados.

Para outras opções, consulte a referência de configuração.

Explore os dados

Navegue até a tela de pesquisa em 20 de outubro de 2025 para explorar os dados e começar a usar o ClickStack.

Interface do HyperDX
Navigation