Pular para o conteúdo principal
Todos os componentes do ClickStack Open Source são distribuídos separadamente como imagens Docker distintas:
  • ClickHouse
  • HyperDX
  • OpenTelemetry collector (OTel)
  • MongoDB
Essas imagens podem ser combinadas e implantadas localmente com o Docker Compose. O Docker Compose expõe portas adicionais para observabilidade e ingestão com base na configuração padrão do otel-collector:
  • 13133: endpoint de verificação de integridade da extensão health_check
  • 24225: receiver do Fluentd para ingestão de logs
  • 4317: receiver OTLP gRPC (padrão para traces, logs e métricas)
  • 4318: receiver OTLP HTTP (alternativa ao gRPC)
  • 8888: endpoint de métricas do Prometheus para monitorar o próprio coletor
Essas portas permitem integrações com várias fontes de telemetria e deixam o OpenTelemetry collector pronto para produção para diferentes necessidades de ingestão.

​
Indicado para

  • Testes locais
  • Provas de conceito
  • Implantações em produção em que a tolerância a falhas não é necessária e um único servidor é suficiente para hospedar todos os dados do ClickHouse
  • Ao implantar o ClickStack, mas hospedar o ClickHouse separadamente, por exemplo, usando o ClickHouse Cloud

​
Etapas de implantação


1

​
Clone o repositório

Para implantar com Docker Compose, clone o repositório do ClickStack, entre no diretório e execute docker-compose up:
git clone https://github.com/ClickHouse/ClickStack.git
docker compose up
2

​
Acesse a UI do HyperDX

Acesse http://localhost:8080 para abrir a UI do HyperDX.Crie um usuário, informando um nome de usuário e uma senha que atendam aos requisitos.Ao clicar em Create, as fontes de dados serão criadas para a instância do ClickHouse implantada com Docker Compose.
Substituir a conexão padrãoVocê pode substituir a conexão padrão da instância integrada do ClickHouse. Para mais detalhes, consulte “Using ClickHouse Cloud”.
Para ver um exemplo de uso de outra instância do ClickHouse, consulte “Using ClickHouse Cloud”.
3

​
Preencha os detalhes da conexão

Para se conectar à instância do ClickHouse implantada, basta clicar em Create e aceitar as configurações padrão.Se preferir se conectar ao seu próprio cluster externo do ClickHouse, por exemplo, o ClickHouse Cloud, você pode inserir manualmente suas credenciais de conexão.Se for solicitado que você crie uma source, mantenha todos os valores padrão e preencha o campo Table com o valor otel_logs. Todas as outras configurações devem ser detectadas automaticamente, permitindo que você clique em Save New Source.

​
Modificando as configurações do Compose

Você pode modificar as configurações da stack, como a versão em uso, por meio do arquivo de variáveis de ambiente: 
user@example-host clickstack % cat .env

# Usado pelo docker-compose.yml
IMAGE_NAME_DOCKERHUB=clickhouse/clickstack-all-in-one
LOCAL_IMAGE_NAME_DOCKERHUB=clickhouse/clickstack-local
ALL_IN_ONE_IMAGE_NAME_DOCKERHUB=clickhouse/clickstack-all-in-one
OTEL_COLLECTOR_IMAGE_NAME_DOCKERHUB=clickhouse/clickstack-otel-collector
CODE_VERSION=2.8.0
IMAGE_VERSION_SUB_TAG=.8.0
IMAGE_VERSION=2
IMAGE_NIGHTLY_TAG=2-nightly
IMAGE_LATEST_TAG=latest

# Configurar URLs de domínio
HYPERDX_API_PORT=8000 #opcional (não deve ser utilizada por outros serviços)
HYPERDX_APP_PORT=8080
HYPERDX_APP_URL=http://localhost
HYPERDX_LOG_LEVEL=debug
HYPERDX_OPAMP_PORT=4320

# Configuração Otel/Clickhouse
HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE=default

​
Configurando o OpenTelemetry collector

A configuração do OTel collector pode ser alterada, se necessário — consulte “Modificando a configuração”.

​
Usando ClickHouse Cloud

Esta distribuição pode ser usada com o ClickHouse Cloud, mas difere do Managed ClickStack. Nesta configuração, você gerencia a UI do ClickStack por conta própria, enquanto usa o ClickHouse Cloud apenas para compute e armazenamento. A menos que você tenha um motivo específico para operar a UI de forma independente, recomendamos usar o Managed ClickStack, que inclui autenticação integrada e recursos Enterprise adicionais, além de eliminar a necessidade de gerenciar a UI do ClickStack por conta própria. Você deve:
  • Remover o serviço do ClickHouse do arquivo docker-compose.yml. Isso é opcional para testes, pois a instância implantada do ClickHouse será simplesmente ignorada, embora desperdice recursos locais. Se remover o serviço, certifique-se de também remover quaisquer referências a ele, como depends_on.
  • Modificar o OTel collector para usar uma instância do ClickHouse Cloud, definindo as variáveis de ambiente CLICKHOUSE_ENDPOINT, CLICKHOUSE_USER e CLICKHOUSE_PASSWORD no arquivo compose. Especificamente, adicione as variáveis de ambiente ao serviço do OTel collector: 
    otel-collector:
    image: ${OTEL_COLLECTOR_IMAGE_NAME_DOCKERHUB}:${IMAGE_VERSION}
    environment:
      CLICKHOUSE_ENDPOINT: '<CLICKHOUSE_ENDPOINT>' # endpoint HTTPS aqui
      CLICKHOUSE_USER: '<CLICKHOUSE_USER>'
      CLICKHOUSE_PASSWORD: '<CLICKHOUSE_PASSWORD>'
      HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE: ${HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE}
      HYPERDX_LOG_LEVEL: ${HYPERDX_LOG_LEVEL}
      OPAMP_SERVER_URL: 'http://app:${HYPERDX_OPAMP_PORT}'
    ports:
      - '13133:13133' # extensão health_check
      - '24225:24225' # receiver do Fluentd
      - '4317:4317' # receiver OTLP gRPC
      - '4318:4318' # receiver OTLP HTTP
      - '8888:8888' # extensão de métricas
    restart: always
    networks:
      - internal
    O CLICKHOUSE_ENDPOINT deve ser o endpoint HTTPS do ClickHouse Cloud, incluindo a porta 8443, por exemplo: https://mxl4k3ul6a.us-east-2.aws.clickhouse.com:8443
  • Ao se conectar à UI do HyperDX e criar uma conexão com o ClickHouse, use suas credenciais do Cloud.

​
Escolha de esquema: Map vs JSON

O ClickStack armazena atributos como colunas Map(LowCardinality(String), String) por padrão. Esse é o esquema recomendado para cargas de trabalho de observabilidade. Em combinação com a serialização de map em buckets e índices de texto nas chaves e nos valores do map, ele permite lookups seletivos sem a sobrecarga de ingestão por chave das subcolunas JSON dinâmicas. Um esquema do tipo JSON está disponível em beta para avaliação em cargas de trabalho com um conjunto pequeno e estável de chaves de atributo. Ele não é recomendado como padrão. Consulte Map vs tipo JSON para ver a comparação completa e as variáveis de ambiente necessárias para habilitar o suporte a JSON.
Última modificação em 10 de junho de 2026