Primeiros passos no Managed ClickStack

Implante o Managed ClickStack no ClickHouse Cloud, envie um evento de teste pelo seu pipeline de ingestão e confirme que o evento está disponível na UI do ClickStack. O ClickHouse Cloud opera o backend do ClickHouse enquanto você mantém o controle sobre o pipeline de ingestão e o schema. O Managed ClickStack oferece:

Escalonamento automático de recurso computacional, independente do armazenamento
Retenção de baixo custo e praticamente ilimitada com base em armazenamento de objetos
Isolamento independente de workloads de leitura e gravação com warehouses
Autenticação integrada
Backups automatizados
Recursos de segurança e compliance
upgrade contínuo

Antes de começar

Você também pode enviar dados diretamente ao ClickHouse usando uma integração compatível e seu próprio schema.

Crie um serviço no ClickHouse Cloud

Conclua o passo Criar um serviço do ClickHouse no quickstart do ClickHouse Cloud. Antes de continuar, confirme que o serviço está em execução.

Esta página exibe o caminho do OpenTelemetry. Use o seletor do guia, próximo ao início da página, para alternar entre OpenTelemetry (recomendado) e Vector.

Prepare seu ambiente de ingestão

Para iniciar um novo OpenTelemetry Collector, instale o Docker. No Kubernetes, faça a implantação do collector com o Helm.
Para usar um collector existente, execute-o na função de gateway e verifique se a distribuição dele inclui o exporter do ClickHouse. Você adicionará a configuração necessária neste guia.

Configurar o Managed ClickStack

Escolha uma fonte de ingestão e configure o collector

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.

OpenTelemetry recomendadoO OpenTelemetry fornece esquemas pré-configurados para logs, rastreamentos, métricas e sessões.

Iniciar um novo coletor
Usar um coletor existente

O ClickStack gera o comando do coletor com as credenciais de administrador default. Recomendamos usar credenciais de ingestão dedicadas para separar o acesso de ingestão da administração e evitar depender da senha de administrador.

Criar credenciais de ingestão dedicadas (recomendado)

No ClickHouse Cloud, abra o Console SQL do serviço e execute:

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

No comando gerado, substitua CLICKHOUSE_USER="default" por CLICKHOUSE_USER="clickstack-ingest" e defina CLICKHOUSE_PASSWORD com a senha do usuário dedicado.

Para continuar com as credenciais de administrador default, copie o comando da guia Iniciar coletor. O ClickStack preenche automaticamente o endpoint do serviço. Substitua o placeholder de senha pela senha do serviço. Se não a tiver mais, recupere ou redefina os detalhes de conexão.O comando tem o seguinte formato:

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

Substitua <host> e <your_password_here> pelos valores do serviço ClickHouse Cloud e execute o comando.O coletor é executado em primeiro plano. Mantenha este terminal aberto e use um segundo terminal para os demais comandos deste guia.

Este comando expõe as portas OTLP sem autenticação e destina-se à avaliação local. Antes de enviar tráfego de produção, proteja o coletor.

Selecione Configurar coletor existente e adapte a configuração do coletor.Execute o coletor como um gateway entre suas aplicações e o ClickHouse Cloud. A configuração abaixo adiciona os exporters do ClickHouse e os pipelines de sinais necessários.O exemplo usa as credenciais default geradas pelo ClickStack. Para usar credenciais de ingestão dedicadas, siga a configuração opcional na guia Iniciar um novo coletor. Nos dois blocos de exporter do ClickHouse, substitua username: default por username: clickstack-ingest e defina password com a senha do usuário dedicado.Mescle os componentes a seguir à configuração existente, em vez de substituir receivers, processors, exporters ou extensions não relacionados.

Componentes obrigatórios do coletorA distribuição do coletor deve incluir o exporter do ClickHouse e o conector de roteamento. A distribuição OpenTelemetry Collector Contrib inclui ambos os componentes.

O exemplo adiciona receivers OTLP, processamento em lote, limitação de memória, roteamento de reprodução de sessão e exporters do ClickHouse.Substitua os placeholders de endpoint e senha pelas credenciais geradas pelo ClickStack:

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]

Reutilize o receiver OTLP existente e preserve as configurações de autenticação e TLS. Se a configuração já usar os IDs de componentes ou pipelines do exemplo, mescle-os ou renomeie-os em vez de criar IDs duplicados. Executar dois receivers nas portas 4317 e 4318 causa conflito de portas.Após mesclar a configuração, recarregue ou reinicie o coletor usando o processo de implantação existente.Para mais detalhes sobre como configurar coletores OpenTelemetry, consulte Ingestão com OpenTelemetry.

Envie dados de teste

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.

Comece a explorar e confirme a ingestão

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.

Agora você tem um serviço Managed ClickStack, um endpoint de ingestão funcional e um evento de teste que pode inspecionar no ClickStack.

Próximas etapas

Se outro guia exigir o endpoint ou a senha do ClickHouse Cloud, obtenha ou redefina os dados de conexão antes de continuar.

Envie dados de aplicações e da infraestrutura

Escolha um guia para os dados que deseja enviar ao ClickStack:

Instrumente uma aplicação

Envie traces e logs da aplicação usando um SDK do OpenTelemetry compatível.

Colete logs do host

Encaminhe logs do host usando um OpenTelemetry Collector executado como agente.

Monitore o Kubernetes

Colete logs, métricas e traces de um cluster do Kubernetes.

Explore outras integrações

Encontre guias para outras aplicações e fontes de telemetria.

Explorar dados de exemplo

Use um conjunto de dados de exemplo para explorar o ClickStack com telemetria mais completa:

Logs, traces e métricas de exemplo

Carregue dados da demonstração pública e diagnostique um problema. Este guia pressupõe que você tenha iniciado um novo OpenTelemetry Collector local. Se você configurou um collector existente, adapte as configurações de endpoint e autenticação à sua implantação.

Logs e métricas locais

Colete arquivos locais e métricas do sistema no macOS ou Linux.

Gere dados sintéticos

Use um gerador para testar a ingestão sem precisar de uma aplicação ou conjunto de dados existente:

Gere dados com otelgen

Envie uma breve sequência de logs, traces e métricas sintéticos via OTLP.

Gere dados com telemetrygen

Gere sinais do OpenTelemetry configuráveis em vários serviços.

Consulte todos os dados de exemplo e demonstrações do ClickStack.

Preparação para produção

Revise as orientações sobre produção e dimensionamento antes de usar o ClickStack para workloads contínuos:

Preparação para produção

Revise as credenciais de ingestão, a segurança, a retenção e as orientações operacionais.

Estimar recursos

Dimensione os recursos computacionais para o volume de ingestão esperado.

Para tarefas de implantação, consulte o guia de implantação do Managed ClickStack.