Package org.apache.sis.util.logging

# Class PerformanceLevel

Object
Level
PerformanceLevel

All Implemented Interfaces:
  `Serializable`

public final class PerformanceLevel extends Level
Logging levels for data processing with execution time measurements. Those levels are used for events that would normally be logged at `Level​.FINE`, but with the possibility to use a slightly higher level if execution time was long. Different logging levels - `SLOW` and `SLOWER` - are provided for logging only the events taking more time than some thresholds. For example the console could log only the slowest events, while a file could log all events considered slow.

Every levels defined in this class have a value between the `Level​.FINE` and `Level​.CONFIG` values. Consequently performance logging are disabled by default, and enabling them imply enabling configuration logging too. This is done that way because the configuration typically have a significant impact on performance.

## Enabling performance logging

Performance logging can be enabled in various ways. Among others:

- The `$JAVA_HOME/lib/logging​.properties` file can be edited in order to log messages at the `FINE` level, at least for the packages of interest.
- The `Logger​.setLevel(Level)` can be invoked, together with `Handler​.setLevel(Level)` on all relevant logging targets (console or file, etc.).
- The `MonolineFormatter​.install(Logger, Level)` convenience method can be invoked.

Since:
  0.3
See Also:
  - Serialized Form

Defined in the `sis-utility` module

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final PerformanceLevel`
  `PERFORMANCE`
  Deprecated.
  Replaced by `Level​.FINE`.
  `static final PerformanceLevel`
  `SLOW`
  The level for logging relatively slow events.
  `static final PerformanceLevel`
  `SLOWER`
  The level for logging only events slower than the ones logged at the `SLOW` level.
  `static final PerformanceLevel`
  `SLOWEST`
  Deprecated.
  Removed for simplification.

  ### Fields inherited from class Level

  `ALL, CONFIG, FINE, FINER, FINEST, INFO, OFF, SEVERE, WARNING`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static Level`
  `forDuration(long duration, TimeUnit unit)`
  Returns the level to use for logging an event of the given duration.
  `long`
  `getMinDuration(TimeUnit unit)`
  Returns the minimal duration for logging an event at this level.
  `void`
  `setMinDuration(long duration, TimeUnit unit)`
  Sets the minimal duration for logging an event at this level.

  ### Methods inherited from class Level

  `equals, getLocalizedName, getName, getResourceBundleName, hashCode, intValue, parse, toString`

  ### Methods inherited from class Object

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- ## Field Details

  - ### PERFORMANCE

    @Deprecated public static final PerformanceLevel PERFORMANCE
    Deprecated.
    Replaced by `Level​.FINE`.
    The level for logging all time measurements, regardless of their duration. The value of this level is 600.
    See Also:
      - SIS-504

  - ### SLOW

    public static final PerformanceLevel SLOW
    The level for logging relatively slow events. By default, only events having an execution time equals or greater than 1 second are logged at this level. However this threshold can be changed by a call to `SLOW.setMinDuration(long, TimeUnit)`.

  - ### SLOWER

    public static final PerformanceLevel SLOWER
    The level for logging only events slower than the ones logged at the `SLOW` level. By default, only events having an execution time equals or greater than 10 seconds are logged at this level. However this threshold can be changed by a call to `SLOWER.setMinDuration(long, TimeUnit)`.

  - ### SLOWEST

    @Deprecated public static final PerformanceLevel SLOWEST
    Deprecated.
    Removed for simplification.
    The level for logging only slowest events.
    See Also:
      - SIS-504

- ## Method Details

  - ### forDuration

    public static Level forDuration(long duration, TimeUnit unit)
    Returns the level to use for logging an event of the given duration. The method may return `Level​.FINE`, `SLOW` or `SLOWER` depending on the duration.
    Parameters:
      `duration` - the event duration.
      `unit` - the unit of the given duration value.
    Returns:
      the level to use for logging an event of the given duration.

  - ### getMinDuration

    public long getMinDuration(TimeUnit unit)
    Returns the minimal duration for logging an event at this level.
    Parameters:
      `unit` - the unit in which to express the minimal duration.
    Returns:
      the minimal duration in the given unit.

  - ### setMinDuration

    @Configuration public void setMinDuration(long duration, TimeUnit unit) throws IllegalArgumentException
    Sets the minimal duration for logging an event at this level. Invoking this method may have an indirect impact of other performance levels:
    - If the given duration is longer than the duration of slower levels, then the later are also set to the given duration.
    - If the given duration is shorter than the duration of faster levels, then the later are also set to the given duration.
    Parameters:
      `duration` - the minimal duration.
      `unit` - the unit of the given duration value.
    Throws:
      `IllegalArgumentException` - if the given duration is zero or negative.