Metrics 监控

Metrics 是什么？

metrics 配置控制 SyncTV 的 Prometheus 指标出口。它不是客户端业务 API，而是给 Prometheus、VictoriaMetrics、Grafana Agent、OpenTelemetry Collector 等监控系统抓取 /metrics 使用。

默认情况下 metrics 是关闭的：

metrics:
  enabled: false

生产环境建议开启 metrics，但不要裸露到公网。最常见做法是只在内网、Kubernetes ServiceMonitor 或受控网段中访问。

完整示例

静态 bearer token：

metrics:
  enabled: true
  host: "0.0.0.0"
  port: 9090
  auth:
    mode: "bearer_token"
    bearer_token_file: "/run/secrets/metrics_token"

Basic auth：

metrics:
  enabled: true
  auth:
    mode: "basic"
    basic_username: "prometheus"
    basic_password_file: "/run/secrets/metrics_basic_password"

Kubernetes TokenReview + SubjectAccessReview：

这个模式要求 SyncTV 二进制编译时启用 k8s feature。Helm 可以渲染 RBAC、ServiceAccount token 和抓取资源，但不能改变镜像里的 feature set。

metrics:
  enabled: true
  auth:
    mode: "kubernetes"
    kubernetes:
      audience: "synctv-metrics"
      authentication_cache_ttl_seconds: 60
      authorization_cache_ttl_seconds: 60

`metrics.enabled`

类型：布尔值。

默认值：false。

作用：是否启动独立的 metrics HTTP 监听器。

什么时候开启：

你要接入 Prometheus 或 VictoriaMetrics。
你要观察请求量、错误率、延迟、缓存命中、连接数等运行状态。
你在 Kubernetes 中使用 ServiceMonitor 或 VMServiceScrape。

什么时候关闭：

本地临时测试。
你没有任何监控系统。
你无法保证 metrics 端点只被可信系统访问。

环境变量：

SYNCTV_METRICS_ENABLED=true

`metrics.host`

类型：字符串，IP 地址或监听地址。

默认值：0.0.0.0。

作用：metrics 监听在哪个网卡地址。

常见值：

值	含义
`0.0.0.0`	监听所有 IPv4 网卡，适合容器和 Kubernetes
`127.0.0.1`	只允许本机访问，适合单机加本地 agent
`::`	监听 IPv6 所有地址

示例：

metrics:
  host: "127.0.0.1"

`metrics.port`

类型：端口号。

默认值：9090。

作用：metrics 监听端口。

示例：

metrics:
  port: 9090

注意：这个端口和主服务 server.port 不同。主服务默认 8080，metrics 默认 9090。

`metrics.tls.enabled`

类型：布尔值。

默认值：false。

作用：是否让 metrics 监听器直接提供 HTTPS。

建议：

Kubernetes 内部由 ServiceMonitor 抓取时，通常可以关闭 TLS，并通过 NetworkPolicy/RBAC 控制访问。
裸机或跨网络抓取时，可以开启 TLS。
如果前面已有反向代理终止 TLS，不需要在 SyncTV metrics 上再次开启。

示例：

metrics:
  tls:
    enabled: true
    cert_path: "/etc/synctv/metrics/tls.crt"
    key_path: "/etc/synctv/metrics/tls.key"

`metrics.tls.cert_path`

类型：文件路径。

默认值：空字符串。

作用：metrics HTTPS 使用的 PEM 证书链路径。

路径规则：相对路径相对配置文件目录或当前工作目录，不相对 data_dir。

`metrics.tls.key_path`

类型：文件路径。

默认值：空字符串。

作用：metrics HTTPS 使用的 PEM 私钥路径。

安全建议：私钥文件只能允许 SyncTV 进程用户读取，不要放在公开目录。

`metrics.auth.mode`

类型：枚举。

默认值：bearer_token。

可选值：

值	含义	适合场景
`bearer_token`	使用固定 bearer token	Docker Compose、单机、简单 Prometheus
`basic`	使用 HTTP Basic Auth	某些传统抓取系统
`kubernetes`	使用 Kubernetes TokenReview 和 SubjectAccessReview	Kubernetes 集群内，更符合平台权限模型

kubernetes 模式需要二进制启用 k8s feature；否则配置校验会失败。

示例：

metrics:
  auth:
    mode: "bearer_token"

`metrics.auth.bearer_token`

类型：字符串 secret。

默认值：空字符串。

作用：当 metrics.auth.mode=bearer_token 时，抓取方必须携带：

Authorization: Bearer <token>

推荐使用文件：

metrics:
  auth:
    bearer_token_file: "/run/secrets/metrics_token"

生成示例：

openssl rand -base64 32

`metrics.auth.basic_username`

类型：字符串。

默认值：空字符串。

作用：当 metrics.auth.mode=basic 时的 Basic Auth 用户名。

示例：

metrics:
  auth:
    mode: "basic"
    basic_username: "prometheus"

`metrics.auth.basic_password`

类型：字符串 secret。

默认值：空字符串。

作用：当 metrics.auth.mode=basic 时的 Basic Auth 密码。

推荐使用文件：

metrics:
  auth:
    basic_password_file: "/run/secrets/metrics_basic_password"

`metrics.auth.kubernetes.audience`

类型：字符串。

默认值：空字符串。

作用：传给 Kubernetes TokenReview 的 audience，用于校验抓取方 token 是否面向 SyncTV metrics 场景签发。

建议：

如果你的 Prometheus 支持 service account token audience，建议设置一个固定值，例如 synctv-metrics。
如果平台没有启用 audience 校验，可以保持空字符串。

`metrics.auth.kubernetes.authentication_cache_ttl_seconds`

类型：秒数。

默认值：60。

作用：Kubernetes TokenReview 成功或失败结果的缓存时间。

调大可以减少 Kubernetes API Server 压力，但权限变化生效会更慢。调小更实时，但 API Server 压力更高。

`metrics.auth.kubernetes.authorization_cache_ttl_seconds`

类型：秒数。

默认值：60。

作用：Kubernetes SubjectAccessReview 授权结果的缓存时间。

建议保持默认。只有在你明确知道 Kubernetes API Server 压力或权限变更时效要求时再调整。

Helm 中的 metrics

Helm values 通常这样开启：

metrics:
  enabled: true
  auth:
    mode: bearer_token
  serviceMonitor:
    enabled: true

如果使用 VictoriaMetrics：

metrics:
  enabled: true
  vmServiceScrape:
    enabled: true

注意：Helm 中 HTTP/gRPC 是两个独立 Service，metrics selector 只应抓 HTTP/API 相关 Service，避免误抓 gRPC Service。