跳转至

Studio 自观测配置与指标说明

本文用于说明部署版 Studio 侧如何确认自观测配置是否开启，以及自观测指标集 df_studio 中与 API、Celery 异步任务、Redis/Broker、业务任务和导出链路相关的指标、标签、单位与监控建议。

适用版本

  • 自观测主动指标能力从 2026 年 5 月 20 日发布版本开始提供。
  • 2026 年 5 月 13 日发布版本尚不支持该主动指标能力。
  • 飞书问题单中已确认最新部署版 v1.130.225 已支持该能力；该版本对应 Studio 当前系统 commit 60a71d992，本文指标和配置已按该 commit 核对。
  • 如果环境低于 v1.130.225，建议先升级后再配置。

采集链路

Studio 应用侧不会主动把指标推送到外部服务。推荐链路是：

Studio API / Celery / WebSocket / Snapshot
  -> 应用内轻量记录指标
  -> Redis 指标缓存
  -> inner /metrics Prometheus 文本出口
  -> Datakit 定时拉取
  -> 自观测工作空间
  -> 仪表板 / 监控器 / 告警

Datakit 拉取地址：

http://<inner-service-ip>:5000/api/v1/inner/metrics?from=datakit&type=df_studio

Prometheus 文本出口会输出完整指标名，例如 df_studio_celery_task_published_total。在观测云 UI 或 DQL 中，通常按“指标集 + 字段”查询，即指标集为 df_studio，字段为 celery_task_published_total。

如何检查自观测配置是否开启

1. 检查 Studio 后端配置

Studio 后端配置项为 SelfMonitorMetricsSet。默认关闭，用户只需要显式开启 enable：

SelfMonitorMetricsSet:
  enable: true

其他配置保持默认即可，含义如下：

配置项 默认值 单位 说明
enable false 布尔值 自观测统一开关。只有为 true 时，API、Celery、业务任务和 /metrics 导出相关指标才会记录。
expireSeconds 3600 秒 周期增量指标在 Redis 中的保留窗口。
stateExpireSeconds 604800 秒 beat 最近发布时间、业务任务最近成功/失败等状态类指标保留窗口。
beatMissedLagThresholdSeconds 300 秒 判断 beat 发布后未开始执行的默认滞后阈值。
beatMissedIntervalMultiplier 2 倍数 判断低频 beat 是否漏调度时使用的最近发布间隔倍数。
celeryQueues celery、correlation_task、snapshot_queue、compute_task 列表 需要读取队列长度和最老等待时间的 Celery 队列。

也可以通过环境变量覆盖：

STUDIO__SelfMonitorMetricsSet__enable=true

注意：enable 必须是布尔语义的 true 或 false。非法字符串或 null 会导致配置加载失败。

2. 检查 /metrics 是否输出自观测指标

在集群内访问 inner 服务：

curl 'http://management-backend.forethought-core:5000/api/v1/inner/metrics?from=datakit&type=df_studio'

如果已开启并且导出正常，响应中应能看到类似内容：

df_studio_self_monitor_export_total{exporter="prometheus_inner",result="success"} 1
df_studio_self_monitor_export_duration_seconds{exporter="prometheus_inner",result="success"} ...
df_studio_self_monitor_export_last_success_timestamp_seconds{exporter="prometheus_inner"} ...

如果导出发生异常，接口会 fail-open，仍尽量返回失败指标：

df_studio_self_monitor_export_total{exporter="prometheus_inner",result="failure"} 1
df_studio_self_monitor_export_error_total{exception_type="...",exporter="prometheus_inner"} 1
df_studio_self_monitor_export_last_failure_timestamp_seconds{exception_type="...",exporter="prometheus_inner"} ...

3. 检查历史健康检查接口

管理后台仍保留 Celery worker 健康检查接口：

curl 'http://management-backend.forethought-core:5000/api/v1/const/celery/ping'

该接口读取 Redis 中的 celery_active_point，返回各队列最近一次活跃时间。返回 200 表示在配置的有效偏移时间内有活跃点；返回 400 通常表示对应 worker 长时间未更新活跃点，可能存在 worker 未运行、任务堆积、Redis/Broker 连接异常等情况。

该接口适合作为兼容健康检查；完整自观测建议优先使用下文的 df_studio 指标。

指标与标签约定

全局标签

标签 适用范围 含义 常见取值 使用建议
service API 服务入口名称 front、inner、openapi、admin、external、center、aiapi、sse 低基数，可用于总览。
run_app_code API 当前进程运行入口 同 service 低基数，可用于区分入口。
route_rule API Flask route rule /api/v1/... 比原始 URL 更适合聚合。
method API HTTP 方法 GET、POST、PUT 低基数。
status_class API HTTP 状态码族 2xx、4xx、5xx 用于成功率、错误率。
queue Celery Celery 队列名 celery、correlation_task、snapshot_queue、compute_task 低基数，异步任务总览核心维度。
task Celery / 业务任务 Celery task 名或业务任务名 forethought.tasks...、statistics_upload 中等基数，用于任务级排障。
status Celery 任务结束状态 success、failure、retry 用于任务质量分析。
exception_type Celery / 导出链路 异常类型 TimeoutError、OperationalError 用于异常 TopN。
beat_name Celery beat beat 条目名 配置中的 beat entry 名称 用于判断定时任务是否漏调度。
domain 业务任务 业务域 archive_report、incidents、billing、cleanup 低基数，业务任务总览主维度。
result 业务任务 / 导出链路 执行结果 success、error、failure、partial_success、skipped 用于成功率和失败率。
item_type 业务任务 处理对象类型 workspace、report_task、notification 低基数。
reason 业务任务 局部失败原因 notify_failed、item_error 控制枚举后可用于告警。
entry 独立入口 非 Flask 入口 websocket、snapshot 用于独立入口健康。
event 独立入口 入口事件 connect、disconnect、send_task 用于入口事件分析。
state 当前态指标 状态名 size、checked_out、overflow 具体含义依赖指标。
exporter /metrics 导出 导出器名称 prometheus_inner 低基数。
le Histogram bucket 桶上界 0.1、1、5、+Inf 仅用于 _bucket 指标计算分位数。

le 表示 histogram bucket 的小于等于上界，不是业务维度。例如 le="1" 表示小于等于 1 秒的样本累计数，le="+Inf" 表示所有样本数。

API 指标

指标字段 单位 标签 含义
api_request_count 次 service、api_path 兼容旧 API 非 5xx 请求量。
api_request_error_count 次 service、api_path 兼容旧 API 5xx 请求量。
api_requests_total 次 service、run_app_code、route_rule、method、status_class API 请求总量，周期增量。
api_errors_total 次 service、run_app_code、route_rule、method、status_class、error_type API 错误量，当前主要覆盖 HTTP 5xx。
api_duration_seconds_bucket 秒 service、run_app_code、route_rule、method、status_class、le API 请求耗时分布。
api_duration_seconds_sum 秒 service、run_app_code、route_rule、method、status_class API 请求耗时总和。
api_duration_seconds_count 次 service、run_app_code、route_rule、method、status_class API 请求耗时样本数。

Celery 队列与任务指标

以下指标在 commit 60a71d992 中已通过 Celery signals 写入，并由 df_studio 指标集导出。worker_queue_count 和 celery_queue_oldest_wait_seconds 直接读取 Redis broker 队列，用于发现 Redis/Broker 队列积压或 worker 不消费；Celery 任务生命周期指标用于进一步区分“未开始消费”和“开始后卡住”。

指标字段 单位 标签 含义
worker_queue_count 个 queue Redis broker 队列当前长度。
celery_queue_oldest_wait_seconds 秒 queue 队列中最老任务从发布到当前的等待时间。
celery_task_published_total 次 task、queue Celery 任务发布次数。
celery_task_started_total 次 task、queue Celery 任务开始执行次数。
celery_task_finished_total 次 task、queue、status Celery 任务结束次数，按状态区分。
celery_task_active 个 task、queue 当前正在执行的 Celery 任务数量。
celery_task_duration_seconds_bucket 秒 task、queue、le 任务执行耗时分布。
celery_task_duration_seconds_sum 秒 task、queue 任务执行耗时总和。
celery_task_duration_seconds_count 次 task、queue 任务执行耗时样本数。
celery_task_queue_wait_seconds_bucket 秒 task、queue、le 任务从发布到开始执行的排队等待耗时分布。
celery_task_queue_wait_seconds_sum 秒 task、queue 任务排队等待耗时总和。
celery_task_queue_wait_seconds_count 次 task、queue 任务排队等待耗时样本数。
celery_task_failure_exception_total 次 task、queue、exception_type 任务失败异常类型分布。
celery_task_timeout_total 次 task、queue、timeout_type Celery soft/hard timeout 次数。
celery_task_retry_total 次 task、queue、exception_type 任务重试次数。
celery_task_retry_delay_seconds_bucket 秒 task、queue、le 任务重试延迟分布。
celery_task_retry_delay_seconds_sum 秒 task、queue 任务重试延迟总和。
celery_task_retry_delay_seconds_count 次 task、queue 任务重试延迟样本数。

Beat 和定时任务指标

指标字段 单位 标签 含义
celery_beat_task_last_publish_timestamp_seconds Unix 秒 beat_name、task beat 条目最近一次发布任务时间。
celery_beat_task_last_started_timestamp_seconds Unix 秒 beat_name、task beat 条目对应任务最近一次开始执行时间。
celery_beat_lag_seconds 秒 beat_name、task beat 发布任务到 worker 开始执行的滞后。
celery_beat_publish_interval_seconds 秒 beat_name、task beat 条目最近两次发布之间的实际间隔。
celery_beat_missed 布尔值 beat_name、task 是否疑似漏调度，1 表示疑似漏调度。

业务任务指标

指标字段 单位 标签 含义
business_task_runs_total 次 domain、task、result 业务任务运行次数。
business_task_items_total 个 domain、task、item_type、result 业务任务处理对象数量。
business_task_duration_seconds_bucket 秒 domain、task、result、le 业务任务端到端耗时分布。
business_task_duration_seconds_sum 秒 domain、task、result 业务任务端到端耗时总和。
business_task_duration_seconds_count 次 domain、task、result 业务任务端到端耗时样本数。
business_task_last_success_timestamp_seconds Unix 秒 domain、task 业务任务最近一次成功时间。
business_task_last_failure_timestamp_seconds Unix 秒 domain、task、exception_type 业务任务最近一次失败时间。
business_task_partial_failure_total 次 domain、task、reason 任务未整体失败但存在局部失败的次数。

当前已接入的业务域包括：

domain 典型任务 关注点
archive_report 归档报告 v2/v3、首周期通知、延迟通知 报告触发、截图、通知是否成功，是否存在局部失败。
incidents 故障值班策略分析、故障队列同步、故障通知发送 故障通知链路是否成功、是否积压。
billing 账单统计上报 是否准点、是否成功、处理工作空间数量。
workspace_usage OpenAPI API Key 用量刷库 用量刷新是否成功，处理 bucket 和 access key 数量。
cleanup 仪表板历史清理等 清理任务是否长期失败或跳过。
sync_config 集成模板同步 配置同步是否成功。
notification Status Page 状态变更通知 通知任务是否成功或失败。
keyevent 关键事件未恢复异步查询 关键事件异步查询是否异常。
cloud_collector 云采集器异步操作 异步操作拆分、锁等待、成功失败。
catalog 统一目录实体健康度 实体健康度任务是否准点、成功和处理量是否异常。
snapshot 仪表板截图、图表截图、图表数据生成 快照服务截图/图表数据任务结果。

独立入口和依赖健康指标

指标字段 单位 标签 含义
service_entry_events_total 次 entry、event、result WebSocket、snapshot 等非 Flask 入口事件次数。
service_entry_active 个/布尔值 entry、state 非 Flask 入口当前活跃状态。
dependency_db_pool_connections 个 pool、state exporter 所在进程数据库连接池当前状态，state 包含 size、checked_in、checked_out、overflow。
self_monitor_export_total 次 exporter、result /metrics 本次导出结果。
self_monitor_export_points_total 个 exporter、result /metrics 本次成功导出的 Prometheus 样本数。
self_monitor_export_duration_seconds 秒 exporter、result /metrics 本次导出耗时。
self_monitor_export_last_success_timestamp_seconds Unix 秒 exporter 最近一次成功导出时间。
self_monitor_export_last_failure_timestamp_seconds Unix 秒 exporter、exception_type 最近一次 fail-open 失败导出时间。
self_monitor_export_error_total 次 exporter、exception_type 本次 fail-open 失败事件。

异步任务和 Redis/Broker 监控建议

客户关注的“异步任务是否异常、Redis 是否断开、worker 是否卡死”不能只看单个指标，建议按组合条件判断。

场景 优先观察指标 推荐维度 判读方式
worker 不消费或消费能力不足 worker_queue_count、celery_queue_oldest_wait_seconds、celery_task_published_total、celery_task_started_total queue、task 队列长度和最老等待时间持续上升，published 有增长但 started 很低，通常说明 worker 未消费、消费不足或与 broker 连接异常。
Redis/Broker 可读但 worker 断开 worker_queue_count、celery_queue_oldest_wait_seconds、celery_task_active queue exporter 能读到队列，队列积压上升，但 active 长期为 0 或明显偏低，优先怀疑 worker 侧断连、挂起或未启动。
Redis/Broker 完全不可用或 exporter 读取失败 self_monitor_export_total、self_monitor_export_error_total、self_monitor_export_last_failure_timestamp_seconds、self_monitor_export_points_total exporter、exception_type 如果 /metrics fail-open、失败时间刷新、样本数明显下降，说明采集链路自身可能访问 Redis、DB 或指标源失败。
任务开始后卡死不结束 celery_task_active、celery_task_started_total、celery_task_finished_total、celery_task_duration_seconds_bucket queue、task active 长时间不下降，started 增加但 finished 不增加，或耗时 P99 持续升高，说明任务可能卡在外部调用、锁、DB 或循环逻辑。
任务失败或重试风暴 celery_task_finished_total、celery_task_failure_exception_total、celery_task_retry_total、celery_task_retry_delay_seconds_bucket task、exception_type failure/retry 同时升高，且异常类型集中，说明任务可能进入失败重试循环。
beat 正常发布但 worker 未开始 celery_beat_task_last_publish_timestamp_seconds、celery_beat_task_last_started_timestamp_seconds、celery_beat_lag_seconds、celery_beat_missed beat_name、task last_publish 更新但 last_started 不更新，lag 升高或 missed=1，说明定时任务已投递但 worker 未开始消费。
beat 停发或低频任务漏调度 celery_beat_publish_interval_seconds、celery_beat_task_last_publish_timestamp_seconds、celery_beat_missed beat_name、task publish interval 超出历史周期或 last_publish 过旧，说明 beat 可能停止、配置未启用或调度器异常。
业务任务整体成功但部分对象失败 business_task_partial_failure_total、business_task_items_total、business_task_runs_total domain、task、reason、item_type partial failure 增加但整体任务可能仍为 partial_success，需要看具体业务对象失败原因。
业务任务长时间无成功 business_task_last_success_timestamp_seconds、business_task_last_failure_timestamp_seconds、business_task_runs_total domain、task last_success 距当前时间过久，且 last_failure 更新或 runs 无 success，说明该业务链路可能静默失败。

推荐至少建立以下告警：

告警项 建议级别 建议条件
自监控导出失败 P0 self_monitor_export_total{result="failure"} 或 self_monitor_export_error_total 出现。
自监控长时间无成功 P0 当前时间减 self_monitor_export_last_success_timestamp_seconds 超过 2 到 3 个 Datakit 拉取周期。
Celery 队列积压 P0 worker_queue_count 持续超过阈值，或 celery_queue_oldest_wait_seconds 持续超过业务可接受等待时间。
worker 疑似不消费 P0 celery_task_published_total 有增长，但 celery_task_started_total 长时间无增长，同时队列长度或最老等待时间上升。
worker 疑似卡死 P0 celery_task_active 长时间大于 0 且不下降，celery_task_finished_total 不增长，任务耗时 P99 持续升高。
beat 漏调度 P0 celery_beat_missed=1，或 celery_beat_lag_seconds 超过任务可接受阈值。
Celery 任务失败率升高 P1 celery_task_finished_total{status!="success"} 占比连续多个周期超过阈值。
Celery 重试风暴 P1 celery_task_retry_total 连续升高，并集中在同一 task 或 exception_type。
业务任务长时间无成功 P0/P1 关键任务长时间没有更新 business_task_last_success_timestamp_seconds。
DB pool 接近耗尽 P1 dependency_db_pool_connections{state="checked_out"} 接近 state="size"，或 state="overflow" > 0 持续出现。

常用 DQL 示例

查看各队列当前积压：

M::`df_studio`:(max(`worker_queue_count`)) BY `queue`

查看各队列最老任务等待时间：

M::`df_studio`:(max(`celery_queue_oldest_wait_seconds`)) BY `queue`

查看任务发布和开始执行的差异：

M::`df_studio`:(sum(`celery_task_published_total`), sum(`celery_task_started_total`)) BY `queue`,`task`

查看任务失败异常 TopN：

M::`df_studio`:(sum(`celery_task_failure_exception_total`)) BY `task`,`exception_type`

查看 beat 是否漏调度：

M::`df_studio`:(max(`celery_beat_missed`), max(`celery_beat_lag_seconds`)) BY `beat_name`,`task`

查看自监控导出状态：

M::`df_studio`:(max(`self_monitor_export_total`), max(`self_monitor_export_points_total`), max(`self_monitor_export_duration_seconds`)) BY `exporter`,`result`

查看业务任务最近成功时间：

M::`df_studio`:(max(`business_task_last_success_timestamp_seconds`)) BY `domain`,`task`

与现有自观测文档的关系

部署版完整自观测部署流程请参考同目录下的《开启部署版自身的可观测》。该文档覆盖 DataKit 部署、Prometheus 拉取配置、APM、RUM、拨测、监控器和模板导入等通用步骤。本文只补充 Studio 后端自身输出的 df_studio 指标、配置开关、标签单位和异步任务/Redis/Broker 监控口径。

文档评价

文档内容是否对您有帮助？ ×