Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Мониторинг метрик Temporal Cloud с помощью ClickStack

View as MarkdownEdit this pageReport an issueSet up docs MCP

Temporal предоставляет абстракцию для создания как простых, так и сложных отказоустойчивых приложений.

Интеграция с существующим Temporal Cloud

В этом разделе описывается настройка ClickStack через конфигурирование коллектора ClickStack OTel с приёмником Prometheus.

Предварительные требования

  • Работающий экземпляр ClickStack
  • Действующая учетная запись Temporal Cloud
  • Сетевой доступ по HTTP из ClickStack в ваш Temporal Cloud

Создайте ключ Temporal Cloud

Убедитесь, что у вас есть API-ключ Temporal Cloud. Его можно создать, следуя руководству по аутентификации в документации Temporal.

Создайте пользовательскую конфигурацию OTel collector

ClickStack позволяет расширить базовую конфигурацию OpenTelemetry Collector, подключив собственный файл конфигурации и задав переменную окружения. Эта конфигурация объединяется с базовой конфигурацией, которой HyperDX управляет через OpAMP.

Создайте файл temporal-metrics.yaml со следующей конфигурацией:

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

Эта конфигурация:

Настройка ClickStack для загрузки пользовательской конфигурации

Чтобы включить пользовательскую конфигурацию коллектора в существующем развертывании ClickStack, необходимо:

  1. Смонтировать пользовательский файл конфигурации по пути /etc/otelcol-contrib/custom.config.yaml
  2. Установить переменную окружения CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
  3. Смонтировать файл temporal.key по пути /etc/otelcol-contrib/temporal.key
  4. Обеспечить сетевую связность между ClickStack и Temporal

Во всех командах предполагается, что они выполняются из каталога sample, в котором хранятся temporal-metrics.yaml и temporal.key.

Вариант 1: Docker Compose

Обновите конфигурацию развертывания 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 ...
Вариант 2: Docker run (образ «всё в одном»)

Если вы используете образ «всё в одном» с 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

Проверьте метрики в HyperDX

После настройки войдите в HyperDX и убедитесь, что метрики поступают:

  1. Перейдите в Metrics explorer
  2. Найдите метрики, начинающиеся с temporal (например, temporal_cloud_v1_workflow_success_count, temporal_cloud_v1_poll_timeout_count)
  3. Вы должны увидеть, как точки данных метрик появляются с заданным интервалом сбора
Метрики Temporal

Панели мониторинга и визуализация

Чтобы вам было проще начать мониторинг Temporal Cloud с помощью ClickStack, мы подготовили несколько примеров визуализаций для метрик Temporal.

Скачать конфигурацию панели мониторинга

Скачать конфигурацию панели мониторинга.

Импортируйте преднастроенный дашборд

  1. Откройте HyperDX и перейдите в раздел Dashboards
  2. Нажмите Import Dashboard в правом верхнем углу в меню с многоточием
Кнопка импорта панели мониторинга
  1. Загрузите файл temporal-metrics-dashboard.json и нажмите Finish Import
Диалог завершения импорта

Просмотрите панель мониторинга

Панель мониторинга будет создана со всеми преднастроенными визуализациями:

Панель мониторинга метрик Temporal

Устранение неполадок

Пользовательский config не загружается

Убедитесь, что переменная окружения CUSTOM_OTELCOL_CONFIG_FILE указана правильно:

docker exec <container-name> printenv CUSTOM_OTELCOL_CONFIG_FILE

Проверьте, что пользовательский файл конфигурации смонтирован в /etc/otelcol-contrib/custom.config.yaml:

docker exec <container-name> ls -lh /etc/otelcol-contrib/custom.config.yaml
# обычно: docker exec clickstack ls -lh /etc/otelcol-contrib/custom.config.yaml

Просмотрите содержимое пользовательской конфигурации, чтобы убедиться, что его можно прочитать:

docker exec <container-name> cat /etc/otelcol-contrib/custom.config.yaml
# обычно: docker exec clickstack cat /etc/otelcol-contrib/custom.config.yaml

Убедитесь, что файл temporal.key смонтирован в контейнер:

docker exec <container-name> cat /etc/otelcol-contrib/temporal.key
# обычно: docker exec clickstack cat /etc/otelcol-contrib/temporal.key
# Эта команда должна вывести содержимое вашего temporal.key

В HyperDX не отображаются метрики

Убедитесь, что Temporal Cloud доступен для коллектора:

# Из контейнера ClickStack
docker exec <container-name> curl -H "Authorization: Bearer <API_KEY>" https://metrics.temporal.io/v1/metrics

Вы должны увидеть ряд метрик Prometheus, например:

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

Убедитесь, что в эффективную конфигурацию входит ваш приёмник Prometheus:

docker exec <container> cat /etc/otel/supervisor-data/effective.yaml | grep -A 10 "Prometheus:"
## обычно: docker exec clickstack cat /etc/otel/supervisor-data/effective.yaml | grep -A 10 "prometheus:"

Проверьте журналы collector agent на наличие ошибок:

docker exec <container> cat /etc/otel/supervisor-data/agent.log | grep -i Prometheus
# Ищите ошибки подключения или сбои аутентификации
# docker exec clickstack cat /etc/otel/supervisor-data/agent.log | grep -i Prometheus

Проверьте журналы коллектора:

docker exec <container> cat /var/log/otel-collector.log | grep -i error
# Ищите ошибки разбора конфигурации — ранние ошибки supervisor.opamp-client можно игнорировать 
# docker exec clickstack cat /var/log/otel-collector.log | grep -i error

Ошибки аутентификации

Если в журналах появляются ошибки аутентификации, проверьте API-ключ.

Проблемы с сетевым подключением

Если ClickStack не удаётся подключиться к Temporal Cloud, убедитесь, что в вашем файле Docker Compose или командах docker run разрешён доступ к внешней сети.

Следующие шаги

  • Настройте оповещения для критически важных метрик (частота сбоев workflow, рост очереди задач, задержка от планирования до запуска)
  • Создайте дополнительные панели мониторинга для конкретных сценариев использования (мониторинг на уровне пространства имен, производительность разных типов workflow)
  • Отслеживайте несколько аккаунтов Temporal Cloud, дублируя конфигурацию приёмника с разными конечными точками и именами сервисов

Переход в продакшн

В этом руководстве для быстрой настройки используется встроенный в ClickStack OpenTelemetry Collector. Для развертываний в продакшне мы рекомендуем запускать собственный OTel Collector и отправлять данные в конечную точку OTLP ClickStack. Конфигурация для продакшна описана в разделе Отправка данных OpenTelemetry.

Navigation