Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Opções de configuração

View as MarkdownEdit this pageReport an issueSet up docs MCP

As opções de configuração a seguir estão disponíveis para cada componente do ClickStack:

Configurações para distribuições de código aberto

Docker

Se estiver usando All in One, HyperDX Only ou Local Mode, basta informar a configuração desejada por meio de uma variável de ambiente, por exemplo.

docker run  -e HYPERDX_LOG_LEVEL='debug' -p 8080:8080 -p 4317:4317 -p 4318:4318 clickhouse/clickstack-all-in-one:latest

Docker Compose

Se você estiver usando o guia de implantação do Docker Compose, poderá usar o arquivo .env para modificar as configurações.

Como alternativa, sobrescreva explicitamente as configurações no arquivo docker-compose.yaml, por exemplo.

Exemplo:

services:
  app:
    environment:
      HYPERDX_API_KEY: ${HYPERDX_API_KEY}
      HYPERDX_LOG_LEVEL: ${HYPERDX_LOG_LEVEL}
      # ... outras configurações

Helm

Personalizar values (opcional)

Você pode personalizar as configurações usando as flags --set, por exemplo.

helm install my-hyperdx hyperdx/hdx-oss-v2 \
  --set replicaCount=2 \
  --set resources.limits.cpu=500m \
  --set resources.limits.memory=512Mi \
  --set resources.requests.cpu=250m \
  --set resources.requests.memory=256Mi \
  --set ingress.enabled=true \
  --set ingress.annotations."kubernetes\.io/ingress\.class"=nginx \
  --set ingress.hosts[0].host=hyperdx.example.com \
  --set ingress.hosts[0].paths[0].path=/ \
  --set ingress.hosts[0].paths[0].pathType=ImplementationSpecific \
  --set env[0].name=CLICKHOUSE_USER \
  --set env[0].value=abc

Como alternativa, edite o values.yaml. Para obter os valores padrão:

helm show values hyperdx/hdx-oss-v2 > values.yaml

Exemplo de configuração:

replicaCount: 2
resources:
  limits:
    cpu: 500m
    memory: 512Mi
  requests:
    cpu: 250m
    memory: 256Mi
ingress:
  enabled: true
  annotations:
    kubernetes.io/ingress.class: nginx
  hosts:
    - host: hyperdx.example.com
      paths:
        - path: /
          pathType: ImplementationSpecific
  env:
    - name: CLICKHOUSE_USER
      value: abc

Aplicação da ClickStack UI (HyperDX)

Configurações da fonte de dados

A UI do ClickStack depende de o usuário definir uma fonte para cada um dos tipos/pilares de dados de observabilidade:

  • Logs
  • Traces
  • Metrics
  • Sessions

Essa configuração pode ser feita no aplicativo em Team Settings -> Sources, como mostrado abaixo para logs:

Configuração de fonte do HyperDX

Cada uma dessas fontes exige que pelo menos uma tabela seja especificada na criação, além de um conjunto de colunas que permite ao HyperDX consultar os dados.

Se você estiver usando o schema padrão do OpenTelemetry (OTel) distribuído com o ClickStack, essas colunas poderão ser inferidas automaticamente para cada uma das fontes. Se estiver modificando o schema ou usando um schema personalizado, será necessário especificar e atualizar esses mapeamentos.

As configurações a seguir estão disponíveis para cada fonte:

Logs

Configuração Descrição Obrigatório Inferido no esquema padrão Valor inferido
Nome Nome da fonte. Sim No –
Seção Rótulo opcional para agrupar fontes no seletor de fontes. As fontes que compartilham uma seção são exibidas juntas, e a busca também considera o nome da seção, além do nome da fonte. No No –
Conexão do servidor Nome da conexão do servidor. Sim No Padrão
Banco de dados Nome do banco de dados ClickHouse. Sim Sim default
Tabela Nome da tabela de destino. Defina como otel_logs se o schema padrão estiver em uso. Sim No
Configurações de consulta Configurações de sessão no nível da consulta, cada uma especificada por um nome e um valor de configuração, adicionadas a todas as consultas executadas nesta fonte. No No –
Ativado Uma fonte desativada é mantida, mas fica oculta nos seletores de fontes e nunca é selecionada automaticamente. No No Ativado
Coluna de timestamp Coluna ou expressão DateTime que faz parte da chave primária. Sim Sim TimestampTime
Seleção padrão Colunas exibidas nos resultados de busca padrão. Sim Sim Timestamp, ServiceName, SeverityText, Body
Expressão de nome do serviço Expressão ou coluna para o nome do serviço. Sim Sim ServiceName
Expressão de versão do serviço Expressão ou coluna que identifica o lançamento em execução de um serviço, usada para exibir marcadores de lançamento nos gráficos do dashboard. Se deixada em branco, usa por padrão o atributo de recurso OpenTelemetry service.version. No No ResourceAttributes['service.version']
Expressão de nível de log Expressão ou coluna para o nível de log. Sim Sim SeverityText
Expressão do corpo Expressão ou coluna para a mensagem de log. Sim Sim Body
Expressão de atributos de log Expressão ou coluna para atributos de log personalizados. Sim Sim LogAttributes
Expressão de atributos de recurso Expressão ou coluna para atributos no nível do recurso. Sim Sim ResourceAttributes
Coluna de timestamp exibida Coluna de timestamp opcional, de maior precisão, usada na exibição da UI. Se não for fornecida, o padrão será Timestamp Column. No Sim Timestamp
fonte de métricas correlacionada Fonte de métricas vinculada (por exemplo, métricas do HyperDX). No No –
Fonte de rastreamento correlacionada Fonte de traces vinculada (por exemplo, traces do HyperDX). No No –
Expressão de ID do trace Expressão ou coluna usada para extrair o ID do trace. Sim Sim TraceId
Expressão de ID do span Expressão ou coluna usada para extrair o ID do span. Sim Sim SpanId
Expressão de Coluna Implícita Coluna usada para pesquisa de texto completo quando nenhum campo é especificado (no estilo Lucene). Geralmente, o corpo do log. Sim Sim Body
Lista de colunas conhecidas Para fontes que usam uma tabela Distributed ou Merge cujas tabelas de destino têm conjuntos de colunas diferentes. Uma lista separada por vírgulas das colunas disponíveis em todas as tabelas de destino, usada em vez de SELECT * ao buscar dados completos de uma linha (por exemplo, no painel lateral da linha). Deixe em branco para selecionar todas as colunas. Somente nomes de colunas — sem expressões ou aliases. No No –
Usar índice de texto Se as buscas baseadas em Lucene usam hasAllTokens ao pesquisar na coluna implícita. No No Automático (detecção pelo schema)
Atributos destacados Expressões ou colunas exibidas ao abrir os detalhes do log. As expressões que retornam URLs serão exibidas como links. No No –
Atributos de trace em destaque Expressões ou colunas extraídas de cada log em um trace, exibidas acima da visualização em cascata do trace. Expressões que retornam URLs são exibidas como links. No No –
Visões materializadas Visões materializadas pré-agregadas associadas a esta fonte, usadas automaticamente para acelerar consultas compatíveis. Consulte Visões materializadas. No No –
Visões materializadas de metadados Visões materializadas usadas para acelerar a descoberta de campos e o preenchimento automático de valores. Consulte Visões materializadas de metadados. No Sim <table>_kv_rollup_15m
Ordenação padrão Expressão ORDER BY que substitui a ordenação padrão dos resultados de busca. Deixe em branco para usar o padrão detectado automaticamente. Isso pode ser personalizado posteriormente para cada busca. No No –

Traces

Configuração Descrição Obrigatório Inferido no schema padrão Valor inferido
Name Nome da fonte. Sim Não –
Section Rótulo opcional para agrupar fontes no seletor de fontes. Fontes que compartilham uma seção aparecem juntas, e a busca encontra o nome da seção além do nome da fonte. Não Não –
Server Connection Nome da conexão com o servidor. Sim Não Default
Database Nome do banco de dados do ClickHouse. Sim Sim default
Table Nome da tabela de destino. Defina como otel_traces se estiver usando o schema padrão. Sim Sim -
Query Settings Configurações de sessão no nível da consulta, cada uma fornecida como um nome de configuração e um valor, que são adicionadas a cada consulta emitida para esta fonte. Não Não –
Enabled Uma fonte desabilitada é mantida, mas fica oculta nos seletores de fonte e nunca é escolhida automaticamente. Não Não Habilitado
Timestamp Column Coluna de data e hora ou expressão que faz parte da sua primary key. Sim Sim Timestamp
Default Select Colunas exibidas nos resultados de busca padrão. Sim Sim Timestamp, ServiceName as service, StatusCode as level, round(Duration / 1e6) as duration, SpanName
Duration Expression expressão usada para calcular a duração do span. Sim Sim Duration
Duration Precision Precisão da expressão de duração (por exemplo, nanossegundos, microssegundos). Sim Sim ns
Trace Id Expression expressão ou coluna para IDs de trace. Sim Sim TraceId
Span Id Expression expressão ou coluna para IDs de span. Sim Sim SpanId
Parent Span Id Expression expressão ou coluna para IDs de spans pai. Sim Sim ParentSpanId
Span Name Expression expressão ou coluna para nomes de span. Sim Sim SpanName
Span Kind Expression expressão ou coluna para o tipo de span (por exemplo, client, server). Sim Sim SpanKind
Correlated Log Source Opcional. Fonte de logs vinculada (por exemplo, logs do HyperDX). Não Não –
Correlated Session Source Opcional. Fonte de sessão vinculada. Não Não –
Correlated Metric Source Opcional. Fonte de métricas correlacionada (por exemplo, métricas do HyperDX). Não Não –
Status Code Expression expressão para o código de status do span. Sim Sim StatusCode
Status Message Expression expressão para a mensagem de status do span. Sim Sim StatusMessage
Service Name Expression expressão ou coluna para o nome do serviço. Sim Sim ServiceName
Service Version Expression Expressão ou coluna que identifica o lançamento em execução de um serviço, usada para desenhar marcadores de lançamento em gráficos do dashboard. Por padrão, usa o atributo de recurso OpenTelemetry service.version quando deixada em branco. Não Não ResourceAttributes['service.version']
Resource Attributes Expression expressão ou coluna para atributos no nível do recurso. Sim Sim ResourceAttributes
Event Attributes Expression expressão ou coluna para atributos de evento. Sim Sim SpanAttributes
Sample Rate Expression Coluna ou expressão que contém o peso de amostragem upstream (1/N). Quando definida, as agregações (count, avg, sum, quantile) são corrigidas para amostragem. Os percentis passam a usar quantileTDigestWeighted, que é uma aproximação, portanto os valores exatos podem diferir ligeiramente. Deixe vazio se os spans não forem submetidos a amostragem. Não Não –
Span Events Expression expressão para extrair eventos de span. Normalmente, uma coluna do tipo Nested. Isso permite renderizar stack traces de exceção com SDK de linguagem compatíveis. Sim Sim Events
Span Links Expression Expressão para extrair links de span, usada para capturar links de um span para spans em outros traces. Espera-se que seja do tipo Nested(TraceId String, SpanId String, TraceState String, Attributes Map(LowCardinality(String), String)). Não Sim Links
Implicit Column Expression Coluna usada para busca de texto completo quando nenhum field é especificado (estilo Lucene). Normalmente, o corpo do log. Sim Sim SpanName
Known Columns List Para fontes em uma tabela Distributed ou Merge cujas tabelas de destino têm conjuntos de colunas não correspondentes. Uma lista separada por vírgulas das colunas disponíveis em todas as tabelas de destino, usada em vez de SELECT * ao buscar dados completos de linhas (por exemplo, no painel lateral da linha). Deixe em branco para selecionar todas as colunas. Somente nomes de colunas — sem expressões ou aliases. Não Não –
Use Text Index Determina se as buscas baseadas em Lucene emitem hasAllTokens ao pesquisar a coluna implícita. Não Não Auto (detect from schema)
Displayed Timestamp Column Coluna de timestamp opcional e de maior precisão, usada na exibição da UI. Por padrão, usa Timestamp Column quando não é fornecida. Não Sim Timestamp
Highlighted Attributes Expressões ou colunas exibidas ao abrir os detalhes do span. Expressões que retornam URLs serão mostradas como links. Não Não –
Highlighted Trace Attributes Expressões ou colunas extraídas de cada span em um trace, exibidas acima do waterfall do trace. Expressões que retornam URLs serão mostradas como links. Não Não –
Materialized Views Visões materializadas pré-agregadas registradas nessa fonte, usadas automaticamente para acelerar queries elegíveis. Consulte Visões materializadas. Não Não –
Metadata Materialized Views Visões materializadas usadas para acelerar a descoberta de campos e o preenchimento automático de valores. Consulte Visões materializadas de metadados. Não Sim <table>_kv_rollup_15m
Default Order By expressão ORDER BY que substitui a ordenação padrão dos resultados de busca. Deixe vazio para usar o padrão detectado automaticamente. Isso pode ser personalizado posteriormente para cada busca. Não Não –

Métricas

Configuração Descrição Obrigatório Inferido no schema padrão Valor inferido
Name Nome da fonte. Sim Não –
Section Rótulo opcional para agrupar fontes no seletor de fontes. Fontes que compartilham uma seção aparecem juntas, e a busca também considera o nome da seção além do nome da fonte. Não Não –
Server Connection Nome da conexão com o servidor. Sim Não Default
Database Nome do banco de dados do ClickHouse. Sim Sim default
Query Settings Até dez configurações de sessão no nível da consulta, cada uma fornecida como um nome de configuração e um valor, que são adicionadas a todas as consultas emitidas para esta fonte. Não Não –
Enabled Alternância na parte superior do formulário da fonte. Uma fonte desativada é mantida, mas fica oculta dos seletores de fontes e nunca é escolhida automaticamente. Exibida apenas ao editar uma fonte existente. Não Não Habilitado
Gauge Table Tabela que armazena métricas do tipo gauge. Não Sim otel_metrics_gauge
Histogram Table Tabela que armazena métricas do tipo histograma. Não Sim otel_metrics_histogram
Sum Table Tabela que armazena métricas do tipo soma (counter). Não Sim otel_metrics_sum
Exponential Histogram Table Tabela que armazena métricas do tipo histograma exponencial. Não Sim otel_metrics_exponential_histogram
Correlated Log Source Opcional. Fonte de logs vinculada (por exemplo, logs do HyperDX). Não Não –

Sessões

Configuração Descrição Obrigatório Inferido no schema padrão Valor inferido
Name Nome da fonte. Sim Não –
Section Rótulo opcional para agrupar fontes no seletor de fontes. Fontes que compartilham uma seção aparecem juntas, e a busca também considera o nome da seção além do nome da fonte. Não Não –
Server Connection Nome da conexão com o servidor. Sim Não Default
Database Nome do banco de dados do ClickHouse. Sim Sim default
Table Tabela de destino para os dados de sessão. Nome da tabela de destino. Defina como hyperdx_sessions se estiver usando o schema padrão. Sim Sim -
Query Settings Até dez configurações de sessão no nível da consulta, cada uma informada como um nome de configuração e um valor, que são adicionadas a todas as consultas emitidas para esta fonte. Não Não –
Enabled Alternância na parte superior do formulário da fonte. Uma fonte desabilitada é mantida, mas fica oculta dos seletores de fontes e nunca é escolhida automaticamente. Exibido apenas ao editar uma fonte existente. Não Não Habilitado
Correlated Trace Source Fonte de traces vinculada para correlação de sessões. Sim Não –
Timestamp Column Coluna de timestamp ou expressão que faz parte da sua chave primária. Sim Sim TimestampTime
Resource Attributes Expression Expressão para extrair metadados no nível de recurso. Não Sim ResourceAttributes

Visões materializadas

As visões materializadas podem ser registradas para fontes de dados de Log e Trace, permitindo que consultas de agregação qualificadas sejam respondidas pela visão pré-agregada em vez da tabela de origem. Para obter orientações sobre como criar e registrar visões, consulte "Visões materializadas".

Cada visão registrada é configurada com as seguintes opções:

Configuração Descrição
Database Banco de dados do ClickHouse que contém a tabela de destino da visão materializada.
Table Tabela de destino da visão materializada — não a própria visão.
Timestamp Column A coluna de timestamp da tabela de destino.
Granularity O bucket de tempo da coluna de timestamp da tabela de destino, por exemplo, 1 minute. Uma consulta só pode usar a visão se seu próprio bucket de tempo for igual ou mais amplo que este.
Minimum Date Opcional. A data e hora mais antiga para a qual a visão contém dados. Se não for fornecida, o ClickStack pressupõe que a visão contém dados para todas as datas para as quais a tabela de origem contém dados.
Dimension Columns Lista separada por vírgulas das colunas que não são pré-agregadas pela visão e que, portanto, podem ser usadas para filtragem e agrupamento.
Pre-aggregated Columns As colunas pré-agregadas pela visão. Cada entrada mapeia uma função de agregação (avg, count, max, min, quantile, sum ou histogram) e uma coluna da tabela de origem para a coluna correspondente na visão. A coluna de origem não é necessária para count.

A maioria dessas configurações é inferida do schema da visão quando a tabela de destino é selecionada.

Visões materializadas de metadados

As visões materializadas de metadados aceleram a descoberta de campos para filtros e o preenchimento automático. Elas podem ser configuradas em fontes de dados de Log e Trace.

Configuração Descrição
Key Rollup Table Opcional e obsoleta. Tabela de rollup das chaves presentes na tabela de origem.
KV Rollup Table Tabela de rollup dos pares chave-valor presentes na tabela de origem.
Granularity O bucket de tempo usado pelas tabelas de rollup, por exemplo, 15 minute.

Atributos destacados

Atributos destacados e Atributos de trace destacados podem ser configurados em fontes de dados de logs e traces.

  • Atributos destacados são colunas ou expressões exibidas para cada log ou span ao visualizar os detalhes do log ou do span.
  • Atributos de trace destacados são colunas ou expressões consultadas de cada log ou span em um trace e exibidas acima do waterfall do trace.

Esses atributos são definidos na configuração da fonte e podem ser expressões SQL arbitrárias. Se a expressão SQL retornar um valor no formato de uma URL, o atributo será exibido como um link. Valores vazios não são exibidos.

Cada atributo é configurado com as seguintes configurações:

Configuração Descrição
SQL Expression A coluna ou expressão SQL arbitrária a ser consultada. Obrigatório.
Alias Opcional. O rótulo exibido para o atributo no lugar da expressão SQL.
Lucene Expression Opcional. Uma versão Lucene da expressão SQL, usada ao buscar este valor de atributo.

Por exemplo, esta trace fonte foi configurada com um Atributo destacado e um Atributo de trace destacado:

Configuração de Atributos destacados

Esses atributos são exibidos no painel lateral após clicar em um log ou span:

Atributos destacados

Ao clicar em um atributo, são fornecidas opções para usá-lo como valor de busca. Se a expressão Lucene opcional for fornecida na configuração do atributo, a expressão Lucene será usada para a busca em vez da expressão SQL.

Busca de Atributos destacados

Fontes correlacionadas

Para habilitar a correlação completa entre fontes no ClickStack, você precisa configurar fontes correlacionadas para logs, traces, métricas e sessões. Isso permite que o HyperDX associe dados relacionados e forneça um contexto mais rico ao exibir eventos.

  • Logs: podem ser correlacionados com traces e métricas.
  • Traces: podem ser correlacionados com logs, sessões e métricas.
  • Metrics: podem ser correlacionadas com logs.
  • Sessions: podem ser correlacionadas com traces.

Configurar essas correlações habilita vários recursos. Por exemplo, o HyperDX pode exibir logs relevantes ao lado de um trace ou destacar anomalias de métricas vinculadas a uma sessão.

Por exemplo, abaixo está a fonte de Logs configurada com fontes correlacionadas:

Fonte correlacionada do HyperDX

Configurações do aplicativo

  • HYPERDX_API_KEY

    • Padrão: Nenhum (obrigatório)
    • Descrição: Chave de autenticação da API do HyperDX.
    • Orientações:
    • Obrigatória para telemetria e logging
    • Em ambiente de desenvolvimento local, pode ser qualquer valor não vazio
    • Para produção, use uma chave segura e exclusiva
    • Pode ser obtida na página Team Settings após a criação da conta

  • HYPERDX_LOG_LEVEL

    • Padrão: info
    • Descrição: Define o nível de verbosidade do logging.
    • Opções: debug, info, warn, error
    • Orientação:
    • Use debug para solução de problemas detalhada
    • Use info para operação normal
    • Use warn ou error em produção para reduzir o volume de logs

  • HYPERDX_API_PORT

    • Padrão: 8000
    • Descrição: Porta do servidor de API do HyperDX.
    • Orientação:
    • Verifique se essa porta está disponível no seu host
    • Altere-a se houver conflito de portas
    • Deve corresponder à porta definida nas configurações do cliente de API

  • HYPERDX_APP_PORT

    • Padrão: 8000
    • Descrição: Porta do aplicativo de frontend do HyperDX.
    • Orientação:
    • Certifique-se de que essa porta esteja disponível no host
    • Altere se houver conflito de porta
    • Deve estar acessível pelo navegador

  • HYPERDX_APP_URL

    • Padrão: http://localhost
    • Descrição: URL base da aplicação front-end.
    • Orientação:
    • Defina seu domínio em produção
    • Inclua o protocolo (http/https)
    • Não inclua a barra no final

  • MONGO_URI

    • Padrão: mongodb://db:27017/hyperdx
    • Descrição: String de conexão do MongoDB.
    • Orientação:
    • Use o valor padrão para desenvolvimento local com Docker
    • Para produção, use uma string de conexão segura
    • Inclua autenticação, se necessário
    • Exemplo: mongodb://user:pass@host:port/db

  • MINER_API_URL

    • Padrão: http://miner:5123
    • Descrição: URL do serviço de mineração de padrões de log.
    • Orientação:
    • Use o valor padrão para desenvolvimento local com Docker
    • Em produção, defina a URL do seu serviço miner
    • Deve estar acessível a partir do serviço de API

  • FRONTEND_URL

    • Padrão: http://localhost:3000
    • Descrição: URL do aplicativo frontend.
    • Orientação:
    • Use o valor padrão para desenvolvimento local
    • Defina seu domínio em produção
    • Deve estar acessível pelo serviço de API

  • OTEL_SERVICE_NAME

    • Padrão: hdx-oss-api
    • Descrição: Nome do serviço para a instrumentação do OpenTelemetry.
    • Orientação:
    • Use um nome descritivo para seu serviço HyperDX. Aplicável se o HyperDX fizer autoinstrumentação.
    • Ajuda a identificar o serviço HyperDX nos dados de telemetria

  • NEXT_PUBLIC_OTEL_EXPORTER_OTLP_ENDPOINT

    • Padrão: http://localhost:4318
    • Descrição: endpoint do collector do OpenTelemetry.
    • Orientação:
    • Relevante para a auto-instrumentação do HyperDX.
    • Use o padrão para desenvolvimento local
    • Defina como a URL do seu collector em produção
    • Deve estar acessível a partir do seu serviço HyperDX

  • USAGE_STATS_ENABLED

    • Padrão: true
    • Descrição: Ativa ou desativa a coleta de estatísticas de uso.
    • Orientação:
    • Defina como false para desativar o rastreamento de uso
    • Útil para implantações com requisitos rigorosos de privacidade
    • O padrão é true para melhorar o produto

  • IS_OSS

    • Padrão: true
    • Descrição: Indica se está sendo executado no modo OSS.
    • Orientação:
    • Mantenha como true para implantações de código aberto
    • Defina como false para implantações Enterprise
    • Afeta a disponibilidade de funcionalidades

  • IS_LOCAL_MODE

    • Padrão: false
    • Descrição: Indica se está sendo executado em modo local.
    • Orientação:
    • Defina como true para desenvolvimento local
    • Desativa determinados recursos de produção
    • Útil para testes e desenvolvimento

  • EXPRESS_SESSION_SECRET

    • Padrão: hyperdx is cool 👋
    • Descrição: Segredo usado no gerenciamento de sessão do Express.
    • Orientação:
    • Altere em produção
    • Use uma string aleatória e forte
    • Mantenha em segredo e em segurança

  • ENABLE_SWAGGER

    • Padrão: false
    • Descrição: Ativa ou desativa a documentação da API do Swagger.
    • Orientações:
    • Defina como true para habilitar a documentação da API
    • Útil para desenvolvimento e testes
    • Desative em produção

  • BETA_CH_OTEL_JSON_SCHEMA_ENABLED

    • Padrão: false
    • Descrição: Habilita suporte Beta para o tipo JSON no HyperDX. Veja também OTEL_AGENT_FEATURE_GATE_ARG para habilitar o suporte a JSON no OTel collector.
    • Orientação:
      • Habilita um recurso beta. Schemas tipados como JSON não são recomendados para workloads típicos de observabilidade. Consulte Map vs JSON type para ver a comparação e quando cada um é mais apropriado.
      • Defina como true para habilitar o suporte a JSON na ClickStack UI.

collector OpenTelemetry

Consulte "ClickStack OpenTelemetry Collector" para mais detalhes.

  • CLICKHOUSE_ENDPOINT

    • Padrão: None (obrigatório) se for uma imagem standalone. Se for uma distribuição All-in-one ou Docker Compose, isso é definido para a instância integrada do ClickHouse.
    • Descrição: A URL HTTPS da instância do ClickHouse para a qual os dados de telemetria serão exportados.
    • Orientação:
      • Deve ser um endpoint HTTPS completo, incluindo a porta (por exemplo, https://clickhouse.example.com:8443)
      • Obrigatório para que o collector envie dados ao ClickHouse

  • CLICKHOUSE_USER

    • Padrão: default
    • Descrição: Nome de usuário usado para autenticar na instância do ClickHouse.
    • Orientação:
      • Certifique-se de que o usuário tenha permissões INSERT e CREATE TABLE
      • Recomenda-se criar um usuário dedicado para ingestão

  • CLICKHOUSE_PASSWORD

    • Padrão: None (obrigatório se a autenticação estiver habilitada)
    • Descrição: Senha do usuário do ClickHouse especificado.
    • Orientação:
      • Obrigatório se a conta de usuário tiver uma senha definida
      • Armazene com segurança por meio de secrets em implantações de produção

  • HYPERDX_LOG_LEVEL

    • Padrão: info
    • Descrição: Nível de verbosidade de log do collector.
    • Orientação:
      • Aceita valores como debug, info, warn, error
      • Use debug durante a solução de problemas

  • OPAMP_SERVER_URL

    • Padrão: None (obrigatório) se for uma imagem standalone. Se for uma distribuição All-in-one ou Docker Compose, isso aponta para a instância implantada do HyperDX.
    • Descrição: URL do servidor OpAMP usado para gerenciar o collector (por exemplo, uma instância do HyperDX). Por padrão, essa é a porta 4320.
    • Orientação:
      • Deve apontar para sua instância do HyperDX
      • Habilita configuração dinâmica e ingestão segura
      • Se omitido, a ingestão segura é desabilitada, a menos que um valor de OTLP_AUTH_TOKEN seja especificado.

  • OTLP_AUTH_TOKEN

    • Padrão: None. Usado somente para imagem standalone.
    • Descrição: Permite especificar um token de autenticação OTLP. Se definido, toda a comunicação exige esse bearer token.
    • Orientação:
      • Recomendado se estiver usando a imagem standalone do collector em produção.

  • HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE

    • Padrão: default
    • Descrição: Banco de dados do ClickHouse no qual o collector grava dados de telemetria.
    • Orientação:
      • Defina se estiver usando um nome do banco de dados personalizado
      • Certifique-se de que o usuário especificado tenha acesso a este banco de dados

  • OTEL_AGENT_FEATURE_GATE_ARG

    • Padrão: <empty string>
    • Descrição: Habilita feature flags no collector. Se definido como --feature-gates=clickhouse.json, habilita suporte Beta para o tipo JSON no collector, garantindo que schemas sejam criados com esse tipo. Consulte também BETA_CH_OTEL_JSON_SCHEMA_ENABLED para habilitar o suporte a JSON no HyperDX.
    • Orientação:
      • Habilita um recurso beta. Schemas tipados como JSON não são recomendados para workloads típicas de observabilidade. Consulte Map vs JSON type para ver a comparação e quando cada um é apropriado.
      • Defina como --feature-gates=clickhouse.json para criar novas tabelas usando o tipo JSON.

ClickHouse

O ClickStack Open Source vem com uma configuração padrão do ClickHouse projetada para operar em escala de vários terabytes, mas os usuários podem modificá-la e otimizá-la conforme sua carga de trabalho.

Para ajustar o ClickHouse com eficácia, é importante entender conceitos-chave de armazenamento, como partes, partições, shards e réplicas e como as mesclagens ocorrem durante a inserção. Recomendamos revisar os fundamentos de índices primários, índices secundários esparsos e índices de salto de dados, além de técnicas de gerenciamento do ciclo de vida dos dados, por exemplo, usando TTL.

O ClickStack oferece suporte à personalização do schema — você pode modificar tipos de coluna, extrair novos campos (por exemplo, de logs), aplicar codecs e dicionários, e acelerar consultas usando projeções.

Além disso, visões materializadas podem ser usadas para transformar ou filtrar dados durante a ingestão, desde que os dados sejam gravados na tabela de origem da visão e a aplicação leia da tabela de destino. Visões materializadas também podem ser usadas para acelerar consultas nativamente no ClickStack.

Para mais detalhes, consulte a documentação do ClickHouse sobre design de schema, estratégias de indexação e melhores práticas de gerenciamento de dados — a maior parte delas se aplica diretamente a implantações do ClickStack.

Navigation