Supervision des métriques de Temporal Cloud avec ClickStack

Supervision des métriques de Temporal Cloud avec ClickStack

Avertissement

La prise en charge d’OpenMetrics sur la plateforme Temporal est disponible en préversion publique. Consultez leur documentation pour plus d’informations.

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

TL;DR

Surveillez les métriques de Temporal Cloud dans ClickStack à l’aide du receiver Prometheus d’OTel. Inclut un tableau de bord préconfiguré.

​

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

1. ​

   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.

   Fichier de clé

   Assurez-vous que ces identifiants sont enregistrés dans un fichier temporal.key, dans le même répertoire que le fichier de configuration créé ci-dessous. Cette clé doit être enregistrée en texte brut, sans espace avant ou après.

2. ​

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

   Cette configuration :

   • Se connecte à Temporal Cloud à l’adresse metrics.temporal.io
   • Collecte des métriques toutes les 60 secondes
   • Collecte les principales métriques de performance
   • Définit l’attribut de ressource service.name requis conformément aux conventions sémantiques d’OpenTelemetry
   • Achemine les métriques vers l’exportateur ClickHouse via un pipeline dédié

   • Vous ne définissez que de nouveaux receivers, processeurs et pipelines dans la configuration personnalisée
   • Les processeurs memory_limiter et batch, ainsi que l’exportateur clickhouse, sont déjà définis dans la configuration de base de ClickStack ; il vous suffit de les référencer par leur nom
   • Le processeur resource définit l’attribut service.name requis conformément aux conventions sémantiques d’OpenTelemetry
   • Si vous avez plusieurs comptes Temporal Cloud, personnalisez service.name pour les distinguer (par exemple, "temporal-prod" et "temporal-dev")
3. ​

   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
   
4. ​

   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é

​

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.

1. ​

   la configuration du tableau de bord

2. ​

   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

   3. Téléversez le fichier temporal-metrics-dashboard.json, puis cliquez sur Finish Import
3. ​

   Afficher le tableau de bord

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

​

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

​

Mise 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 le point de terminaison OTLP de ClickStack. Consultez Envoi de données OpenTelemetry pour la configuration en production.