Prometheus 指标命名需遵循蛇形命名法、固定前缀、对象_行为_单位结构、标准化单位、标签维度可控、后缀匹配类型等规范。例如 dify_api_requests_total、dify_task_execution_duration_seconds，禁用驼峰、缩写、无前缀、动态高基数标签及模糊单位。

Prometheus 指标命名不是随意拼凑，而是有明确结构和语义约束的工程实践。规范的命名能直接提升查询效率、降低告警误报率，并让新成员快速理解监控意图。

指标名必须用蛇形命名法 + 明确前缀

全部小写字母，单词间用下划线连接；前缀体现服务或系统归属，避免全局冲突。Dify 统一使用 dify_ 开头，其他服务也应固定前缀（如 user_service_、payment_gateway_）。

• ✅ 推荐：dify_api_requests_total、payment_gateway_refund_duration_seconds
• ❌ 避免：DifyApiRequestsTotal（驼峰）、api_req_cnt（缩写歧义）、requests_total（无前缀，易冲突）

名称结构应体现“对象_行为_单位”逻辑

指标名本身不承载维度信息，只表达度量本质。单位必须标准化：时间统一用 seconds，大小统一用 bytes，计数统一用 total（Counter）或 count（Gauge）。

• ✅ 清晰可读：dify_task_execution_duration_seconds（任务执行耗时，单位秒）
• ✅ 语义完整：dify_cache_hits_total（缓存命中次数，单调递增）
• ❌ 单位模糊：request_time_ms（毫秒非标准）、queue_size（未说明是当前值还是累计）

标签用于维度切分，严禁嵌入动态值

标签是 Prometheus 多维分析的核心，但设计不当会引发高基数问题。应只保留有限、稳定、有聚合意义的维度，如 method、status、endpoint；绝不能将用户 ID、请求 ID、长文本参数作为标签。

• ✅ 安全维度：dify_api_requests_total{method="post", status="200", endpoint="/v1/chat"}
• ❌ 高风险标签：user_id="abc123"（百万用户 → 百万时间序列）、trace_id="xyz789"（唯一值，完全无法聚合）
• ? 替代方案：高频动态值应记录在日志或链路追踪系统中，而非 Prometheus 标签

按指标类型选择后缀，保持语义一致

后缀反映指标行为特征，有助于快速识别用途和使用方式：

• _total：仅用于 Counter 类型（累计值），如 dify_worker_jobs_processed_total
• _seconds：Histogram 或 Summary 的耗时类指标，如 dify_api_request_duration_seconds
• _bytes：大小类 Gauge 或 Histogram，如 dify_llm_output_tokens_bytes
• _ratio 或 _percent：比例类 Gauge，如 dify_cache_hit_ratio（值域 0–1 或 0–100）