Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Monitoramento das métricas do Temporal Cloud com ClickStack

View as MarkdownEdit this pageReport an issueSet up docs MCP

A Temporal oferece uma abstração para desenvolver aplicações simples, sofisticadas e resilientes.

Integração com o Temporal Cloud existente

Esta seção mostra como configurar o ClickStack usando o receiver Prometheus no OTel collector do ClickStack.

Pré-requisitos

  • Instância do ClickStack em execução
  • Conta existente no Temporal Cloud
  • Acesso à rede HTTP do ClickStack para o seu Temporal Cloud

Criar chave do Temporal Cloud

Certifique-se de ter uma API key do Temporal Cloud. Você pode criá-la seguindo o guia de autenticação na documentação do Temporal.

Crie uma configuração personalizada do OTel collector

O ClickStack permite estender a configuração básica do OpenTelemetry collector montando um arquivo de configuração personalizado e definindo uma variável de ambiente. A configuração personalizada é mesclada à configuração básica gerenciada pelo HyperDX via OpAMP.

Crie um arquivo chamado temporal-metrics.yaml com a seguinte configuração:

temporal-metrics.yamlyaml
receivers:
  prometheus/temporal:
    config:
      scrape_configs:
      - job_name: 'temporal-cloud'
        scrape_interval: 60s
        scrape_timeout: 30s
        honor_timestamps: true
        scheme: https
        authorization:
          type: Bearer
          credentials_file: /etc/otelcol-contrib/temporal.key
        static_configs:
          - targets: ['metrics.temporal.io']
        metrics_path: '/v1/metrics'

processors:
  resource:
    attributes:
      - key: service.name
        value: "temporal"
        action: upsert

service:
  pipelines:
    metrics/temporal:
      receivers: [prometheus/temporal]
      processors:
        - resource
        - memory_limiter
        - batch
      exporters:
        - clickhouse

Esta configuração:

Configure o ClickStack para carregar uma configuração personalizada

Para habilitar uma configuração personalizada do collector na implantação existente do ClickStack, você deve:

  1. Montar o arquivo de configuração personalizada em /etc/otelcol-contrib/custom.config.yaml
  2. Definir a variável de ambiente CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
  3. Montar o arquivo temporal.key em /etc/otelcol-contrib/temporal.key
  4. Garantir a conectividade de rede entre o ClickStack e o Temporal

Todos os comandos presumem que sejam executados a partir do diretório de exemplo, onde temporal-metrics.yaml e temporal.key estão armazenados.

Opção 1: Docker Compose

Atualize a configuração de implantação do ClickStack:

services:
  clickstack:
    # ... existing configuration ...
    environment:
      - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
    volumes:
      - ./temporal-metrics.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
      - ./temporal.key:/etc/otelcol-contrib/temporal.key:ro
      # ... other volumes ...
Opção 2: Docker run (imagem all-in-one)

Se estiver usando a imagem all-in-one com docker run:

docker run --name clickstack \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
  -v "$(pwd)/temporal-metrics.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v "$(pwd)/temporal.key:/etc/otelcol-contrib/temporal.key:ro" \
  clickhouse/clickstack-all-in-one:latest

Verifique as métricas no HyperDX

Após a configuração, faça login no HyperDX e verifique se as métricas estão sendo recebidas:

  1. Navegue até o explorador de métricas
  2. Pesquise por métricas que comecem com temporal (por exemplo, temporal_cloud_v1_workflow_success_count, temporal_cloud_v1_poll_timeout_count)
  3. Você deverá ver os pontos de dados das métricas aparecerem no intervalo de coleta configurado
Métricas do Temporal

Dashboards e visualizações

Para ajudar você a começar a monitorar o Temporal Cloud com o ClickStack, fornecemos algumas visualizações de exemplo para o Temporal Metrics.

Baixe a configuração do dashboard

Baixe o arquivo de configuração do dashboard.

Importe o dashboard pré-configurado

  1. Abra o HyperDX e vá até a seção Dashboards
  2. Clique em Import Dashboard no canto superior direito, no menu de reticências
Botão de importação de dashboard
  1. Faça upload do arquivo temporal-metrics-dashboard.json e clique em Finish Import
Caixa de diálogo para concluir a importação

Visualize o dashboard

O dashboard será criado com todas as visualizações pré-configuradas:

Dashboard do Temporal Metrics

Solução de problemas

A configuração personalizada não está sendo carregada

Verifique se a variável de ambiente CUSTOM_OTELCOL_CONFIG_FILE está definida corretamente:

docker exec <container-name> printenv CUSTOM_OTELCOL_CONFIG_FILE

Verifique se o arquivo de configuração personalizado está montado em /etc/otelcol-contrib/custom.config.yaml:

docker exec <container-name> ls -lh /etc/otelcol-contrib/custom.config.yaml
# geralmente, docker exec clickstack ls -lh /etc/otelcol-contrib/custom.config.yaml

Veja o conteúdo da configuração personalizada para verificar se está legível:

docker exec <container-name> cat /etc/otelcol-contrib/custom.config.yaml
# geralmente, docker exec clickstack cat /etc/otelcol-contrib/custom.config.yaml

Verifique se temporal.key está montado no contêiner:

docker exec <container-name> cat /etc/otelcol-contrib/temporal.key
# geralmente, docker exec clickstack cat /etc/otelcol-contrib/temporal.key
# Isso deve exibir o conteúdo do seu temporal.key

Nenhuma métrica aparece no HyperDX

Verifique se o Temporal Cloud está acessível a partir do coletor:

# Do contêiner do ClickStack
docker exec <container-name> curl -H "Authorization: Bearer <API_KEY>" https://metrics.temporal.io/v1/metrics

Você deverá ver uma série de métricas do Prometheus exibidas, por exemplo.

temporal_cloud_v1_workflow_success_count{operation="CompletionStats",region="aws-us-east-2",temporal_account="l2c4n",temporal_namespace="clickpipes-aws-prd-apps-us-east-2.l2c4n",temporal_task_queue="clickpipes-svc-dc118d12-b397-4975-a33e-c2888ac12ac4-peer-flow-task-queue",temporal_workflow_type="QRepPartitionWorkflow"} 0.067 1765894320

Verifique se a configuração efetiva inclui o receiver do Prometheus:

docker exec <container> cat /etc/otel/supervisor-data/effective.yaml | grep -A 10 "Prometheus:"
## geralmente, docker exec clickstack cat /etc/otel/supervisor-data/effective.yaml | grep -A 10 "prometheus:"

Verifique se há erros nos logs do agente do collector:

docker exec <container> cat /etc/otel/supervisor-data/agent.log | grep -i Prometheus
# Procure erros de conexão ou falhas de autenticação
# docker exec clickstack cat /etc/otel/supervisor-data/agent.log | grep -i Prometheus

Verifique os logs do collector:

docker exec <container> cat /var/log/otel-collector.log | grep -i error
# Procure erros de parsing de configuração - erros iniciais do supervisor.opamp-client podem ser ignorados 
# docker exec clickstack cat /var/log/otel-collector.log | grep -i error

Erros de autenticação

Se você vir erros de autenticação nos logs, verifique sua chave de API.

Problemas de conectividade de rede

Se o ClickStack não conseguir se conectar ao Temporal Cloud, verifique se o arquivo do Docker Compose ou os comandos docker run permitem conectividade de rede externa.

Próximos passos

  • Configure alertas para métricas críticas (taxas de falha de workflow, crescimento do backlog de tarefas, latência entre agendamento e início)
  • Crie dashboards adicionais para casos de uso específicos (monitoramento por espaço de nomes, desempenho por tipo de workflow)
  • Monitore várias contas do Temporal Cloud duplicando a configuração do receiver com diferentes endpoints e nomes de serviço

Em produção

Este guia usa o OpenTelemetry Collector integrado do ClickStack para uma configuração rápida. Para implantações em produção, recomendamos executar seu próprio OTel Collector e enviar os dados para o endpoint OTLP do ClickStack. Consulte Enviando dados com OpenTelemetry para a configuração de produção.

Navigation