Interface LogMetrics

public sealed interface LogMetrics
Metrics are cheap, numeric counters about the logging system itself - for example how many events an appender has dropped, or how often a reused encoder buffer had to shrink itself back down. Unlike LogAlerts, which records discrete events (each with a message/throwable, kept in a bounded ring buffer), metrics are just running totals: no per-call allocation, no ring buffer entry, no listener dispatch.

An instance is available from every LogConfig.metrics(). Components that are provided config, or that are started with config, should prefer capturing config.metrics() over reaching for global state.

Deliberately a separate type from LogAlerts rather than more methods on it - the two are meant to be independently replaceable (e.g. a future Micrometer-backed LogMetrics without needing to also replace how alerts are recorded).

See Also:

  • Field Details

    • EVENTS_DROPPED_METRIC

      static final String EVENTS_DROPPED_METRIC
      Counter name for the global count of log events dropped without ever being written anywhere - for example an appender dropping events on reentry. Incremented whenever a drop happens regardless of whether that particular drop is also logged/alerted, since counting and alerting/logging are separate concerns.
      See Also:

    • BUFFER_TRIMMED_METRIC

      static final String BUFFER_TRIMMED_METRIC
      Counter name for the global count of times a reused encoder buffer had its backing storage shrunk back down after growing past its configured max size (see LogEncoder.Buffer.isOversized()). An occasional trim is normal and expected once in a while, but resizing often is a sign the configured max size (or the initial size) doesn't match the actual event sizes being logged - worth watching, not erroring on, hence warnCounter(String, long) rather than errorCounter(String, long).
      See Also:

    • EVENTS_FAILED_METRIC

      static final String EVENTS_FAILED_METRIC
      Counter name for the global count of log events an appender failed to write - the encoder or output threw while appending, so the event was caught, alerted (see LogAlerts.error(Class, String, Throwable)), and lost rather than retried. Kept separate from EVENTS_DROPPED_METRIC: a drop is a deliberate skip (the appender chose not to write), while this is an unexpected failure partway through actually trying to - different root causes worth distinguishing when triaging.
      See Also:

  • Method Details

    • errorCounter

      void errorCounter(String name, long increment)
      Increments a counter for something worth tracking as "this happens and it matters".
      Parameters:
      name - counter name, e.g. EVENTS_DROPPED_METRIC or a logger name.
      increment - amount to add, usually 1.

    • warnCounter

      void warnCounter(String name, long increment)
      Like errorCounter(String, long) but for something worth tracking yet less significant than an error - a trend worth watching rather than something that, by itself, indicates a problem. Kept as a separate counter namespace from errorCounter(String, long): the same name passed to both is two distinct counters, not one shared one.
      Parameters:
      name - counter name, e.g. BUFFER_TRIMMED_METRIC.
      increment - amount to add, usually 1.

    • counters

      List<LogMetrics.Counter> counters()
      A snapshot of every counter recorded via errorCounter(String, long) and warnCounter(String, long). Counters are monotonically increasing for the life of the process, like a Prometheus/Micrometer counter - there is no reset method; a downstream metrics system computes rate of change rather than relying on the counter itself being reset.
      Returns:
      immutable snapshot.