监控应用程序事件

Overview

在本指南中，您可以了解如何在 Kotlin Sync 驱动程序中设置和配置监控。

监控是获取运行程序所执行活动的信息，供应用程序或应用程序性能管理库使用的过程。

您可以使用Kotlin同步驱动程序监控集群、驱动程序命令和连接池事件。这些功能可帮助您在设计和调试应用程序时做出明智的决策。

本指南介绍如何执行以下任务：

使用Kotlin同步驱动程序监控特定事件
使用 Java 管理扩展 (JMX) 和 JConsole 监控连接池事件

提示

本指南介绍如何使用有关驱动程序元活动的信息。要学习；了解如何记录数据事务，请参阅监控数据更改页面。

监控事件

如需监控事件，必须在 MongoClient 实例上注册监听器。

事件是运行程序时发生的任何操作。驱动程序包括监听驱动程序运行时发生的事件子集的功能。

监听器是在某些事件发生时执行某些操作的类。监听器的 API 定义了其可以响应的事件。

侦听器类的每个方法代表对特定事件的响应，并接受代表该事件的事件对象作为参数。

Kotlin 同步驱动程序将其定义的事件分为三类：

命令事件
服务器发现和监控事件
连接池事件

以下部分介绍如何监控每个事件类别。有关可以监控的事件的完整列表，请参阅Java事件包。

命令事件

命令事件是与 MongoDB 数据库命令相关的事件。生成命令事件的数据库命令的一些示例包括 find、insert、delete 和 count。

要监控命令事件，请创建一个实现CommandListener接口的类，并使用MongoClient实例。

有关 MongoDB 数据库命令的更多信息，请参阅 MongoDB Server 手册中有关数据库命令的 MongoDB 手册条目。

注意

内部命令

驱动程序不会为其内部调用的命令发布事件。这包括驱动程序用于监控集群的数据库命令以及与连接建立相关的命令，例如初始 hello 命令。

重要

编辑输出

作为安全措施，驱动程序会编辑某些命令事件的内容。这可以保护这些命令事件中包含的敏感信息。有关已编辑命令事件的完整列表，请参阅MongoDB 命令日志记录和监控规范。

例子

此示例说明如何为数据库命令创建计数器。计数器追踪驱动程序成功执行每个数据库命令的次数，并在每次数据库命令完成时打印此信息。

要制作计数器，请按以下步骤操作：

创建具有计数器功能的类，实现 CommandListener 接口。
将新类的实例添加到 MongoClientSettings对象中。
使用 MongoClientSettings对象配置 MongoClient实例。

以下代码实现了这些步骤：

import com.mongodb.kotlin.client.MongoClientimport org.bson.Documentimport com.mongodb.event.*import com.mongodb.MongoClientSettingsimport com.mongodb.ConnectionString
class CommandCounter : CommandListener {    private val commands = mutableMapOf<String, Int>()
    override fun commandSucceeded(event: CommandSucceededEvent) {        val commandName = event.commandName        val count = commands[commandName] ?: 0        commands[commandName] = count + 1        println(commands.toString())    }
    override fun commandFailed(event: CommandFailedEvent) {        println("Failed execution of command '${event.commandName}' with id ${event.requestId}")    }}

fun main() {    val uri = "<connection string uri>"
// Instantiate your new listener    val commandCounter = CommandCounter()
// Include the listener in your client settings    val settings = MongoClientSettings.builder()        .applyConnectionString(ConnectionString(uri))        .addCommandListener(commandCounter)        .build()
// Connect to your database    val mongoClient = MongoClient.create(settings)    val database = mongoClient.getDatabase("sample_mflix")    val collection = database.getCollection<Document>("movies")
// Run some commands to test the counter    collection.find().firstOrNull()    collection.find().firstOrNull()
    mongoClient.close()}

有关本节中提到的类和方法的详情，请参阅以下 API 文档：

服务器发现和监控事件

服务器发现与监控 (SDAM) 事件是指与驱动程序连接到的 MongoDB 实例或集群的状态变化相关的事件。

该驱动程序定义了 9 个 SDAM 事件，并提供以下监听器接口，每个接口监听 3 个 SDAM 事件：

ClusterListener ：侦听拓扑相关事件
ServerListener ：侦听与 mongod 或 mongos 进程相关的事件
ServerMonitorListener ：侦听与心跳相关的事件

要监控SDAM事件类型，请创建一个实现上述三个接口之一的类，并使用 MongoClient实例注册该类的实例。

有关每个 SDAM事件的详细说明，请参阅MongoDB SDAM监控事件规范。

例子

此示例演示如何创建侦听器类，用于打印有关MongoDB实例写入可用性的消息。

要创建报告写入状态的事件，请执行以下任务：

创建一个类来跟踪集群描述更改，并实现 ClusterListener 接口。
将新类的实例添加到 MongoClientSettings对象中。
使用 MongoClientSettings对象配置 MongoClient实例。

以下代码实现了这些步骤：

import com.mongodb.kotlin.client.MongoClientimport org.bson.Documentimport com.mongodb.event.*import com.mongodb.MongoClientSettingsimport com.mongodb.ConnectionString
class IsWriteable : ClusterListener {    private var isWritable = false
    override fun clusterDescriptionChanged(event: ClusterDescriptionChangedEvent) {        if (!isWritable) {            if (event.newDescription.hasWritableServer()) {                isWritable = true                println("Able to write to cluster")            }        } else {            if (!event.newDescription.hasWritableServer()) {                isWritable = false                println("Unable to write to cluster")            }        }    }}

fun main() {    val uri = "<connection string uri>"
// Instantiate your new listener    val clusterListener = IsWriteable()
// Include the listener in your client settings    val settings = MongoClientSettings.builder()        .applyConnectionString(ConnectionString(uri))        .applyToClusterSettings { builder ->            builder.addClusterListener(clusterListener)        }        .build()
// Connect to your database    val mongoClient = MongoClient.create(settings)    val database = mongoClient.getDatabase("sample_mflix")    val collection = database.getCollection<Document>("movies")
// Run a command to trigger a ClusterDescriptionChangedEvent event    collection.find().firstOrNull()
    mongoClient.close()}

有关本节中提到的类和方法的详情，请参阅以下 API 文档：

连接池事件

连接池事件是与驱动程序持有的连接池相关的事件。连接池是驱动程序与 MongoDB 实例维护的一组打开的 TCP 连接。连接池有助于减少应用程序与MongoDB实例执行的网络握手次数，并可帮助应用程序更快地运行。

要监控连接池事件，请创建一个实现 ConnectionPoolListener 接口的类，并使用 MongoClient实例注册该类的实例。

例子

此示例展示了如何创建监听器类，在每次从连接池中检出连接时打印一条消息。

要创建报告连接签出的事件，请执行以下任务：

创建一个类来跟踪签出并实施 CommandListener 接口。
将新类的实例添加到 MongoClientSettings对象中。
使用 MongoClientSettings对象配置 MongoClient实例。

以下代码实现了这些步骤：

import com.mongodb.kotlin.client.MongoClientimport org.bson.Documentimport com.mongodb.event.*import com.mongodb.MongoClientSettingsimport com.mongodb.ConnectionString
class ConnectionPoolLibrarian : ConnectionPoolListener {    override fun connectionCheckedOut(event: ConnectionCheckedOutEvent) {        println("Let me get you the connection with id ${event.connectionId.localValue}...")    }    override fun connectionCheckOutFailed(event: ConnectionCheckOutFailedEvent) {        println("Something went wrong! Failed to checkout connection.")    }}

fun main() {    val uri = "<connection string uri>"
// Instantiate your new listenerval cpListener = ConnectionPoolLibrarian()
// Include the listener in your client settings    val settings = MongoClientSettings.builder()        .applyConnectionString(ConnectionString(uri))        .applyToConnectionPoolSettings({            it.addConnectionPoolListener(cpListener)            })        .build()
// Connect to your database            val mongoClient = MongoClient.create(settings)    val database = mongoClient.getDatabase("sample_mflix")    val collection = database.getCollection<Document>("movies")
// Run some commands to test the counter    collection.find().firstOrNull()
    mongoClient.close()}

有关本节中提到的类和方法的详情，请参阅以下 API 文档：

用 JMX 监控连接池事件

您可以使用“Java 管理扩展”(JMX) 监控连接池事件。JMX 提供了监控应用程序和设备的工具。

有关 JMX 的更多信息，请参阅Oracle JMX 官方文档。

JMX 支持

要启用 JMX 连接池监控，请将 JMXConnectionPoolListener 类的实例添加到 MongoClient 对象。

JMXConnectionPoolListener 类执行以下操作：

为驱动程序维护连接池的每个 mongod 或 mongos 进程创建 MXBean 实例。
将这些 MXBean 实例注册到平台 MBean 服务器。

在平台 MBean 服务器上注册的 MXBean 具有以下属性：

属性	说明
`clusterId`	客户端生成的唯一标识符。当应用程序有多个 `MongoClient` 实例连接到同一 MongoDB 部署时，该标识符可确保驱动程序生成的每个 MXBean 都有唯一的名称。
`host`	运行 `mongod` 或 `mongos` 进程的计算机的主机名。
`port`	`mongod` 或 `mongos` 进程正在侦听的端口。
`minSize`	连接池的最小大小，包括空闲和正在使用的连接。
`maxSize`	连接池的最大大小，包括空闲连接和使用中的连接。
`size`	连接池的当前大小，包括空闲连接和使用中的连接。
`checkedOutCount`	当前正在使用的连接数。

此驱动程序创建的所有 MXBean 实例均位于 "org.mongodb.driver" 域中。

如需了解有关本小节讨论主题的更多信息，请参阅 Oracle 提供的以下资源：

JMX 和 JConsole 示例

本例展示了如何使用 JMX 和 JConsole 监控驱动程序的连接池。JConsole 是 Java 平台自带的与 JMX 兼容的图形界面监控工具。

提示

查阅官方 JMX 与 JConsole 文档

此示例中对 JMX 和 JConsole 的描述只是说明性的，而不是事实来源。有关保证的最新信息，请查阅以下Oracle官方资源：

以下代码段将 JMXConnectionPoolListener 添加到 MongoClient 实例。然后代码暂停执行，以便您可以导航到 JConsole 并检查连接池。

import com.mongodb.kotlin.client.MongoClientimport org.bson.Documentimport com.mongodb.MongoClientSettingsimport com.mongodb.ConnectionStringimport com.mongodb.management.JMXConnectionPoolListener
fun main() {    val uri = "<connection string uri>"
// Instantiate your JMX listener    val connectionPoolListener = JMXConnectionPoolListener()
// Include the listener in your client settings    val settings = MongoClientSettings.builder()        .applyConnectionString(ConnectionString(uri))        .applyToConnectionPoolSettings {            it.addConnectionPoolListener(connectionPoolListener)        }        .build()
    try {// Connect to your database        val mongoClient = MongoClient.create(settings)        val database = mongoClient.getDatabase("sample_mflix")        val collection = database.getCollection<Document>("movies")        collection.find().firstOrNull()        collection.find().firstOrNull()        println("Navigate to JConsole to see your connection pools...")
// Pause execution        Thread.sleep(Long.MAX_VALUE)        mongoClient.close()    } catch (e: Exception) {        e.printStackTrace()    }}

Navigate to JConsole to see your connection pools...

启动服务器后，使用以下命令在终端中打开 JConsole：

jconsole

打开 JConsole 后，在图形界面中执行以下操作：

选择运行上述示例代码的进程。
在警告对话框中按 Insecure Connection。
单击 MBeans 标签页。
检查 "org.mongodb.driver" 域下的连接池事件。

如果您不再希望在 JConsole 中检查连接池，请执行以下操作：

关闭 JConsole窗口以退出 JConsole。
通过前面的代码片段停止运行的程序。

有关 JMX 和 JConsole 的详细信息，请参阅 Oracle 提供的以下资源：

有关 JMXConnectionPoolListener 类的更多信息，请参阅 JMXConnectionPoolListener 的API文档。

将驱动程序包含在分布式跟踪系统中

如果使用分布式跟踪系统，则可以包含驱动程序的事件数据。分布式跟踪系统是种应用程序，可在请求传播到面向服务架构中的不同服务时对其进行跟踪。

如果您在 Spring 云应用程序中使用该驱动程序，请使用 Spring Cloud Sleuth 将 MongoDB 事件数据包含在 Zipkin 分布式跟踪系统中。

如果您不使用 Spring 云或希望在 Zipkin 以外的分布式跟踪系统中包含驱动程序事件数据，则必须写入一个命令事件侦听器来管理所需分布式跟踪系统的跨度。

提示

要进一步学习；了解本节所讨论的概念，查看以下资源：

Spring Cloud
- Spring Cloud Sleuth
- spans
- TraceMongoCommandListener
  ：用于管理 span 的事件侦听的实施
- 开始体验
Zipkin
Dapper：Google Research 对分布式跟踪系统的详细描述