Skip to content

應用程式監控 ​

程式碼範例: events

Ktor 提供透過事件監控伺服器應用程式的功能。 你可以處理與應用程式生命週期相關的預先定義事件(應用程式啟動、停止等),也可以使用自訂事件來處理特定情況。你還可以使用 MonitoringEvent 掛鉤來處理自訂外掛程式的事件。

事件定義 ​

每個事件都由 EventDefinition 類別的執行個體表示。該類別具有一個 T 型別參數,用於指定傳遞給事件的值的型別。可以在事件處理常式中將此值作為 Lambda 引數存取。例如,大多數預先定義事件都接受 Application 作為參數,允許你在事件處理常式內部存取應用程式屬性。

對於自訂事件,你可以傳遞該事件所需的型別參數。 以下程式碼片段示範了如何建立一個接受 ApplicationCall 執行個體的自訂 NotFoundEvent。

kotlin
val NotFoundEvent: EventDefinition<ApplicationCall> = EventDefinition()

自訂事件章節示範了當伺服器針對資源傳回 404 Not Found 狀態碼時,如何在自訂外掛程式中觸發此事件。

預先定義的應用程式事件 ​

Ktor 提供以下與應用程式生命週期相關的預先定義事件:

例如,你可以訂閱 ApplicationStopped 事件以釋放應用程式資源。

在應用程式中處理事件 ​

若要處理指定 Application 執行個體的事件,請使用 monitor 屬性。 此屬性提供對 Events 執行個體的存取,該執行個體公開了以下允許你處理應用程式事件的函式:

subscribe / unsubscribe 函式接受帶有 T 值的 EventDefinition 執行個體作為 Lambda 引數。 以下範例示範了如何訂閱 ApplicationStarted 事件並在事件處理常式中記錄日誌訊息:

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

在這個範例中,你可以看到如何處理 ApplicationStopped 事件:

kotlin
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 事件:

kotlin
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 事件。

    kotlin
    val NotFoundEvent: EventDefinition<ApplicationCall> = EventDefinition()
  2. 若要觸發該事件,請呼叫 Events.raise 函式。以下範例示範了如何處理 ResponseSent 掛鉤,以在呼叫的狀態碼為 404 時觸發新建立的事件。

    kotlin
    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. 若要在 Application 中處理建立的事件,請安裝此外掛程式:

    kotlin
    fun Application.module() {
        install(ApplicationMonitoringPlugin)
    }
  4. 接著,使用 Events.subscribe 訂閱該事件:

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

有關完整範例,請參閱 events。