Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Supervision des métriques de Temporal Cloud avec ClickStack

View as MarkdownEdit this pageReport an issueSet up docs MCP

Temporal fournit une abstraction pour créer des applications simples, sophistiquées et résilientes.

Intégration avec une instance existante de Temporal Cloud

Cette section explique comment configurer ClickStack en configurant le ClickStack OTel collector avec le Prometheus receiver.

Prérequis

  • Instance ClickStack en cours de fonctionnement
  • Compte Temporal Cloud existant
  • Accès réseau HTTP depuis ClickStack vers votre Temporal Cloud

Créer une clé Temporal Cloud

Assurez-vous de disposer d’une clé d’API Temporal Cloud. Vous pouvez la créer en suivant le guide d’authentification de la documentation Temporal.

Créer une configuration personnalisée de l’OTel collector

ClickStack vous permet d’étendre la configuration de base de l’OpenTelemetry Collector en montant un fichier de configuration personnalisé et en définissant une variable d’environnement. La configuration personnalisée est fusionnée avec la configuration de base gérée par HyperDX via OpAMP.

Créez un fichier nommé temporal-metrics.yaml avec la configuration suivante :

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

Cette configuration :

Configurer ClickStack pour charger une configuration personnalisée

Pour activer une configuration personnalisée du collecteur dans votre déploiement ClickStack existant, vous devez :

  1. Monter le fichier de configuration personnalisé dans /etc/otelcol-contrib/custom.config.yaml
  2. Définir la variable d’environnement CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
  3. Monter le fichier temporal.key dans /etc/otelcol-contrib/temporal.key
  4. Assurer la connectivité réseau entre ClickStack et Temporal

Toutes les commandes partent du principe qu’elles sont exécutées depuis le répertoire d’exemple où sont stockés temporal-metrics.yaml et temporal.key.

Option 1 : Docker Compose

Mettez à jour la configuration de votre déploiement 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 ...
Option 2 : docker run (image tout-en-un)

Si vous utilisez l’image tout-en-un avec 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

Vérifier les métriques dans HyperDX

Une fois la configuration terminée, connectez-vous à HyperDX et vérifiez que les métriques remontent bien :

  1. Accédez à Metrics Explorer
  2. Recherchez les métriques commençant par temporal (par ex., temporal_cloud_v1_workflow_success_count, temporal_cloud_v1_poll_timeout_count)
  3. Vous devriez voir des points de données apparaître à l’intervalle de collecte configuré
Métriques Temporal

Tableaux de bord et visualisation

Pour vous aider à démarrer la surveillance de Temporal Cloud avec ClickStack, nous fournissons quelques exemples de visualisations pour les métriques Temporal.

Télécharger la configuration du tableau de bord

Télécharger le fichier de configuration du tableau de bord.

Importer le tableau de bord préconfiguré

  1. Ouvrez HyperDX et accédez à la section Dashboards
  2. Cliquez sur Import Dashboard dans l’angle supérieur droit, sous le menu à trois points
Bouton Import Dashboard
  1. Téléversez le fichier temporal-metrics-dashboard.json, puis cliquez sur Finish Import
Boîte de dialogue Finish Import

Afficher le tableau de bord

Le tableau de bord sera créé avec toutes les visualisations déjà configurées :

Tableau de bord des métriques Temporal

Dépannage

La configuration personnalisée ne se charge pas

Vérifiez que la variable d'environnement CUSTOM_OTELCOL_CONFIG_FILE est correctement définie :

docker exec <container-name> printenv CUSTOM_OTELCOL_CONFIG_FILE

Vérifiez que le fichier de configuration personnalisé est monté dans /etc/otelcol-contrib/custom.config.yaml :

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

Consultez le contenu de la configuration personnalisée pour vérifier qu'il est bien lisible :

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

Vérifiez que temporal.key est bien monté dans le conteneur :

docker exec <container-name> cat /etc/otelcol-contrib/temporal.key
# usually, docker exec clickstack cat /etc/otelcol-contrib/temporal.key
# This should output your temporal.key

Aucune métrique ne s’affiche dans HyperDX

Vérifiez que Temporal Cloud est accessible depuis le collector :

# From the ClickStack container
docker exec <container-name> curl -H "Authorization: Bearer <API_KEY>" https://metrics.temporal.io/v1/metrics

Vous devriez voir une série de métriques Prometheus s’afficher, par exemple.

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

Vérifiez que la configuration effective inclut votre receiver Prometheus :

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

Vérifiez les logs de l’agent collector pour y repérer des erreurs :

docker exec <container> cat /etc/otel/supervisor-data/agent.log | grep -i Prometheus
# Look for connection errors or authentication failures
# docker exec clickstack cat /etc/otel/supervisor-data/agent.log | grep -i Prometheus

Consultez les logs du collector :

docker exec <container> cat /var/log/otel-collector.log | grep -i error
# Look for config parsing errors - early supervisor.opamp-client can be ignored 
# docker exec clickstack cat /var/log/otel-collector.log | grep -i error

Erreurs d’authentification

Si vous voyez des erreurs d’authentification dans les logs, vérifiez votre clé API.

Problèmes de connectivité réseau

Si ClickStack ne parvient pas à joindre Temporal Cloud, assurez-vous que votre fichier Docker Compose ou vos commandes docker run autorisent l’accès au réseau externe.

Prochaines étapes

  • Configurez des alertes pour les métriques critiques (taux d’échec des workflows, croissance du backlog de tâches, latence entre la planification et le démarrage)
  • Créez des tableaux de bord supplémentaires pour des cas d’usage spécifiques (surveillance au niveau de l’espace de noms, performances par type de workflow)
  • Surveillez plusieurs comptes Temporal Cloud en dupliquant la configuration du receiver avec différents endpoints et noms de service

Passage en production

Ce guide utilise l’OpenTelemetry Collector intégré à ClickStack pour une mise en place rapide. Pour les déploiements en production, nous vous recommandons d’exécuter votre propre OTel Collector et d’envoyer les données vers l’endpoint OTLP de ClickStack. Consultez Envoyer des données OpenTelemetry pour la configuration de production.

Navigation