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:

• LogConfig.metrics()

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	LogMetrics.Gauge	A retained handle for incrementing or decrementing a metric.
static final record	LogMetrics.Metric	A single named metric's current value, as returned by snapshot().
static enum	LogMetrics.StandardMetric	The fixed, well known set of metrics RainbowGum itself records, as opposed to the open ended, per logger name counters LogAlerts.alert(LogEvent) also drives into the counter matching the alert's level.

Field Summary

Fields

Modifier and Type	Field	Description
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()).
static final String	EVENTS_DEDUPLICATED_METRIC	Counter name for the global count of log events the dedupe route filter dropped as repeats.
static final String	EVENTS_DISCARDED_METRIC	Counter name for the global count of log events an async publisher discarded because its configured overload policy chose to, rather than wait for buffer space.
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.
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.
static final String	EVENTS_FILTERED_METRIC	Counter name for the global count of log events a route's filters dropped, including events a filter moved to a level the route does not enable.
static final String	EVENTS_QUEUED_METRIC	Gauge name for the aggregate number of events waiting in async publisher buffers.
static final String	EVENTS_THROTTLED_METRIC	Counter name for the global count of log events the throttle route filter dropped because more arrived than its rate allows.
static final String	LOGGER_NAMES_METRIC	Counter name for the running count of distinct logger names registered via LogConfig.LoggerRegistry.registerLoggerName(LoggerAPI, String).
static final String	REOPEN_FAIL_METRIC	Counter name for the global count of failed appender output reopen attempts.
static final String	REOPEN_METRIC	Counter name for the global count of appender output reopen attempts, whether successful or failed.
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.

Method Summary

Modifier and Type	Method	Description
void	errorCounter(String name, long increment)	Increments a counter for something worth tracking as "this happens and it matters".
LogMetrics.Gauge	gauge(String name, System.Logger.Level level)	Creates a handle for updating a named value directly.
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.
List<LogMetrics.Metric>	snapshot()	A snapshot of every metric recorded via errorCounter(String, long), warnCounter(String, long), infoCounter(String, long), and gauge(String, Level).
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.

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:

• Constant Field Values

EVENTS_DISCARDED_METRIC

static final String EVENTS_DISCARDED_METRIC

Counter name for the global count of log events an async publisher discarded because its configured overload policy chose to, rather than wait for buffer space. Kept separate from EVENTS_DROPPED_METRIC: the application opted into discarding, so it is a warning, not an error.

See Also:

• Constant Field Values

EVENTS_FILTERED_METRIC

static final String EVENTS_FILTERED_METRIC

Counter name for the global count of log events a route's filters dropped, including events a filter moved to a level the route does not enable. Filtering is usually intended, so it is an info counter.

See Also:

• Constant Field Values

EVENTS_THROTTLED_METRIC

static final String EVENTS_THROTTLED_METRIC

Counter name for the global count of log events the throttle route filter dropped because more arrived than its rate allows. They are also counted by EVENTS_FILTERED_METRIC. Events lost to load are worth watching, so it is a warning counter.

See Also:

• Constant Field Values

EVENTS_DEDUPLICATED_METRIC

static final String EVENTS_DEDUPLICATED_METRIC

Counter name for the global count of log events the dedupe route filter dropped as repeats. They are also counted by EVENTS_FILTERED_METRIC. It is a warning counter like EVENTS_THROTTLED_METRIC.

See Also:

• Constant Field Values

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:

• Constant Field Values

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:

• Constant Field Values

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:

• Constant Field Values

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:

• Constant Field Values

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:

• Constant Field Values

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:

• Constant Field Values

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:

• Constant Field Values

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.