Observabilidade do BYOC

As implantações BYOC incluem recursos completos de observabilidade, permitindo que você monitore seus serviços ClickHouse por meio de uma stack dedicada de monitoramento do Prometheus e de endpoints de métricas expostos diretamente pelos servidores ClickHouse. Todos os dados de observabilidade permanecem na sua conta na nuvem, dando a você controle total sobre sua infraestrutura de monitoramento.

O BYOC oferece duas formas principais de coletar e visualizar métricas com o Prometheus:

1. Conectar-se à stack integrada do Prometheus: Acesse a instância centralizada do Prometheus, pré-instalada e em execução no seu cluster Kubernetes do BYOC.
2. Coletar métricas do ClickHouse diretamente: Aponte sua própria implantação do Prometheus para o endpoint /metrics_all exposto por cada serviço do ClickHouse.

Recomendação: Para a maioria dos casos de uso, recomendamos a integração com a stack do Prometheus integrada, pois ela fornece métricas abrangentes de todos os componentes da sua implantação BYOC (serviços ClickHouse, cluster Kubernetes e serviços de suporte), em vez de apenas métricas do servidor ClickHouse.

O ClickHouse BYOC implanta uma stack completa de monitoramento com Prometheus no seu cluster Kubernetes, incluindo Prometheus, Grafana, AlertManager e, opcionalmente, Thanos para armazenamento de métricas de longo prazo. Essa stack coleta métricas de:

• servidores ClickHouse e ClickHouse Keeper
• componentes do sistema e do cluster Kubernetes
• nós da infraestrutura subjacente

Para se conectar à stack do Prometheus integrada:

1. Habilite o balanceador de carga privado da sua infraestrutura BYOC no console do ClickHouse Cloud (consulte Balanceadores de carga).
2. Solicite a URL do endpoint do Prometheus ao suporte do ClickHouse.
3. Verifique a conectividade de rede privada com o endpoint do Prometheus — normalmente por meio de peering de VPC/VNet ou outra configuração de rede privada.

Os formatos de endpoint variam conforme o tipo de conectividade:

<cloud> pode ser aws, gcp ou azure. Para endpoints privados, <label> é específico da nuvem: vpce na AWS, p no GCP e privatelink no Azure.

Você pode usar a stack do Prometheus do BYOC no seu ecossistema de monitoramento de várias maneiras:

Opção 1: consultar a API do Prometheus

• Acesse diretamente o endpoint da API do Prometheus pela sua plataforma de monitoramento preferida ou por dashboards personalizados.
• Use consultas PromQL para extrair, agregar e visualizar as métricas de que você precisa.
• Ideal para criar dashboards personalizados ou pipelines de alertas.

Endpoint de consulta do Prometheus /query:

https://prometheus-internal.<subdomain>.<region>.<cloud>.clickhouse-byoc.com/query

Opção 2: Federar métricas para sua própria instância do Prometheus

• Configure sua instância externa do Prometheus para federar (extrair) métricas da stack do Prometheus do ClickHouse BYOC.
• Isso permite unificar e centralizar a coleta de métricas de vários ambientes ou clusters.
• Exemplo de configuração de federação do Prometheus:

scrape_configs:
  - job_name: 'federate-clickhouse-byoc'
    scrape_interval: 15s
    honor_labels: true
    metrics_path: '/federate'
    params:
      'match[]':
        - '{job="clickhouse"}'
        - '{job="kubernetes"}'
    static_configs:
      - targets:
        - 'prometheus-internal.<subdomain>.<region>.<cloud>.clickhouse-byoc.com'

Os serviços ClickHouse expõem um endpoint de métricas compatível com o Prometheus, que você pode coletar diretamente usando sua própria instância do Prometheus. Essa abordagem fornece métricas específicas do ClickHouse, mas não inclui métricas do Kubernetes nem dos serviços de suporte.

O endpoint de métricas está disponível em /metrics_all no endpoint do seu serviço ClickHouse:

curl --user <username>:<password> https://<service-subdomain>.<byoc-subdomain>.<region>.<provider>.clickhouse-byoc.com:8443/metrics_all

Exemplo de resposta:

# HELP ClickHouse_CustomMetric_StorageSystemTablesS3DiskBytes The amount of bytes stored on disk `s3disk` in system database
# TYPE ClickHouse_CustomMetric_StorageSystemTablesS3DiskBytes gauge
ClickHouse_CustomMetric_StorageSystemTablesS3DiskBytes{hostname="c-jet-ax-16-server-43d5baj-0"} 62660929
# HELP ClickHouse_CustomMetric_NumberOfBrokenDetachedParts The number of broken detached parts
# TYPE ClickHouse_CustomMetric_NumberOfBrokenDetachedParts gauge
ClickHouse_CustomMetric_NumberOfBrokenDetachedParts{hostname="c-jet-ax-16-server-43d5baj-0"} 0
# HELP ClickHouse_CustomMetric_TotalNumberOfErrors The total number of errors on server since the last restart
# TYPE ClickHouse_CustomMetric_TotalNumberOfErrors gauge
ClickHouse_CustomMetric_TotalNumberOfErrors{hostname="c-jet-ax-16-server-43d5baj-0"} 9

O endpoint de métricas exige autenticação com credenciais do ClickHouse. Recomendamos usar o usuário default ou criar um usuário dedicado com permissões mínimas especificamente para a coleta de métricas.

Permissões necessárias:

• permissão REMOTE para se conectar ao serviço
• permissões SELECT nas tabelas de sistema relevantes

Exemplo de configuração de usuário:

CREATE USER scrapping_user IDENTIFIED BY 'secure_password';
GRANT REMOTE ON *.* TO scrapping_user;
GRANT SELECT ON system._custom_metrics_dictionary_custom_metrics_tables TO scrapping_user;
GRANT SELECT ON system._custom_metrics_dictionary_database_replicated_recovery_time TO scrapping_user;
GRANT SELECT ON system._custom_metrics_dictionary_failed_mutations TO scrapping_user;
GRANT SELECT ON system._custom_metrics_dictionary_group TO scrapping_user;
GRANT SELECT ON system._custom_metrics_dictionary_shared_catalog_recovery_time TO scrapping_user;
GRANT SELECT ON system._custom_metrics_dictionary_table_read_only_duration_seconds TO scrapping_user;
GRANT SELECT ON system._custom_metrics_view_error_metrics TO scrapping_user;
GRANT SELECT ON system._custom_metrics_view_histograms TO scrapping_user;
GRANT SELECT ON system._custom_metrics_view_metrics_and_events TO scrapping_user;
GRANT SELECT(description, metric, value) ON system.asynchronous_metrics TO scrapping_user;
GRANT SELECT ON system.custom_metrics TO scrapping_user;
GRANT SELECT(name, value) ON system.errors TO scrapping_user;
GRANT SELECT(description, event, value) ON system.events TO scrapping_user;
GRANT SELECT(description, labels, metric, value) ON system.histogram_metrics TO scrapping_user;
GRANT SELECT(description, metric, value) ON system.metrics TO scrapping_user;

Configure sua instância do Prometheus para coletar as métricas expostas no endpoint de métricas do ClickHouse:

global:
  scrape_interval: 15s

scrape_configs:
  - job_name: "clickhouse"
    static_configs:
      - targets: ["<service-subdomain>.<byoc-subdomain>.<region>.<provider>.clickhouse-byoc.com:8443"]
    scheme: https
    metrics_path: "/metrics_all"
    basic_auth:
      username: <username>
      password: <password>
    honor_labels: true

Substitua:

• <service-subdomain>.<byoc-subdomain>.<region>.<provider>.clickhouse-byoc.com:8443 pelo endpoint do seu serviço
• <username> e <password> pelas credenciais do seu usuário de coleta

Para equipes que desejam um conjunto pronto de dashboards, o ClickHouse oferece um ClickHouse Mixin para o Prometheus. Trata-se de um dashboard pré-configurado do Grafana, projetado especificamente para monitorar clusters do ClickHouse.

Depois que sua instância do Prometheus estiver integrada à stack de monitoramento do ClickHouse, você poderá visualizar as métricas no Grafana seguindo estas etapas:

1. Adicione o Prometheus como fonte de dados no Grafana Vá para "Fontes de dados" na barra lateral do Grafana, clique em "Adicionar fonte de dados" e selecione "Prometheus". Insira a URL da sua instância do Prometheus e as credenciais necessárias para se conectar.

2. Importe o dashboard do ClickHouse No Grafana, navegue até a área de dashboards e escolha "Importar". Você pode fazer upload do arquivo JSON do dashboard ou colar o conteúdo dele diretamente. Obtenha o arquivo JSON no repositório do ClickHouse mixin: JSON do dashboard do ClickHouse Mix-in

3. Explore suas métricas Depois que o dashboard for importado e configurado com sua fonte de dados do Prometheus, você verá métricas em tempo real dos seus serviços do ClickHouse Cloud.