Docker Compose

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.

• 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

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

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.

Para ver um exemplo de uso de outra instância do ClickHouse, consulte "Using ClickHouse Cloud".

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.

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

# Used by 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

# Set up domain URLs
HYPERDX_API_PORT=8000 #optional (should not be taken by other services)
HYPERDX_APP_PORT=8080
HYPERDX_APP_URL=http://localhost
HYPERDX_LOG_LEVEL=debug
HYPERDX_OPAMP_PORT=4320

# Otel/ClickHouse config
HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE=default

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

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.

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.