使用自定义监控指标提高可观测性

选择文档版本：

您可以在 AlloyDB Omni Kubernetes 操作器中使用自定义指标，通过针对数据库执行 SQL 查询来定义和收集特定于应用的指标。自定义指标使用 ObservabilityConfig 自定义资源 (CR) 来定义指标收集规则。

使用 ObservabilityConfig 配置自定义指标

ObservabilityConfig CR 由两个主要部分组成，即 dbClusterRefs 和 customMetrics。

dbClusterRefs

此部分包含此配置所适用的 DBCluster 资源的引用列表。每个 ObservabilityConfig 都必须以同一命名空间中的一个 DBCluster 为目标。

customMetrics

此部分定义了自定义指标收集的核心配置，包括资源限制和查询定义。

资源限制 (resourceLimits)

为保护数据库，系统会对自定义查询强制执行限制。如果您未在清单中指定这些限制，系统将使用下表中列出的默认值。

参数 说明 默认 最大值 单位
workMemory 指定监控代理用于收集这些指标的特定数据库连接的 work_mem。此设置是指标收集流程的本地设置，不会影响在 DBCluster 规范中配置的全局 work_mem 参数。 4MB 不适用 KB、MB（默认值：KB）
maxParallelWorkers 为监控代理使用的特定数据库连接指定 max_parallel_workers_per_gather。将此值设置为 0 可停用并行查询执行，并最大限度地减少 CPU 影响。此设置仅适用于指标收集流程，不会影响全局数据库配置。 0 不适用 整数
statementTimeout 为监控代理使用的特定数据库连接指定 statement_timeout。此设置会限制任何单个指标查询可运行的最长时间。此设置仅适用于指标收集进程，不会影响全局数据库配置。 2s 30s ms、s（默认值：ms）

自定义指标定义 (definitions)

definitions 列表中的每个条目都定义了一个查询，并描述了如何解读其结果。

  • metricGroup：用于指标命名的唯一名称（小写字母、数字、下划线）。
  • database：查询的目标数据库名称。监控代理会与此特定数据库建立连接以执行查询；因此，所查询的架构必须存在于该数据库中。
  • query：有效的 SQL SELECT 语句。仅允许执行 SELECT 查询。
  • metrics：将 SQL 结果列映射到 Prometheus 类型的列表：

安全性和权限

AlloyDB Omni 操作器使用 alloydbmonitor 用户来收集指标。默认情况下，AlloyDB Omni 操作器会创建此用户，并为其授予 postgres 数据库中的 LOGIN 属性和 pg_monitor 角色。

添加自定义指标时，请确保相应用户拥有适当的额外权限：

  • 用户责任：数据库管理员必须手动向 alloydbmonitor 用户授予对自定义查询中使用的任何特定应用表、视图或架构的 SELECT 权限。
  • 写入权限安全检查：为确保系统完整性并防止意外修改数据，AlloyDB Omni 操作器会执行安全检查。如果系统发现 alloydbmonitor 用户对目标数据库拥有任何写入权限（例如 INSERT、UPDATE 和 DELETE），系统会记录错误并拒绝从该数据库收集自定义指标。

授予权限示例

如需向名为 warehousedb 的数据库的 public 架构中的所有表授予只读访问权限，您必须运行以下命令：

psql -h <var>DB_CLUSTER_ENDPOINT</var> -U <var>DB_ADMIN_USER</var> -d warehousedb
warehousedb=# GRANT SELECT ON ALL TABLES IN SCHEMA public TO alloydbmonitor;

清单示例

以下示例清单将监控代理配置为连接到 postgres 数据库，并使用 pg_stat_database 系统视图跟踪事务统计信息。

apiVersion: alloydbomni.dbadmin.goog/v1
kind: ObservabilityConfig
metadata:
  name: obs-metrics
spec:
  dbClusterRefs:
    - dbcluster-sample
  customMetrics:
    resourceLimits:
      workMemory: "4MB"
      maxParallelWorkers: 0
    definitions:
      - metricGroup: database
        database: "postgres"
        query: |
          SELECT
            curr_db, xact_commit, xact_rollback
          FROM pg_stat_database WHERE datname IS NOT NULL
        metrics:
          - name: curr_db
            desc: "Database name"
            usage: label
          - name: xact_commit
            desc: "Transactions committed"
            usage: counter
          - name: xact_rollback
            desc: "Transactions rolled back"
            usage: counter

指标参考文档

本部分引用了自定义指标功能生成的指标。

生成的指标输出

此示例清单会以以下 Prometheus 格式导出指标：

# HELP alloydb_omni_custom_database_xact_commit_total Transactions committed
# TYPE alloydb_omni_custom_database_xact_commit_total counter
alloydb_omni_custom_database_xact_commit_total{database="postgres",curr_db="testdb1",dbcluster="dbcluster-sample",dbcluster_type="Primary",dbinstance="n/a",dbinstance_type="n/a",dbnamespace="mc",dbnode="76d3-dbcluster-sample",dbnode_type="Primary"} 382069 1774388549568
# HELP alloydb_omni_custom_database_xact_rollback_total Transactions rolled back
# TYPE alloydb_omni_custom_database_xact_rollback_total counter
alloydb_omni_custom_database_xact_rollback_total{database="postgres",curr_db="testdb1",dbcluster="dbcluster-sample",dbcluster_type="Primary",dbinstance="n/a",dbinstance_type="n/a",dbnamespace="mc",dbnode="76d3-dbcluster-sample",dbnode_type="Primary"} 4364 1774388549568

标准标签

每个自定义指标都会自动包含以下标准标签：database、dbcluster、dbcluster_type、dbinstance、dbinstance_type、dbnamespace、dbnode 和 dbnode_type。如需详细了解这些标签，请参阅 AlloyDB Omni 指标标签

指标收集指标

这些指标表示每个指标收集周期的状态。您可以在监控代理容器日志中找到详细的错误消息，包括哪些特定查询超时或失败。

# HELP alloydb_omni_monitor_custom_metrics_errors_total Total number of errors encountered during execution of the custom query
# TYPE alloydb_omni_monitor_custom_metrics_errors_total counter
alloydb_omni_monitor_custom_metrics_errors_total{metricGroup="database",dbcluster="dbcluster-sample",dbnode="...",...} 0 1773703411350

在使用自定义指标之前，请考虑以下事项：

  • 仅允许使用 SELECT 语句。系统会拒绝任何尝试修改数据的语句。在将查询纳入自定义指标配置之前，请先手动执行并验证查询结果和性能。
  • 设计每个 SQL 查询，使其返回最少数量的结果行。我们建议您指定少于 5 行，最好是单行。这样可确保从查询结果中派生的指标和标签不会导致基数过大，进而对监控系统的性能产生负面影响。
  • 优化查询，确保它们不会占用过多的资源。使用 resourceLimits 来保护您的数据库。
  • 每个查询都必须返回具有唯一标签值组合的行。