Primeiros passos no Managed ClickStack

No seu serviço do ClickHouse Cloud, inicie o ClickStack. Na página Getting Started do ClickStack, selecione Iniciar ingestão.

Na página Escolher uma fonte de ingestão, selecione OpenTelemetry.

CREATE USER `clickstack-ingest` IDENTIFIED WITH sha256_password BY '<password>';
GRANT SELECT, INSERT, CREATE DATABASE, CREATE TABLE, CREATE VIEW ON default.* TO `clickstack-ingest`;

docker run -e CLICKHOUSE_ENDPOINT="https://<host>:8443" \
    -e CLICKHOUSE_USER="default" \
    -e CLICKHOUSE_PASSWORD="<your_password_here>" \
    -p 4317:4317 -p 4318:4318 \
    clickhouse/clickstack-otel-collector:latest

receivers:
  otlp/hyperdx:
    protocols:
      grpc:
        include_metadata: true
        endpoint: "0.0.0.0:4317"
      http:
        cors:
          allowed_origins: ["*"]
          allowed_headers: ["*"]
        include_metadata: true
        endpoint: "0.0.0.0:4318"
processors:
  batch:
  memory_limiter:
    # 80% of maximum memory up to 2G, adjust for low memory environments
    limit_mib: 1500
    # 25% of limit up to 2G, adjust for low memory environments
    spike_limit_mib: 512
    check_interval: 5s
connectors:
  routing/logs:
    default_pipelines: [logs/out-default]
    error_mode: ignore
    table:
      - context: log
        statement: route() where IsMatch(attributes["rr-web.event"], ".*")
        pipelines: [logs/out-rrweb]
exporters:
  clickhouse/rrweb:
    database: default
    endpoint: <clickhouse_cloud_endpoint>
    password: <your_password_here>
    username: default
    ttl: 720h
    logs_table_name: hyperdx_sessions
    timeout: 5s
    retry_on_failure:
      enabled: true
      initial_interval: 5s
      max_interval: 30s
      max_elapsed_time: 300s
  clickhouse:
    database: default
    endpoint: <clickhouse_cloud_endpoint>
    password: <your_password_here>
    username: default
    ttl: 720h
    timeout: 5s
    retry_on_failure:
      enabled: true
      initial_interval: 5s
      max_interval: 30s
      max_elapsed_time: 300s

service:
  pipelines:
    traces:
      receivers: [otlp/hyperdx]
      processors: [memory_limiter, batch]
      exporters: [clickhouse]
    metrics:
      receivers: [otlp/hyperdx]
      processors: [memory_limiter, batch]
      exporters: [clickhouse]
    logs/in:
      receivers: [otlp/hyperdx]
      exporters: [routing/logs]
    logs/out-default:
      receivers: [routing/logs]
      processors: [memory_limiter, batch]
      exporters: [clickhouse]
    logs/out-rrweb:
      receivers: [routing/logs]
      processors: [memory_limiter, batch]
      exporters: [clickhouse/rrweb]

Envie um log de teste com o timestamp atual:

NOW_NANO="$(date +%s)000000000"

curl -i "http://localhost:4318/v1/logs" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
{
  "resourceLogs": [{
    "resource": {
      "attributes": [{
        "key": "service.name",
        "value": {"stringValue": "clickstack-docs-test"}
      }]
    },
    "scopeLogs": [{
      "scope": {"name": "clickstack-docs-test"},
      "logRecords": [{
        "timeUnixNano": "${NOW_NANO}",
        "severityText": "INFO",
        "body": {"stringValue": "ClickStack ingestion test"}
      }]
    }]
  }]
}
EOF

Se você usar um collector existente, substitua http://localhost:4318 pelo endpoint HTTP OTLP correspondente. Se o receiver exigir autenticação, adicione o header necessário ao comando curl.

Uma solicitação bem-sucedida retorna HTTP/1.1 200 OK.

Depois que o ClickStack detectar as fontes de dados do OpenTelemetry, selecione Começar a explorar para abrir a visualização Busca. Pesquise por ClickStack ingestion test.

O resultado deve incluir o evento de teste com o nome do serviço clickstack-docs-test.

A partir do seu serviço do ClickHouse Cloud, inicie o ClickStack. Na página Getting Started do ClickStack, selecione Start ingestion.

Na página Choose an ingestion source, selecione Vector.

O Vector é um pipeline de dados de observabilidade de alto desempenho e independente de fornecedor, especialmente popular para a ingestão de logs por sua flexibilidade e baixo consumo de recursos.

Ao usar o Vector com o ClickStack, é você quem define o schema. Ele pode seguir as convenções do OpenTelemetry ou usar fields específicos dos seus events.

Crie um banco de dados e uma tabela

Crie um database e uma table antes de configurar o sink do Vector.

No ClickHouse Cloud, abra o SQL console do seu service e crie um database:

Por exemplo, crie um banco de dados para logs:

CREATE DATABASE IF NOT EXISTS logs

Em seguida, crie uma tabela cujo schema corresponda à estrutura dos seus dados de log. O exemplo abaixo pressupõe um formato clássico de log de acesso do Nginx:

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);

Sua table deve estar alinhada com o schema de saída produzido pelo Vector. Ajuste o schema conforme necessário para seus dados, seguindo as melhores práticas de schema recomendadas.

Recomendamos fortemente que você entenda como as chaves primárias funcionam no ClickHouse e escolha uma chave de ordenação de acordo com os seus padrões de acesso. Consulte as orientações específicas do ClickStack sobre como escolher uma chave primária.

Configure o sink do ClickHouse

Com a tabela criada, adicione um sink do ClickHouse à configuração do Vector:

sinks:
  clickhouse:
    type: clickhouse
    inputs:
      - your_input
    endpoint: "https://<host>:8443"
    database: logs
    table: nginx_logs
    format: json_each_row
    skip_unknown_fields: true
    auth:
      strategy: basic
      user: default
      password: "<your_password_here>"

Substitua your_input pelo input do seu pipeline existente. Substitua <host> e <your_password_here> pelos valores do seu ClickHouse Cloud service. Se necessário, altere o target database ou a table.

CREATE USER `clickstack-ingest` IDENTIFIED WITH sha256_password BY '<password>';
GRANT SELECT, INSERT ON logs.nginx_logs TO `clickstack-ingest`;

Salve a configuração atualizada e, em seguida, recarregue ou reinicie o Vector usando o seu processo de implantação atual.

Para mais exemplos de ingestão de dados com o Vector, consulte Ingestão com o Vector ou, para opções avançadas, a documentação do sink ClickHouse do Vector.

Crie uma fonte de dados no ClickStack

Crie uma fonte de dados para a tabela preenchida pelo seu pipeline do Vector. O ClickStack solicita que você crie uma no primeiro login.

O formulário já vem pré-preenchido com as expressões do schema padrão do OpenTelemetry. Para a tabela do Nginx criada neste guia, configure a source com estes valores:

A tabela do Nginx não contém uma coluna Body. Defina Body Expression como:

concat(
  remote_addr, ' ',
  remote_user, ' ',
  '[', formatDateTime(time_local, '%d/%b/%Y:%H:%i:%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, '"'
)

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

Envie um evento representativo pela entrada do pipeline Vector existente.

Para conferir mais exemplos de fontes e transformações do Vector, consulte Ingestão com Vector.

Após criar a fonte de dados, selecione Iniciar exploração para abrir a visualização Busca. Selecione a fonte de dados da sua tabela e confirme se ela contém o evento enviado.