Application monitoring
Ktor provides the ability to monitor your server application by using events. You can handle predefined events related to an application's lifecycle (application starting, stopping, etc.), or you can use custom events to handle specific cases. You can also handle events for custom plugins using the MonitoringEvent hook.
Event definition
Each event is represented by the EventDefinition class instance. This class has a T
type parameter specifying the type of value passed to the event. This value can be accessed in the event handler as a lambda argument. For example, most of the predefined events accept Application
as a parameter allowing you to access application properties inside the event handler.
For a custom event, you can pass a type parameter required for this event. The code snippet below shows how to create a custom NotFoundEvent
that accepts the ApplicationCall
instance.
The Custom events section shows how to raise this event in a custom plugin when a server returns the 404 Not Found
status code for a resource.
Predefined application events
Ktor provides the following predefined events related to an application's lifecycle:
For example, you can subscribe to the ApplicationStopped
event to release application resources.
Handle events in an application
To handle events for the specified Application
instance, use the monitor
property. This property provides access to the Events instance that exposes the following functions allowing you to handle application events:
subscribe
: subscribes to an event specified by EventDefinition.unsubscribe
: unsubscribes from an event specified by EventDefinition.raise
: raises an event specified by EventDefinition with the specified value.
The subscribe
/unsubscribe
functions accept the EventDefinition
instance with the T
value as a lambda argument. The example below shows how to subscribe to the ApplicationStarted
event and log a message in the event handler:
In this example, you can see how to handle the ApplicationStopped
event:
For the full example, see events.
Handle events in a custom plugin
You can handle events in custom plugins using the MonitoringEvent
hook. The example below shows how to create the ApplicationMonitoringPlugin
plugin and handle the ApplicationStarted
and ApplicationStopped
events:
You can find the full example here: events.
Custom events
In this section, we'll take a look at how to create a custom event raised when a server returns the 404 Not Found
status code for a resource.
First, you need to create the event definition. The code snippet below shows how to create a custom
NotFoundEvent
event that acceptsApplicationCall
as a parameter.val NotFoundEvent: EventDefinition<ApplicationCall> = EventDefinition()To raise the event, call the
Events.raise
function. The sample below shows how to handle theResponseSent
hook to raise the newly created event if the status code for a call is404
.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) } } }To handle the created event in the Application, install the plugin:
fun Application.module() { install(ApplicationMonitoringPlugin) }Then, subscribe to the event using
Events.subscribe
:fun Application.module() { install(ApplicationMonitoringPlugin) monitor.subscribe(NotFoundEvent) { call -> log.info("No page was found for the URI: ${call.request.uri}") } }
For the full exmaple, see events.