跳转到主要内容
警告Temporal 平台对 OpenMetrics 的支持目前处于公开预览阶段。更多信息请参阅官方文档。
Temporal 提供了一个抽象层，用于构建从简单到复杂且具备弹性的应用程序。
简而言之使用 OTel Prometheus receiver 在 ClickStack 中监控 Temporal Cloud 指标。包含一个预置仪表盘。

​
与现有 Temporal Cloud 集成

本节将介绍如何通过为 ClickStack OTel collector 配置 Prometheus receiver 来配置 ClickStack。

​
前置条件

  • 正在运行的 ClickStack 实例
  • 已有 Temporal Cloud 账户
  • ClickStack 能够通过 HTTP 访问你的 Temporal Cloud
1

​
创建 Temporal Cloud 密钥

请确保您已拥有 Temporal Cloud API 密钥。您可以按照 Temporal 文档中的身份验证指南创建该密钥。
密钥文件请确保将这些凭据存储在名为 temporal.key 的文件中，且该文件与下文创建的配置文件位于同一目录。此密钥应以纯文本形式存储，前后不要有任何空格。
2

​
创建自定义 OTel collector 配置

ClickStack 允许你通过挂载自定义配置文件并设置环境变量，扩展基础 OpenTelemetry collector 配置。自定义配置会与 HyperDX 通过 OpAMP 管理的基础配置合并。创建一个名为 temporal-metrics.yaml 的文件，内容如下：
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
此配置：
  • 连接到 metrics.temporal.io 上的 Temporal Cloud
  • 每 60 秒采集一次指标
  • 采集关键性能指标
  • 按照 OpenTelemetry 语义约定设置必需的 service.name 资源属性
  • 通过专用管道将指标路由到 ClickHouse 导出器
  • 你只需在自定义配置中定义新的接收器、处理器和管道
  • memory_limiter 和 batch 处理器以及 clickhouse 导出器已在基础 ClickStack 配置中定义好，你只需按名称引用它们
  • resource 处理器会按照 OpenTelemetry 语义约定设置必需的 service.name 属性
  • 如果有多个 Temporal Cloud 账户，请自定义 service.name 以区分它们 (例如："temporal-prod"、"temporal-dev")
3

​
配置 ClickStack 以加载自定义配置

要在现有的 ClickStack 部署中启用自定义 collector 配置，必须：
  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 之间的网络连通
以下所有命令都假定在示例目录中执行，即存放 temporal-metrics.yaml 和 temporal.key 的目录。
选项 1：Docker Compose
更新您的 ClickStack 部署配置：
services:
  clickstack:
    # ... 现有配置 ...
    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
      # ... 其他卷 ...
选项 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
4

​
在 HyperDX 中验证指标

配置完成后，登录 HyperDX 并确认指标已开始流入：
  1. 进入 Metrics 浏览器
  2. 搜索以 temporal 开头的指标 (例如：temporal_cloud_v1_workflow_success_count、temporal_cloud_v1_poll_timeout_count)
  3. 你应能看到指标数据点按所配置的采集间隔持续出现

​
仪表盘和可视化

为帮助你开始使用 ClickStack 监控 Temporal Cloud，我们提供了一些用于 Temporal 指标的示例可视化。
1

​
仪表盘配置

2

​
导入预构建仪表盘

  1. 打开 HyperDX，并进入“仪表盘”部分
  2. 点击右上角省略号菜单中的 导入仪表盘
  1. 上传 temporal-metrics-dashboard.json 文件，然后点击 完成导入
3

​
查看仪表盘

系统会创建该仪表盘，并预先配置好所有可视化：

​
故障排查

​
自定义配置未正确加载

请确认环境变量 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 中未显示任何指标

验证 collector 能否访问 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 receiver： 
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
查看 collector 日志： 
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 命令已启用外部网络。

​
后续步骤

  • 为关键指标 (工作流失败率、任务积压增长、从调度到启动的延迟) 设置告警
  • 为特定用例创建额外的仪表盘 (命名空间级监控、工作流类型性能)
  • 通过复制 receiver 配置并为其指定不同的端点和服务名称，监控多个 Temporal Cloud 账户

​
用于生产环境

本指南在 ClickStack 内置的 OpenTelemetry Collector 基础上进行了扩展，便于快速完成设置。对于生产环境部署，我们建议运行您自己的 OTel collector，并将数据发送到 ClickStack 的 OTLP 端点。有关生产环境配置，请参阅发送 OpenTelemetry 数据。
最后修改于 2026年6月10日