应用监控

代码示例: events

Ktor 提供了通过使用事件来监控服务器应用的功能。 您可以处理与应用生命周期相关的预定义事件（应用启动、停止等），或者可以使用自定义事件来处理特定情况。您还可以使用 MonitoringEvent 钩子处理自定义插件的事件。

事件定义

每个事件都由 EventDefinition 类实例表示。该类具有一个 T 类型形参，用于指定传递给事件的值类型。在事件处理程序中，该值可以作为 lambda 实参进行访问。例如，大多数预定义事件都接受 Application 作为形参，允许您在事件处理程序中访问应用属性。

对于自定义事件，您可以传递该事件所需的类型形参。 下面的代码片段展示了如何创建一个接受 ApplicationCall 实例的自定义 NotFoundEvent。

val NotFoundEvent: EventDefinition<ApplicationCall> = EventDefinition()

自定义事件部分展示了当服务器针对某项资源返回 404 Not Found 状态码时，如何在自定义插件中触发此事件。

预定义应用事件

Ktor 提供了以下与应用生命周期相关的预定义事件：

• ApplicationStarting
• ApplicationStarted
• ServerReady
• ApplicationStopPreparing
• ApplicationStopping
• ApplicationStopped

例如，您可以订阅 ApplicationStopped 事件以释放应用资源。

在应用中处理事件

要处理指定 Application 实例的事件，请使用 monitor 属性。 该属性提供了对 Events 实例的访问，该实例公开了以下允许您处理应用事件的函数：

• subscribe: 订阅由 EventDefinition 指定的事件。
• unsubscribe: 取消订阅由 EventDefinition 指定的事件。
• raise: 使用指定的值触发由 EventDefinition 指定的事件。

  自定义事件部分展示了如何触发自定义事件。

subscribe / unsubscribe 函数接受 EventDefinition 实例，并将 T 值作为 lambda 实参。 下面的示例展示了如何订阅 ApplicationStarted 事件并在事件处理程序中记录一条消息：

fun Application.module() {
    monitor.subscribe(ApplicationStarted) { application ->
        application.environment.log.info("Server is started")
    }
}

在此示例中，您可以了解如何处理 ApplicationStopped 事件：

fun Application.module() {
    monitor.subscribe(ApplicationStopped) { application ->
        application.environment.log.info("Server is stopped")
        // 释放资源并取消订阅事件
        monitor.unsubscribe(ApplicationStarted) {}
        monitor.unsubscribe(ApplicationStopped) {}
    }
}

有关完整示例，请参阅 events。

在自定义插件中处理事件

您可以使用 MonitoringEvent 钩子在自定义插件中处理事件。 下面的示例展示了如何创建 ApplicationMonitoringPlugin 插件并处理 ApplicationStarted 和 ApplicationStopped 事件：

import io.ktor.events.EventDefinition
import io.ktor.http.*
import io.ktor.server.application.*
import io.ktor.server.application.hooks.*

val ApplicationMonitoringPlugin = createApplicationPlugin(name = "ApplicationMonitoringPlugin") {
    on(MonitoringEvent(ApplicationStarted)) { application ->
        application.log.info("Server is started")
    }
    on(MonitoringEvent(ApplicationStopped)) { application ->
        application.log.info("Server is stopped")
        // 释放资源并取消订阅事件
        application.monitor.unsubscribe(ApplicationStarted) {}
        application.monitor.unsubscribe(ApplicationStopped) {}
    }
}

您可以在此处找到完整示例：events。

自定义事件

在本节中，我们将了解如何创建一个在服务器针对资源返回 404 Not Found 状态码时触发的自定义事件。

1. 首先，您需要创建事件定义。 下面的代码片段展示了如何创建一个接受 ApplicationCall 作为形参的自定义 NotFoundEvent 事件。

   val NotFoundEvent: EventDefinition<ApplicationCall> = EventDefinition()

2. 要触发该事件，请调用 Events.raise 函数。下面的示例展示了如何处理 ResponseSent 钩子，如果调用的状态码为 404，则触发新创建的事件。

   import io.ktor.events.EventDefinition
   import io.ktor.http.*
   import io.ktor.server.application.*
   import io.ktor.server.application.hooks.*
   
   val ApplicationMonitoringPlugin = createApplicationPlugin(name = "ApplicationMonitoringPlugin") {
       on(ResponseSent) { call ->
           if (call.response.status() == HttpStatusCode.NotFound) {
               this@createApplicationPlugin.application.monitor.raise(NotFoundEvent, call)
           }
       }
   }

3. 要在应用中处理创建的事件，请安装该插件：

   fun Application.module() {
       install(ApplicationMonitoringPlugin)
   }

4. 然后，使用 Events.subscribe 订阅该事件：

   fun Application.module() {
       install(ApplicationMonitoringPlugin)
       monitor.subscribe(NotFoundEvent) { call ->
           log.info("No page was found for the URI: ${call.request.uri}")
       }
   }

有关完整示例，请参阅 events。