Interface LogMetrics

public sealed interface LogMetrics
Numeric metrics about the logging system itself. Counters track running totals such as dropped events; gauges track values that can rise and fall, such as queued events. Unlike LogAlerts, updating a metric does not create an alert or notify listeners. Retain a LogMetrics.Gauge for frequent updates without a name lookup.

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:

    • EVENTS_QUEUED_METRIC

      static final String EVENTS_QUEUED_METRIC
      Gauge name for the aggregate number of events waiting in async publisher buffers. Events removed for processing are no longer counted, even while their output is being written. Concurrent snapshots can briefly lead or lag queue activity.
      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:

    • REOPEN_FAIL_METRIC

      static final String REOPEN_FAIL_METRIC
      Counter name for the global count of failed appender output reopen attempts. Each failed attempt increments this counter in addition to recording an alert, regardless of the appender or output type.
      See Also:

    • REOPEN_METRIC

      static final String REOPEN_METRIC
      Counter name for the global count of appender output reopen attempts, whether successful or failed. Subtract REOPEN_FAIL_METRIC to obtain the number of successful attempts.
      See Also:

    • ROLL_FAIL_METRIC

      static final String ROLL_FAIL_METRIC
      Counter name for failed automatic file rotation attempts, including closing the active output, rotating archives, and opening the replacement output. Recovery attempts that fail also increment this counter. External rotation followed by an explicit reopen is counted by REOPEN_FAIL_METRIC instead. Events lost because rotation failed are also counted by EVENTS_FAILED_METRIC.
      See Also:

    • LOGGER_NAMES_METRIC

      static final String LOGGER_NAMES_METRIC
      Counter name for the running count of distinct logger names registered via LogConfig.LoggerRegistry.registerLoggerName(LoggerAPI, String). Not itself a problem, hence infoCounter(String, long) rather than warnCounter(String, long), but worth watching: a count that keeps climbing without bound is a sign something is using per-request/per-entity data (e.g. a request id) as a logger name instead of a fixed, bounded set of names.
      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.

    • infoCounter

      void infoCounter(String name, long increment)
      Like errorCounter(String, long) but for a plain running total, not inherently a problem or even a trend worth watching. Kept as a separate counter namespace from errorCounter(String, long)/warnCounter(String, long): the same name passed to more than one of these is a distinct counter per method, not one shared one.
      Parameters:
      name - counter name, e.g. LOGGER_NAMES_METRIC.
      increment - amount to add, usually 1.

    • gauge

      LogMetrics.Gauge gauge(String name, System.Logger.Level level)
      Creates a handle for updating a named value directly. For INFO, WARNING, and ERROR, each call returns a new handle sharing the value for the same name and level; retain the handle for frequent updates without repeated name lookups. The value is initially zero and appears in snapshot() as soon as the handle is created. Counter methods for the same name and level share this value too. Levels below INFO and OFF return a shared no-op handle and do not register a metric.
      Parameters:
      name - metric name.
      level - significance of the metric.
      Returns:
      a handle to the shared value, or a no-op handle.

    • snapshot

      List<LogMetrics.Metric> snapshot()
      A snapshot of every metric recorded via errorCounter(String, long), warnCounter(String, long), infoCounter(String, long), and gauge(String, Level). Counter values increase over time; gauge values can also decrease. Snapshots are approximate while updates are concurrent.
      Returns:
      immutable snapshot.