Prometheus方式的指标集建模

MetricSet 的定义和作用

MetricSet 作为指标建模的核心组件，承担以下关键职责：

• 指标组织：将相关指标组织成逻辑集合，便于管理和查询。

• 标签管理：定义指标的通用标签和过滤规则。

• 查询优化：通过统一的查询接口提供高效的指标查询能力。

• 语义表达：为指标提供丰富的元数据和多语言支持。

MetricSet 结构概览

可观测数据体系
├── TelemetryDataSet          # 遥测数据集（日志、追踪）
├── EntitySet                 # 实体集
└── MetricSet                 # 指标集
    ├── labels                # 标签定义
    │   ├── keys: Field[]     # 标签字段列表
    │   ├── dynamic: boolean  # 动态标签生成
    │   └── filter: string    # 标签过滤器
    └── metrics: Metric[]     # 指标列表
        ├── name              # 指标名称
        ├── generator         # 查询生成器
        ├── aggregator        # 聚合方式
        └── data_format       # 格式化方式

Labels 设计原则

Labels（标签）定义了指标的维度属性，遵循以下设计原则：

• 通用性优先：MetricSet 级别的标签应该是所有指标共有的维度。

• 动态生成：推荐使用动态方式自动生成标签，避免硬编码。

• 高效过滤：标签应支持高效的索引和过滤查询。

• 基数控制：避免高基数标签导致的性能问题。

Labels 属性配置

标签字段定义

每个标签字段继承 Field 的完整属性，重点关注以下特性：

Labels 配置示例

Kubernetes 场景标签配置

labels:
  dynamic: true
  filter: 'kube_deployment_spec_replicas'
  keys:
    - name: namespace
      display_name:
        zh_cn: 命名空间
        en_us: Namespace
      type: string
      filterable: true
      analysable: true
      pattern: ".*"
    - name: deployment  
      display_name:
        zh_cn: 部署名称
        en_us: Deployment
      type: string
      filterable: true
      analysable: true
      pattern: ".*"

APM 场景标签配置

labels:
  dynamic: true
  filter: 'arms_app_requests_count_ign_destid_endpoint_parent_ppid_prpc{callKind=~"http|rpc|custom_entry|server|consumer|schedule"}'
  keys:
    - name: service
      display_name:
        zh_cn: 服务名称
        en_us: Service
      type: string
      filterable: true
      analysable: true
    - name: rpc
      display_name:
        zh_cn: 接口名称  
        en_us: Operation
      type: string
      filterable: true
      analysable: true

Metrics 设计原则

Metrics（指标）是 MetricSet 的核心组成部分，每个指标代表一个可查询的监控维度：

• 业务语义：指标名称应该体现清晰的业务含义。

• 计算完整：generator 应该包含完整的计算逻辑，而非原始指标。

• 单位明确：合理配置 data_format 和 unit 属性。

• 聚合合理：根据指标特性选择正确的 aggregator。

Metrics 核心属性

基于字段系统的基础上，Metric 扩展了以下监控特有属性：

数据格式化规范

Metric 通常用于图表绘制，因此数据格式化字段极其重要，应尽可能使用 Schema 中定义的枚举值，禁止使用自定义格式。

详细格式化选项见 字段系统章节。

Aggregator 选择指南

正确选择 aggregator 对指标查询的准确性至关重要：

注意 ：对于已在 generator 中计算比率的指标（如 usage/limit * 100），不应设置 aggregator，让 UModel 系统根据实际需求自动选择聚合策略。

下述是常见的 Generator 和 Aggregator 的组合示例：

- name: request_count
  generator: 'sum_over_time_lcro(arms_app_requests_count_ign_destid_endpoint_parent_ppid_prpc{callKind=~"http|rpc|custom_entry|server|consumer|schedule"}[60s])'
  aggregator: sum
  data_format: KMB

2. 副本数指标 - Deployment 期望副本数。

- name: deployment_desired_replicas
  generator: kube_deployment_spec_replicas{}
  aggregator: sum
  data_format: KMB

3. 比率类指标（不设置聚合器）- Deployment 可用性。

- name: deployment_availability_rate
  generator: (sum by (namespace, deployment) (kube_deployment_status_replicas_ready{}) / (sum by (namespace, deployment) (kube_deployment_spec_replicas{}))!=0) * 100
  # 不设置 aggregator
  data_format: percent

4. 平均延迟指标 - APM 平均响应时间。

- name: avg_request_latency_seconds
  generator: 'sum(sum_over_time_lcro(arms_app_requests_seconds_ign_destid_endpoint_parent_ppid_prpc{callKind=~"http|rpc|custom_entry|server|consumer|schedule"}[60s])) / sum(sum_over_time_lcro(arms_app_requests_count_ign_destid_endpoint_parent_ppid_prpc{callKind=~"http|rpc|custom_entry|server|consumer|schedule"}[60s]))'
  # 不设置 aggregator
  data_format: s

Golden Metric 标识

Golden Metric 用于标识最关键的监控指标：

• 数量限制：每个 MetricSet 推荐设置3-5个 Golden Metric，不超过 8 个。

• 选择标准：直接反映系统健康状况的核心指标。

• 应用场景：告警规则、仪表板、自动化运维。

Metrics 配置示例

• CPU 使用率指标。

  - name: deployment_cpu_usage_vs_requests
    display_name:
      zh_cn: CPU使用率相对于请求值
      en_us: CPU Usage vs Requests  
    description:
      zh_cn: Deployment 的 CPU 使用率相对于请求值的百分比
      en_us: CPU usage percentage relative to requests for the deployment
    generator: |
      sum by (namespace, deployment) (
        rate(container_cpu_usage_seconds_total{pod!~"POD"}[5m])
      ) / sum by (namespace, deployment) (
        kube_pod_container_resource_requests_cpu_cores{pod!~"POD"}
      ) * 100
    data_format: percent
    unit: ''
    golden_metric: true
    interval_us: [15000000]
    type: gauge

• 请求计数指标。

  - name: request_count
    display_name:
      zh_cn: 请求次数
      en_us: Request Count
    description:
      zh_cn: 请求次数指的是对一个特定应用或接口发起调用的总次数
      en_us: Request count refers to the total number of calls to a specific service or API
    generator: 'sum_over_time_lcro(arms_app_requests_count_ign_destid_endpoint_parent_ppid_prpc{callKind=~"http|rpc|custom_entry|server|consumer|schedule"}[60s])'
    aggregator: sum
    data_format: KMB
    golden_metric: true
    interval_us: 15000000

变量替换机制

• UModel 系统中，对于 Prometheus 语法的 MetricSet 内置了Label筛选注入能力，对Labels中的标签值进行筛选后，会自动将筛选条件表达式注入到 generator 中。

• 由于 Metric 中的 generator 支持多指标进行 join 操作，不一定所有的指标都支持所有Label注入（例如 K8s 中的一些高阶指标，需要多指标 Join 做数据富化的场景）。因此需要使用变量替换机制来处理标签字段的差异性。

# 示例：node 标签只在 kube_pod_info 中存在
kube_pod_info{node=~"${{node|.*}}"}

标签关联示例

# 内存资源相关指标，通过 ReplicaSet 关联 Pod 和 Deployment
- aggregator: sum
  data_format: byte
  description:
      en_us: Total memory requests for all pods in the deployment
      zh_cn: Deployment 所有 Pod 的内存请求总量
  display_name:
      en_us: Deployment Memory Requests Total
      zh_cn: Deployment 内存请求总量
  generator: sum by (namespace, deployment) (kube_pod_container_resource_requests_memory_bytes{pod!~"POD"} * on (pod, namespace) group_left (deployment) (max by (pod, namespace, deployment) (label_replace(kube_pod_info{created_by_kind="ReplicaSet"}, "replicaset", "$1", "created_by_name", "(.*)") * on (namespace, replicaset) group_left (deployment) label_replace(kube_replicaset_owner{owner_kind="Deployment", owner_name=~"${{deployment|.*}}"}, "deployment", "$1", "owner_name", "(.*)"))))
  golden_metric: false
  interval_us:
  - 15000000
  launch_stage: ga
  name: deployment_memory_requests_total
  type: gauge
  unit: ''

设计原则

1. 语义明确：指标名称应该清晰表达业务含义。

2. 标签合理：避免高基数标签，保持查询性能。

3. 计算完整：generator 包含完整的业务逻辑。

4. 格式标准：严格使用 Schema 定义的 data_format 枚举值。

5. 聚合正确：根据指标特性选择合适的 aggregator。

性能优化

1. 标签过滤：在查询早期阶段应用标签过滤。

2. 聚合优化：使用 sum by 等函数减少时间序列数量。

3. 动态标签：使用 dynamic: true 提高标签管理效率。