3. 日志标签与流设计：标签（Labels）的最佳实践、基数（Cardinality）控制、如何避免高基数导致的性能问题

在 Loki 中，标签（Labels）是日志流的唯一标识符，决定了日志如何被索引、存储和查询。错误的标签设计——尤其是高基数（High Cardinality）——是导致 Loki 性能退化、存储膨胀和查询超时的首要原因。本章将深入剖析标签设计原则、基数控制策略以及生产级避坑指南。

3.1 标签与日志流的核心关系

Loki 的每个日志流由一组键值对标签唯一标识。当日志写入时，具有相同标签组合的日志会被聚合到同一个流中。流是 Loki 存储和查询的最小逻辑单元。

3.2 标签最佳实践

3.2.1 应该作为标签的字段

• 服务/应用标识：job、service、app —— 基数通常 < 50
• 部署环境：env、cluster —— 基数通常 < 10
• 固定拓扑维度：namespace、datacenter、region —— 基数通常 < 100
• 日志级别：level —— 基数固定为 5~8

3.2.2 不应该作为标签的字段

3.3 基数控制策略

3.3.1 基数估算公式

总流数 = ∏ (每个标签键的基数)
示例：
  job: 5 个值 × env: 3 个值 × host: 200 个值 = 3,000 个流  ✅ 可接受
  job: 5 个值 × env: 3 个值 × user_id: 100,000 个值 = 1,500,000 个流  ❌ 灾难

3.3.2 生产级基数控制清单

1. 限制标签总数：每个日志流不超过 5~8 个标签键。
2. 限制标签值长度：标签值建议不超过 64 字节，避免长字符串。
3. 使用 chunk_target_size：配置目标块大小（如 1.5MB），避免小流产生过多块。
4. 启用 cardinality_limit：在 Loki 配置中设置每租户最大流数。
5. 定期审计：使用 loki-canary 或 Grafana 的 loki_boltdb_shipper_streams 指标监控流数量。

3.4 避免高基数的架构设计

下图展示了从日志采集到存储的完整链路中，如何在每个环节控制基数。

3.5 实战：Promtail 配置示例

以下配置展示了如何在 Promtail 中移除高基数标签，并将高基数字段保留在日志行内。

scrape_configs:
  - job_name: kubernetes-pods
    kubernetes_sd_configs:
      - role: pod
    pipeline_stages:
      # 1. 解析 JSON 日志
      - json:
          expressions:
            user_id: user_id
            request_id: request_id
            level: level
            msg: message
      # 2. 丢弃高基数标签（不将其作为 Loki 标签）
      - drop:
          source: user_id
      - drop:
          source: request_id
      # 3. 将日志级别映射为标签（低基数）
      - labels:
          level: level
      # 4. 重新组合日志行内容（保留高基数字段供查询）
      - template:
          source: message
          template: "{{.msg}} | user={{.user_id}} | req={{.request_id}}"
    relabel_configs:
      - source_labels: [__meta_kubernetes_pod_label_app]
        target_label: job
      - source_labels: [__meta_kubernetes_namespace]
        target_label: namespace

3.6 监控与告警：基数异常检测

使用以下 PromQL 查询监控 Loki 的流数量，并设置告警阈值。

# 每个租户的活跃流数量
sum by (tenant_id) (loki_ingester_streams_count)

# 流数量变化率（5分钟）
rate(loki_ingester_streams_count[5m])

# 高基数标签检测（需要开启 -log.level=debug）
sum by (label_name) (loki_distributor_label_cardinality)

3.7 常见误区与避坑