客户指标集成 (CMI)

AuraDB 虚拟专用云 AuraDS 企业版 AuraDB 商业关键版

可以配置应用程序性能监控系统来获取以下类型 AuraDB 实例的指标

AuraDB 虚拟专用云
AuraDS 企业版
AuraDB 商业关键版

这使用户可以访问其 Neo4j Aura 实例指标数据以进行监控。

分析指标数据可以让用户

优化 Neo4j 负载
调整 Aura 实例大小
设置通知

流程概述

详细步骤

以项目管理员身份登录 Aura。
确保有一个专用的 Aura 用户用于获取指标。您可以
- 创建新用户
  1. 在 Neo4j Aura 的 "用户管理" 中，邀请新用户，选择 "指标集成读取器" 作为角色。
  2. 按照邀请链接登录 Neo4j Aura。
  3. 确认项目成员资格。
- 或者，您可以在 "用户管理" 中找到现有用户，并将角色更改为 "指标集成读取器"
  
  具有 "指标集成读取器" 角色的用户的权限仅限于获取指标和获取项目的只读视图。
确保您以上一步骤中选择的用户的身份登录 Aura。在 "帐户详细信息" 中，创建新的 Aura API 凭据。保存客户端密钥。
配置 APM 系统以从 Neo4j Aura 的 "指标集成" 中显示的 URL 或配置模板获取指标。使用 oauth2 类型的身份验证，指定在上一步中创建的客户端 ID 和客户端密钥。查看 Prometheus 和 Grafana 以及 Datadog 的示例。
使用 APM 系统基于 Neo4j 指标创建可视化、仪表板和警报。

安全

仅当以下所有条件都满足时，才会返回 Neo4j Aura 实例的指标

指标请求的 Authorization 标头包含有效令牌。
该令牌是为具有 "指标集成读取器" 角色的 Aura 用户发行的。
项目具有 企业版 (虚拟专用云) 或 商业关键版 类型的实例。
指定的实例属于指定的项目。

旧术语 企业版 仍在代码库和 API 中使用。但是，在 Aura 控制台和文档中，AuraDB 企业版项目类型现在称为 AuraDB 虚拟专用云。

撤销对指标的访问权限

要撤销用户对特定项目的指标的访问权限，请在 "用户管理" 中将该用户从该项目中删除。之后，该用户仍然存在，但其与项目的连接将被移除。

所述的撤销将在授权缓存过期后生效，大约需要 5 分钟。这会导致返回 HTTP 401，以及消息 用户没有访问指标资源的权限。 但是，如果您只删除用于检索指标的 Aura API 凭据，则撤销将在使用这些凭据发行的令牌过期后生效，因为无法再颁发新令牌。当前使用的令牌过期时间为 1 小时。

指标标签

根据指标的不同，将应用以下标签

aggregation: 用于计算指标值的聚合，在每个指标上设置。由于 Neo4j 实例作为 Neo4j 集群部署，因此执行聚合以组合来自所有相关集群节点的值。使用以下聚合：MIN、MAX、AVG 和 SUM。
instance_id: 报告指标的 Aura 实例 ID，在每个指标上设置。
database: 报告指标的 Neo4j 数据库的名称。默认情况下设置为 neo4j。

示例

# HELP neo4j_database_count_node The total number of nodes in the database.
# TYPE neo4j_database_count_node gauge
neo4j_database_count_node{aggregation="MAX",database="neo4j",instance_id="78e7c3e0"} 778114.000000 1711462853000

在 Neo4j Aura 高级指标中查找指标名称

在 Neo4j Aura 高级指标中，可以使用图表菜单项 "指标集成" 来查找与图表相对应的指标名称，如图所示。

指标抓取间隔

推荐的指标抓取间隔范围为 30 秒到 2 分钟，具体取决于要求。指标端点缓存指标 30 秒。

使用 Prometheus 的示例

安装 Prometheus

一种方法是从 https://prometheus.ac.cn/docs/prometheus/latest/installation/ 获取 tarball

配置 Prometheus

要监控一个或多个实例，请在 Prometheus 配置文件 prometheus.yml 中添加一个部分。

复制指标集成中建议的配置部分，如图所示。

将占位符 <AURA_CLIENT_ID> 和 <AURA_CLIENT_SECRET> 替换为在上一步中创建的相应值。

有关详细信息，请参阅 Prometheus 配置参考。

启动 Prometheus

./prometheus --config.file=prometheus.yml

测试指标是否被获取

打开 http://localhost:9090 并在搜索字段中输入指标名称或表达式（例如，neo4j_aura_cpu_usage）。

使用 Grafana

安装和配置 Grafana，将上一步中配置的 Prometheus 实例的端点添加为数据源。您可以基于 Neo4j 指标创建可视化、仪表板和警报。

使用 Datadog 的示例

配置具有令牌身份验证的端点

编辑 /etc/datadog-agent/conf.d/openmetrics.d/conf.yaml 如下所示

将占位符 <ENDPOINT_URL>、<AURA_CLIENT_ID> 和 <AURA_CLIENT_SECRET> 替换为上一步中的相应值。

/etc/datadog-agent/conf.d/openmetrics.d/conf.yaml

init_config:
instances:
  - openmetrics_endpoint: <ENDPOINT_URL>
    metrics:
      - neo4j_.*
    auth_token:
      reader:
        type: oauth
        url: https://api.neo4j.io/oauth/token
        client_id: <AURA_CLIENT_ID>
        client_secret: <AURA_CLIENT_SECRET>
      writer:
        type: header
        name: Authorization
        value: "Bearer <TOKEN>"

有关详细信息，请参阅 Datadog 代理文档和配置参考。

测试指标是否被获取

sudo systemctl restart datadog-agent
观察 /var/log/datadog/* 以查看是否正在获取指标，或者是否存在有关解析配置的警告。
在 Datadog 指标浏览器中检查指标是否出现（几分钟后）。

编程支持

用于指标集成的 Aura API

Aura API 支持使用以下方法获取指标集成端点
- 端点 /tenants/{tenantId}/metrics-integration（用于项目指标）
- JSON 属性 metrics_integration_url 作为 /instances/{instanceId} 响应的一部分（用于实例指标）
参考：Aura API 规范

项目在控制台 UI 和文档中替换了租户。但是，在 API 中，tenant 仍然是术语。

用于指标集成的 Aura CLI

Aura CLI 具有用于 tenants 命令的子命令以获取项目指标端点

aura projects get-metrics-integration --tenant-id <YOUR_PROJECT_ID>

# example output
{
  endpoint: "https://customer-metrics-api.neo4j.io/api/v1/<YOUR_PROJECT_ID>/metrics"
}

# extract endpoint
aura projects get-metrics-integration --project-id <YOUR_PROJECT_ID> | jq '.endpoint'

例如，对于指标端点，Aura CLI 的 `instances get` 命令的 JSON 输出包含一个新的属性 `metrics_integration_url`。

aura instances get --instance-id <YOUR_INSTANCE_ID>

# example output
{
    "id": "id",
    "name": "Production",
    "status": "running",
    "tenant_id": "YOUR_PROJECT_ID",
    "cloud_provider": "gcp",
    "connection_url": "YOUR_CONNECTION_URL",
    "metrics_integration_url": "https://customer-metrics-api.neo4j.io/api/v1/<YOUR_PROJECT_ID>/<YOUR_INSTANCE_ID>/metrics",
    "region": "europe-west1",
    "type": "enterprise-db",
    "memory": "8GB",
    "storage": "16GB"
  }

# extract endpoint
aura instances get --instance-id <YOUR_INSTANCE_ID> | jq '.metrics_integration_url'

参考：Aura CLI 速查表

指标粒度

集成端点返回的指标根据提供的标签进行分组：`aggregation`、`instance_id` 和 `database`。

Aura 实例通常在多个服务器上运行，以实现可用性和工作负载可扩展性。这些服务器部署在用户选择的区域中的不同云提供商可用区中。

指标集成支持 Aura 实例指标的更细粒度视图，其中包含可用区和实例模式组合的额外数据点。此视图可以按需启用。

请联系客户支持，为您的项目启用实例的更细粒度指标。

创建新的 Aura 实例后，更细粒度的指标可能会有延迟。这是由于收集“可用区”数据的方式。

示例指标数据点

neo4j_aura_cpu_usage{aggregation="MAX",instance_id="a59d71ae",availability_zone="eu-west-1a",instance_mode="PRIMARY"} 0.025457 1724245310000
neo4j_aura_cpu_usage{aggregation="MAX",instance_id="a59d71ae",availability_zone="eu-west-1b",instance_mode="PRIMARY"} 0.047088 1724245310000
neo4j_aura_cpu_usage{aggregation="MAX",instance_id="a59d71ae",availability_zone="eu-west-1c",instance_mode="PRIMARY"} 0.021874 1724245310000

其他指标标签

availability_zone - 用户选择的云提供商区域。
instance_mode - 基于用户选择的工作负载需求（读写）。（每个实例至少 3 个主节点）

使用

以下是如何深入了解 Aura 实例 CPU 使用情况以进行容量规划的示例

示例 PromQL 查询以绘制图表

max by(availability_zone) (neo4j_aura_cpu_usage{instance_mode="PRIMARY"}) / sum by(availability_zone) (neo4j_aura_cpu_limit{instance_mode="PRIMARY"})

图 1. 图表显示了按可用区划分的每个主节点的 CPU 使用率

指标定义

内存不足错误
指标名称	`neo4j_aura_out_of_memory_errors_total`
描述	实例的内存不足错误总数。如果出现任何 OOM 错误，请考虑增加实例大小。
指标类型	计数器
默认聚合	`SUM`

可用 CPU
指标名称	`neo4j_aura_cpu_limit`
描述	分配给实例节点的总 CPU 内核数。
指标类型	仪表盘
默认聚合	`MAX`

CPU 使用率
指标名称	`neo4j_aura_cpu_usage`
描述	CPU 使用率（内核）。CPU 用于规划和服务查询。如果此指标持续飙升或达到其限制，请考虑增加实例大小。
指标类型	仪表盘
默认聚合	`MAX`

总存储空间
指标名称	`neo4j_aura_storage_limit`
描述	分配给实例的总磁盘存储空间。
指标类型	仪表盘
默认聚合	`MAX`

已用堆空间
指标名称	`neo4j_dbms_vm_heap_used_ratio`
描述	已使用的已配置堆内存的百分比。堆空间用于查询执行、事务状态、图形管理等。堆空间的大小高度依赖于 Neo4j 使用的性质。例如，长时间运行的查询或非常复杂的查询可能需要比简单查询更大的堆空间。为了提高性能，堆空间应足够大以支持并发操作。此值不应长时间超过 80%，短时间峰值是正常的。如果出现性能问题，您可能需要调整查询并监控其内存使用情况，以确定是否需要增加堆空间。如果 Neo4j 的工作负载和查询的性能表明需要更多堆空间，请考虑增加实例大小。这有助于避免因垃圾回收而产生的不必要的暂停。
指标类型	仪表盘
默认聚合	`MAX`

页面缓存命中率（每分钟）
指标名称	`neo4j_dbms_page_cache_hit_ratio_per_minute`
描述	查询执行期间所需的数据在内存中找到的次数百分比，与从磁盘读取数据的次数相比。理想情况下，整个图形都应适合内存，并且此值应始终保持在 98% 到 100% 之间。如果此值始终或显着低于 100%，请检查页面缓存使用率以查看图形是否太大而无法放入内存。在图形上进行大量插入或更新操作也会导致此值发生变化。
指标类型	仪表盘
默认聚合	`AVG`

页面缓存使用率
指标名称	`neo4j_dbms_page_cache_usage_ratio`
描述	已分配的页面缓存的使用百分比。如果此值接近或达到 100%，那么命中率可能会开始下降，您应该考虑增加实例大小，以便为页面缓存提供更多内存。
指标类型	仪表盘
默认聚合	`MIN`

正在运行的 Bolt 连接
指标名称	`neo4j_dbms_bolt_connections_running`
描述	当前正在执行 Cypher 事务并返回结果的 Bolt 连接总数。这是一组随时间推移的快照，如果工作负载都快速完成，可能会显示峰值。
指标类型	仪表盘
默认聚合	`MAX`

空闲的 Bolt 连接
指标名称	`neo4j_dbms_bolt_connections_idle`
描述	连接到 Aura 数据库但当前未执行 Cypher 或返回结果的 Bolt 连接总数。
指标类型	仪表盘
默认聚合	`MAX`

关闭的 Bolt 连接
指标名称	`neo4j_dbms_bolt_connections_closed_total`
描述	自启动以来关闭的 Bolt 连接总数。这包括正常和异常结束的连接。如果 Aura 执行后台维护，此值可能会下降。
指标类型	计数器
默认聚合	`MAX`

打开的 Bolt 连接
指标名称	`neo4j_dbms_bolt_connections_opened_total`
描述	自启动以来打开的 Bolt 连接总数。这包括成功和失败的连接。如果 Aura 执行后台维护，此值可能会下降。
指标类型	计数器
默认聚合	`MAX`

垃圾回收年轻代
指标名称	`neo4j_dbms_vm_gc_time_g1_young_generation_total`
描述	显示自启动以来用于清理短期对象堆空间的总时间。年轻代垃圾回收通常很快完成，Aura 实例会在垃圾回收器运行时等待。高值表示实例的内存不足，您应该考虑增加实例大小。
指标类型	计数器
默认聚合	`MAX`

垃圾回收老年代
指标名称	`neo4j_dbms_vm_gc_time_g1_old_generation_total`
描述	显示自启动以来用于清理长期对象堆空间的总时间。老年代垃圾回收可能需要时间才能完成，Aura 实例会在垃圾回收器运行时等待。高值表示存在长时间运行的进程或查询，可以对其进行优化，或者您的实例的 CPU 或内存不足，您应该考虑查看这些指标并可能增加实例大小。
指标类型	计数器
默认聚合	`MAX`

重新规划事件
指标名称	`neo4j_database_cypher_replan_events_total`
描述	自服务器启动以来 Cypher 重新规划查询的总次数。如果此值飙升或正在增加，请检查执行的查询是否正确使用参数。如果 Aura 执行后台维护，此值可能会下降。
指标类型	计数器
默认聚合	`MAX`

活动读取事务
指标名称	`neo4j_database_transaction_active_read`
描述	当前活动读取事务数。
指标类型	仪表盘
默认聚合	`MAX`

活动写入事务
指标名称	`neo4j_database_transaction_active_write`
描述	活动写入事务数。
指标类型	仪表盘
默认聚合	`MAX`

已提交的事务
指标名称	`neo4j_database_transaction_committed_total`
描述	自服务器启动以来已提交的事务总数。如果 Aura 执行后台维护，此值可能会下降。
指标类型	计数器
默认聚合	`MAX`

峰值并发事务
指标名称	`neo4j_database_transaction_peak_concurrent_total`
描述	自服务器启动以来检测到的最高并发事务数。如果 Aura 执行后台维护，此值可能会下降。
指标类型	计数器
默认聚合	`MAX`

事务回滚
指标名称	`neo4j_database_transaction_rollbacks_total`
描述	回滚的事务总数。如果 Aura 执行后台维护，此值可能会下降。
指标类型	计数器
默认聚合	`MAX`

检查点事件
指标名称	`neo4j_database_check_point_events_total`
描述	自服务器启动以来执行的检查点事件总数。如果 Aura 执行后台维护，此值可能会下降。
指标类型	计数器
默认聚合	`MAX`

检查点事件累计时间
指标名称	`neo4j_database_check_point_total_time_total`
描述	自服务器启动以来在检查点中花费的总时间（以毫秒为单位）。如果 Aura 执行后台维护，此值可能会下降。
指标类型	计数器
默认聚合	`MAX`

上次检查点持续时间
指标名称	`neo4j_database_check_point_duration`
描述	上次检查点事件的持续时间。检查点通常需要几秒钟到几分钟。超过 30 分钟的值需要调查。
指标类型	仪表盘
默认聚合	`MAX`

关系
指标名称	`neo4j_database_count_relationship`
描述	数据库中的关系总数。
指标类型	仪表盘
默认聚合	`MAX`

节点
指标名称	`neo4j_database_count_node`
描述	数据库中的节点总数。
指标类型	仪表盘
默认聚合	`MAX`

数据库存储大小
指标名称	`neo4j_database_store_size_database`
描述	保留用于存储用户数据库数据的磁盘空间量（以字节为单位）。理想情况下，数据库应全部适合内存（页面缓存）以获得最佳性能。请密切关注此指标，以确保您有足够的存储空间来满足当前和未来增长需求。将此指标与页面缓存使用率一起检查，以查看数据是否太大而无法放入内存，在这种情况下，请考虑增加实例大小。
指标类型	仪表盘
默认聚合	`MAX`

页面缓存逐出
指标名称	`neo4j_dbms_page_cache_evictions_total`
描述	内存中数据被替换的总次数。峰值可能意味着您的工作负载超出了实例的可用内存，您可能会注意到性能下降或查询执行错误。如果此指标仍然很高，请考虑增加实例大小以提高性能。
指标类型	计数器
默认聚合	`MAX`

成功执行的查询
指标名称	`neo4j_db_query_execution_success_total`
描述	在此数据库上成功执行的查询总数。
指标类型	计数器
默认聚合	`SUM`

查询执行失败
指标名称	`neo4j_db_query_execution_failure_total`
描述	在此数据库上执行的失败查询总数。
指标类型	计数器
默认聚合	`SUM`

查询延迟第 99 百分位数
指标名称	`neo4j_db_query_execution_internal_latency_q99`
描述	查询执行时间（以毫秒为单位），其中 99% 的查询执行时间快于报告的时间。
指标类型	仪表盘
默认聚合	`MAX`

查询延迟第 75 百分位数
指标名称	`neo4j_db_query_execution_internal_latency_q75`
描述	查询执行时间（以毫秒为单位），其中 75% 的查询执行时间快于报告的时间。
指标类型	仪表盘
默认聚合	`MAX`

查询延迟第 50 百分位数
指标名称	`neo4j_db_query_execution_internal_latency_q50`
描述	查询执行时间（以毫秒为单位），其中 50% 的查询执行时间快于报告的时间。这也对应于查询执行时间的中间值。
指标类型	仪表盘
默认聚合	`MAX`

上次提交的事务 ID
指标名称	`neo4j_database_transaction_last_committed_tx_id_total`
描述	上次提交的事务的 ID。跟踪 Aura 实例的主节点集群成员的此指标。它应显示重叠的不断增长的线，如果其中一条线变平或落后，则很明显该集群成员不再复制数据，需要采取措施纠正这种情况。
指标类型	计数器
默认聚合	`MAX`

集群领导者（仅在开启高粒度时包含）
指标名称	neo4j_cluster_raft_is_leader
描述	此服务器是领导者吗？跟踪集群中每个筏成员的此指标。如果它不是领导者，则报告 0，如果是领导者，则报告 1。所有这些的总和应始终为 1。但是，在某些短暂的时期，总和可能大于 1，因为多个成员认为自己是领导者。如果指标在超过 30 秒的时间内显示 0，则可能需要采取措施。
指标类型	仪表盘
默认聚合	`MAX`