Monitoramento das métricas do Temporal Cloud com ClickStack

AvisoO suporte a OpenMetrics na plataforma Temporal está disponível em Prévia Pública. Consulte a documentação da Temporal para mais informações.

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

ResumoMonitore métricas da Temporal Cloud no ClickStack usando o receiver Prometheus do OTel. Inclui um dashboard pré-configurado.

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.

Arquivo da chaveCertifique-se de armazenar essas credenciais em um arquivo temporal.key no mesmo diretório do arquivo de configuração criado abaixo. Essa chave deve ser armazenada apenas como texto, sem espaços antes ou depois.

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.yaml

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:

Conecta ao Temporal Cloud em metrics.temporal.io
Coleta métricas a cada 60 segundos
Coleta métricas essenciais de desempenho
Define o atributo de recurso service.name obrigatório de acordo com as convenções semânticas do OpenTelemetry
Encaminha as métricas para o exportador do ClickHouse por meio de um pipeline dedicado

Na configuração personalizada, você define apenas novos receivers, processors e pipelines
Os processors memory_limiter e batch e o exportador clickhouse já estão definidos na configuração base do ClickStack — você só os referencia pelo nome
O processor resource define o atributo service.name obrigatório de acordo com as convenções semânticas do OpenTelemetry
Para várias contas do Temporal Cloud, personalize service.name para diferenciá-las (por exemplo, "temporal-prod" e "temporal-dev")

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:

Montar o arquivo de configuração personalizada em /etc/otelcol-contrib/custom.config.yaml
Definir a variável de ambiente CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
Montar o arquivo temporal.key em /etc/otelcol-contrib/temporal.key
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:
    # ... configuração existente ...
    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
      # ... outros 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:

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

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.

a configuração do dashboard

Importe o dashboard pré-configurado

Abra o HyperDX e vá até a seção Dashboards
Clique em Import Dashboard no canto superior direito, no menu de reticências

Faça upload do arquivo temporal-metrics-dashboard.json e clique em Finish Import

Visualize o dashboard

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

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

Colocando em produção

Este guia amplia 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 do OpenTelemetry para a configuração de produção.

Features

Guides

Monitoramento das métricas do Temporal Cloud com ClickStack

Integração com o Temporal Cloud existente

Pré-requisitos

Criar chave do Temporal Cloud

Crie uma configuração personalizada do OTel collector

Configure o ClickStack para carregar uma configuração personalizada

Opção 1: Docker Compose

Opção 2: Docker run (imagem all-in-one)

Verifique as métricas no HyperDX

Dashboards e visualizações

a configuração do dashboard

Importe o dashboard pré-configurado

Visualize o dashboard

Solução de problemas

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

Nenhuma métrica aparece no HyperDX

Erros de autenticação

Problemas de conectividade de rede

Próximos passos

Colocando em produção

​Integração com o Temporal Cloud existente

​Pré-requisitos

​Criar chave do Temporal Cloud

​Crie uma configuração personalizada do OTel collector

​Configure o ClickStack para carregar uma configuração personalizada

Opção 1: Docker Compose

Opção 2: Docker run (imagem all-in-one)

​Verifique as métricas no HyperDX

​Dashboards e visualizações

​ a configuração do dashboard

​Importe o dashboard pré-configurado

​Visualize o dashboard

​Solução de problemas

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

​Nenhuma métrica aparece no HyperDX

​Erros de autenticação

​Problemas de conectividade de rede

​Próximos passos

​Colocando em produção

Integração com o Temporal Cloud existente

Pré-requisitos

Criar chave do Temporal Cloud

Crie uma configuração personalizada do OTel collector

Configure o ClickStack para carregar uma configuração personalizada

Verifique as métricas no HyperDX

Dashboards e visualizações

a configuração do dashboard

Importe o dashboard pré-configurado

Visualize o dashboard

Solução de problemas

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

Nenhuma métrica aparece no HyperDX

Erros de autenticação

Problemas de conectividade de rede

Próximos passos

Colocando em produção