java.lang.Object
net.i2p.util.Log
public class Logextends Object
Wrapper class for whatever logging system I2P uses. This class should be instantiated and kept as a variable for each class it is used by, e.g. private final Log _log = context.logManager().getLog(MyClassName.class);

If there is anything in here that doesn't make sense, turn off your computer and go fly a kite.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    private static final class 
    Log.LogScope
    One named logging scope and its settings.

  • Field Summary

    Modifier and Type
    Field
    Description
    private final Class<?>
    _class
    The class logging through this.
    private final String
    _className
    Name of that class, for the records.
    private final LogManager
    _manager
    The manager holding this logger.
    private int
    _minPriority
    Priority below which messages are dropped.
    private final String
    _name
    Logger name, usually the class name.
    private final Log.LogScope
    _scope
    The scope whose settings apply.
    private LogSuppressor
    _suppressor
    The repeat suppressor backing the *Throttled methods.
    static final int
    CRIT
    Priority of a message about a failure the router could not recover from.
    static final int
    DEBUG
    Priority of a diagnostic message, for debugging only.
    static final int
    ERROR
    Priority of a message about a failure the router recovered from.
    static final int
    INFO
    Priority of an informational message about normal operation.
    static final String
    STR_CRIT
    Property value selecting CRIT messages in the config file.
    static final String
    STR_DEBUG
    Property value selecting DEBUG messages in the config file.
    static final String
    STR_ERROR
    Property value selecting ERROR messages in the config file.
    static final String
    STR_INFO
    Property value selecting INFO messages in the config file.
    static final String
    STR_WARN
    Property value selecting WARN messages in the config file.
    static final int
    WARN
    Priority of a message about a condition that may need attention.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Log(Class<?> cls)
    Warning - not recommended.
    Log(String name)
    Warning - not recommended.
    Log(LogManager manager, Class<?> cls)
    Create a log bound to a class.
    Log(LogManager manager, Class<?> cls, String name)
    Create a log bound to either a class or a name.
    Log(LogManager manager, String name)
    Create a log bound to a name.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    debug(String msg)
    Log a debug message.
    void
    debug(String msg, Throwable t)
    Log a debug message with a throwable.
    boolean
    debugThrottled(String key, String msg)
    Collapse repeats of a debug message.
    void
    error(String msg)
    Log an error message.
    void
    error(String msg, Throwable t)
    Log an error message with a throwable.
    boolean
    errorThrottled(String key, String msg)
    Collapse repeats of an error.
    static int
    getLevel(String level)
    Integer log level for a string level name.
    int
    getMinimumPriority()
    Minimum priority for logging.
    String
    getName()
    Return the name this logger records against.
    Object
    getScope()
    The logging scope object for this log.
    (package private) static String
    getScope(String name, Class<?> cls)
    Scope string for a name and class.
    void
    info(String msg)
    Log an info message.
    void
    info(String msg, Throwable t)
    Log an info message with a throwable.
    boolean
    infoThrottled(String key, String msg)
    Collapse repeats of an info message.
    void
    log(int priority, String msg)
    Log a message at the given priority.
    void
    log(int priority, String msg, Throwable t)
    Log a message with a throwable at the given priority.
    void
    logAlways(int priority, String msg)
    Always log this message with the given priority, ignoring current minimum priority level.
    void
    logCloseLoop(int level, Object... desc)
    Logs a close loop when closing a resource This method is for debugging purposes only and is subject to change or removal w/o notice.
    void
    logCloseLoop(Object... desc)
    Logs a loop when closing a resource with level DEBUG.
    void
    setMinimumPriority(int priority)
    Configure the minimum priority for logging.
    boolean
    shouldDebug()
    Check if DEBUG level logging is enabled.
    boolean
    shouldError()
    Check if ERROR level logging is enabled.
    boolean
    shouldInfo()
    Check if INFO level logging is enabled.
    boolean
    shouldLog(int priority)
    Check if messages at the given priority should be logged.
    boolean
    shouldWarn()
    Check if WARN level logging is enabled.
    boolean
    throttled(int priority, String key, String msg)
    Log a message at the given priority, collapsing repeats of the same condition.
    static String
    toLevelString(int level)
    Convert a log level integer to its string representation.
    void
    warn(String msg)
    Log a warning message.
    void
    warn(String msg, Throwable t)
    Log a warning message with a throwable.
    boolean
    warnThrottled(String key, String msg)
    Collapse repeats of a warning.

    Methods inherited from class Object

    clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • _class

      private final Class<?> _class
      The class logging through this.

    • _className

      private final String _className
      Name of that class, for the records.

    • _name

      private final String _name
      Logger name, usually the class name.

    • _minPriority

      private int _minPriority
      Priority below which messages are dropped.

    • _scope

      private final Log.LogScope _scope
      The scope whose settings apply.

    • _manager

      private final LogManager _manager
      The manager holding this logger.

    • DEBUG

      public static final int DEBUG
      Priority of a diagnostic message, for debugging only. Higher values are more severe; a message is recorded when its priority is at least the logger's configured minimum.
      See Also:

    • INFO

      public static final int INFO
      Priority of an informational message about normal operation. Higher values are more severe; a message is recorded when its priority is at least the logger's configured minimum.
      See Also:

    • WARN

      public static final int WARN
      Priority of a message about a condition that may need attention. Higher values are more severe; a message is recorded when its priority is at least the logger's configured minimum.
      See Also:

    • ERROR

      public static final int ERROR
      Priority of a message about a failure the router recovered from. Higher values are more severe; a message is recorded when its priority is at least the logger's configured minimum.
      See Also:

    • CRIT

      public static final int CRIT
      Priority of a message about a failure the router could not recover from. Higher values are more severe; a message is recorded when its priority is at least the logger's configured minimum.
      See Also:

    • STR_DEBUG

      public static final String STR_DEBUG
      Property value selecting DEBUG messages in the config file.
      See Also:

    • STR_INFO

      public static final String STR_INFO
      Property value selecting INFO messages in the config file.
      See Also:

    • STR_WARN

      public static final String STR_WARN
      Property value selecting WARN messages in the config file.
      See Also:

    • STR_ERROR

      public static final String STR_ERROR
      Property value selecting ERROR messages in the config file.
      See Also:

    • STR_CRIT

      public static final String STR_CRIT
      Property value selecting CRIT messages in the config file.
      See Also:

    • _suppressor

      private volatile LogSuppressor _suppressor
      The repeat suppressor backing the *Throttled methods.

      Lazily created: most logging classes never throttle anything, and this class is instantiated for every class that logs.

  • Constructor Details

    • Log

      public Log(Class<?> cls)
      Warning - not recommended. Use I2PAppContext.getGlobalContext()logManager().getLog(cls).
      Parameters:
      cls - the class whose name prefixes each line logged through this log

    • Log

      public Log(String name)
      Warning - not recommended. Use I2PAppContext.getGlobalContext()logManager().getLog(name).
      Parameters:
      name - the log's name, used in place of a class name to prefix each line

    • Log

      Log(LogManager manager, Class<?> cls)
      Create a log bound to a class.
      Parameters:
      manager - the manager this log reports to
      cls - the class whose name scopes the log

    • Log

      Log(LogManager manager, String name)
      Create a log bound to a name.
      Parameters:
      manager - the manager this log reports to
      name - the name that scopes the log

    • Log

      Log(LogManager manager, Class<?> cls, String name)
      Create a log bound to either a class or a name.
      Parameters:
      manager - the manager this log reports to
      cls - the class whose name scopes the log, or null when scoping by name
      name - the name that scopes the log, or null when scoping by class

  • Method Details

    • getLevel

      public static int getLevel(String level)
      Integer log level for a string level name.
      Parameters:
      level - the level name to convert, matched case-insensitively
      Returns:
      the integer level

    • toLevelString

      public static String toLevelString(int level)
      Convert a log level integer to its string representation.
      Parameters:
      level - the integer level
      Returns:
      the level string

    • log

      public void log(int priority, String msg)
      Log a message at the given priority.
      Parameters:
      priority - one of DEBUG, INFO, WARN, ERROR or CRIT
      msg - the message text to record

    • log

      public void log(int priority, String msg, Throwable t)
      Log a message with a throwable at the given priority.
      Parameters:
      priority - one of DEBUG, INFO, WARN, ERROR or CRIT
      msg - the message text to record
      t - the throwable whose stack trace is logged alongside the message

    • logAlways

      public void logAlways(int priority, String msg)
      Always log this message with the given priority, ignoring current minimum priority level. This allows an INFO message about changing port numbers, for example, to always be logged.
      Parameters:
      priority - the level to record the message at (DEBUG, INFO, WARN, ERROR
      msg - the message text, passed to the log manager's record formatter

    • throttled

      public boolean throttled(int priority, String key, String msg)
      Log a message at the given priority, collapsing repeats of the same condition.

      The first occurrence of key is always written. After that, an occurrence is written once LogSuppressor.DEFAULT_BURST repeats have accumulated or LogSuppressor.DEFAULT_WINDOW_MS have passed, and the line then states how many were collapsed. Use this instead of a plain call when the same condition can repeat thousands of times a minute: the volume hides other messages and drives log rotation for no diagnostic gain.

      Parameters:
      priority - the priority level
      key - stable identifier for the condition; must not vary per occurrence
      msg - the message text to record on the first occurrence and then per burst
      Returns:
      true if the message was written, false if it was suppressed

    • warnThrottled

      public boolean warnThrottled(String key, String msg)
      Collapse repeats of a warning. See throttled(int, String, String).
      Parameters:
      key - stable identifier for the condition
      msg - the message text to record on the first occurrence and then per burst
      Returns:
      true if the message was written

    • errorThrottled

      public boolean errorThrottled(String key, String msg)
      Collapse repeats of an error. See throttled(int, String, String).
      Parameters:
      key - stable identifier for the condition
      msg - the message text to record on the first occurrence and then per burst
      Returns:
      true if the message was written

    • infoThrottled

      public boolean infoThrottled(String key, String msg)
      Collapse repeats of an info message. See throttled(int, String, String).
      Parameters:
      key - stable identifier for the condition
      msg - the message text to record on the first occurrence and then per burst
      Returns:
      true if the message was written

    • debugThrottled

      public boolean debugThrottled(String key, String msg)
      Collapse repeats of a debug message. See throttled(int, String, String).
      Parameters:
      key - stable identifier for the condition
      msg - the message text to record on the first occurrence and then per burst
      Returns:
      true if the message was written

    • debug

      public void debug(String msg)
      Log a debug message.
      Parameters:
      msg - the message text to record

    • debug

      public void debug(String msg, Throwable t)
      Log a debug message with a throwable.
      Parameters:
      msg - the message text to record
      t - the throwable whose stack trace is logged alongside the message

    • info

      public void info(String msg)
      Log an info message.
      Parameters:
      msg - the message text to record

    • info

      public void info(String msg, Throwable t)
      Log an info message with a throwable.
      Parameters:
      msg - the message text to record
      t - the throwable whose stack trace is logged alongside the message

    • warn

      public void warn(String msg)
      Log a warning message.
      Parameters:
      msg - the message text to record

    • warn

      public void warn(String msg, Throwable t)
      Log a warning message with a throwable.
      Parameters:
      msg - the message text to record
      t - the throwable whose stack trace is logged alongside the message

    • error

      public void error(String msg)
      Log an error message.
      Parameters:
      msg - the message text to record

    • error

      public void error(String msg, Throwable t)
      Log an error message with a throwable.
      Parameters:
      msg - the message text to record
      t - the throwable whose stack trace is logged alongside the message

    • getMinimumPriority

      public int getMinimumPriority()
      Minimum priority for logging.
      Returns:
      the minimum priority

    • setMinimumPriority

      public void setMinimumPriority(int priority)
      Configure the minimum priority for logging.
      Parameters:
      priority - the minimum priority

    • shouldLog

      public boolean shouldLog(int priority)
      Check if messages at the given priority should be logged.
      Parameters:
      priority - the priority level
      Returns:
      true if messages at this priority will be logged

    • shouldDebug

      public boolean shouldDebug()
      Check if DEBUG level logging is enabled.
      Returns:
      true if DEBUG messages are recorded, false if the minimum priority excludes them

    • shouldInfo

      public boolean shouldInfo()
      Check if INFO level logging is enabled.
      Returns:
      true if INFO messages are recorded, false if the minimum priority excludes them

    • shouldWarn

      public boolean shouldWarn()
      Check if WARN level logging is enabled.
      Returns:
      true if WARN messages are recorded, false if the minimum priority excludes them

    • shouldError

      public boolean shouldError()
      Check if ERROR level logging is enabled.
      Returns:
      true if ERROR messages are recorded, false if the minimum priority excludes them

    • logCloseLoop

      public void logCloseLoop(Object... desc)
      Logs a loop when closing a resource with level DEBUG. This method is for debugging purposes only and is subject to change or removal w/o notice. NOT a supported API.
      Parameters:
      desc - the objects naming the resource whose close() is being called

    • logCloseLoop

      public void logCloseLoop(int level, Object... desc)
      Logs a close loop when closing a resource This method is for debugging purposes only and is subject to change or removal w/o notice. NOT a supported API.
      Parameters:
      level - level at which to log
      desc - the objects naming the resource whose close() is being called

    • getName

      public String getName()
      Return the name this logger records against.
      Returns:
      the logger class name when one was supplied, otherwise the explicit name

    • getScope

      public Object getScope()
      The logging scope object for this log.
      Returns:
      the scope object, whose Object.equals(Object) compares scope strings

    • getScope

      static String getScope(String name, Class<?> cls)
      Scope string for a name and class.
      Parameters:
      name - the logger name, or null if the class alone identifies it
      cls - the class the logger was created for, or null
      Returns:
      the scope string identifying this logger