Metrics
Colotok reports accepted enqueue attempts, provider rejection and publish failures, and AsyncProvider retention-buffer size. These metrics do not by themselves confirm destination delivery.
MetricsCollector
MetricsCollector is an interface to collect metrics. You can implement this interface to send metrics to your monitoring system like Prometheus, InfluxDB, etc.
recordWriteDuration() is available for custom instrumentation, but Colotok has no built-in production invocation. A future built-in duration metric must first define whether it measures queue wait, handler time, publish time, or end-to-end time.
Runtime Emission Matrix
Event | Log count | Error | Buffer size | Write duration |
|---|---|---|---|---|
Accepted normal record | incremented after enqueue acceptance | none | updated by | not emitted |
Record filtered by level | none | none | none | not emitted |
Full rejection from default synchronous | none |
| none | not emitted |
Rejection after normal close or force shutdown | none |
| none | not emitted |
Rejection after provider failure | none |
| none | not emitted |
Async publish failure | no additional count |
| failed batch retained | not emitted |
Newest record dropped at the retention limit | no additional count |
| remains at the limit | not emitted |
| no self-count | no self-error | no self-update | not emitted |
Collector throws | best-effort metric is lost | no recursive error | no recursive update | not emitted |
The log count is recorded when the provider channel accepts a record, not after destination delivery. Filtered records and LogRecord.Metrics do not produce runtime metrics.
Writing Paths and Backpressure
Provider.write() performs a non-blocking enqueue attempt. With the default SUSPEND overflow policy it does not wait for capacity; when the channel is full, the newest record is rejected and the accepted FIFO prefix remains queued.
AsyncProvider.writeAsync() waits until channel capacity is available, so channel pressure alone does not produce a full rejection. Coroutine *Async calls targeting a regular Provider still delegate to its non-blocking write() path. Rejection after normal close is reported as provider_closed. AsyncProvider.writeAsync() rethrows a failed channel's cause after recording provider_failed; normal closure is reported through metrics without throwing. A regular Provider.write() records rejection metrics without throwing, including when called through the coroutine extension.
Metrics Selection Strategy
You can specify how to collect metrics for each provider using MetricsCollectorSpec.
Inherit
With the default Inherit strategy, registration selects the collector configured in ColotokLoggerContext. Configure it with withMetrics() before adding Providers. Later calls to withMetrics() apply to subsequent registrations; each registered Provider uses its selected collector.
Explicit
The provider uses a specific collector. You can choose whether to also report to the global collector using the inheritParent flag.
CompositeMetricsCollector
Use CompositeMetricsCollector when the same metric callback should be sent to multiple external collectors.
Callbacks are forwarded to every collector in list order. Metrics are best-effort: if one collector throws, the exception is isolated and the remaining collectors still receive the callback. A collector failure does not fail logging, flush(), or join(), so collector exceptions must not be used for application control flow.
MetricsCollectorSpec.Explicit(collector, inheritParent = true) automatically combines the context collector with the explicit collector. Do not also put that same context collector inside a CompositeMetricsCollector unless duplicate metric emission is intentional.
NoOp
The base or external metrics collector is disabled for the provider. Internal metrics logging can still be enabled separately.
Internal Metrics Logging
By setting enableInternalMetricsLogging = true, you can output metrics events as LogRecord.Metrics to the provider itself. This is useful for debugging or monitoring without external infrastructure.
Internal metrics logging can be used alongside MetricsCollectorSpec. For example, you can report to a global Prometheus collector while also logging metrics events to a local file.
Internal metrics use the same provider level filter and channel. For AsyncProvider, they also use the same retention buffer. They can be rejected under capacity pressure, but LogRecord.Metrics does not emit further metrics, preventing recursive growth.