# Logbook

# Utilities

## Misc. Utilities

This documents general purpose utility functions available in Logbook.

logbook.debug(*args, **kwargs)

  Logs a `LogRecord` with the level set to `DEBUG`.

logbook.info(*args, **kwargs)

  Logs a `LogRecord` with the level set to `INFO`.

logbook.warn(*args, **kwargs)

  Logs a `LogRecord` with the level set to `WARNING`. This function has an alias named `warning()`.

logbook.warning(*args, **kwargs)

  Alias for `warn()`.

logbook.notice(*args, **kwargs)

  Logs a `LogRecord` with the level set to `NOTICE`.

logbook.error(*args, **kwargs)

  Logs a `LogRecord` with the level set to `ERROR`.

logbook.exception(*args, **kwargs)

  Works exactly like `error()` just that the message is optional and exception information is recorded.

logbook.catch_exceptions(*args, **kwargs)

  A context manager that catches exceptions and calls `exception()` for exceptions caught that way. Example:

      with logger.catch_exceptions():
          execute_code_that_might_fail()

logbook.critical(*args, **kwargs)

  Logs a `LogRecord` with the level set to `CRITICAL`.

logbook.log(level, *args, **kwargs)

  Logs a `LogRecord` with the level set to the level parameter. Because custom levels are not supported by logbook, this method is mainly used to avoid the use of reflection (e.g.: `getattr()`) for programmatic logging.

logbook.set_datetime_format(datetime_format)

  Set the format for the datetime objects created, which are then made available as the `LogRecord.time` attribute of `LogRecord` instances.

  Parameters

    datetime_format – Indicates how to generate datetime objects.

  Possible values are:

  > “utc”

  >   `LogRecord.time` will be a datetime in UTC time zone (but not time zone aware)

  > “local”

  >   `LogRecord.time` will be a datetime in local time zone (but not time zone aware)

  > A callable returning datetime instances

  >   `LogRecord.time` will be a datetime created by `datetime_format` (possibly time zone aware)

  This function defaults to creating datetime objects in UTC time, using datetime.utcnow(), so that logbook logs all times in UTC time by default. This is recommended in case you have multiple software modules or instances running in different servers in different time zones, as it makes it simple and less error prone to correlate logging across the different servers.

  On the other hand if all your software modules are running in the same time zone and you have to correlate logging with third party modules already logging in local time, it can be more convenient to have logbook logging to local time instead of UTC. Local time logging can be enabled like this:

      import logbook
      from datetime import datetime
      logbook.set_datetime_format("local")

  Other uses rely on your supplied `datetime_format`. Using pytz for example:

      from datetime import datetime
      import logbook
      import pytz

      def utc_tz():
          return datetime.now(tz=pytz.utc)

      logbook.set_datetime_format(utc_tz)

## Slow Operations Logging

logbook.utils.logged_if_slow(*args, **kwargs)

  Context manager that logs if operations within take longer than threshold seconds.

  Parameters

    - threshold – Number of seconds (or fractions thereof) allwoed before logging occurs. The default is 1 second.

    - logger – `Logger` to use. The default is a ‘slow’ logger.

    - level – Log level. The default is DEBUG.

    - func – (Deprecated). Function to call to perform logging.

  The remaining parameters are passed to the `log()` method.

## Deprecations

logbook.utils.deprecated(func=None, message=None)

  Marks the specified function as deprecated, and emits a warning when it’s called.

      >>> @deprecated(message='No longer supported')
      ... def deprecated_func():
      ...     pass

  This will cause a warning log to be emitted when the function gets called, with the correct filename/lineno.

  New in version 0.12.

logbook.utils.suppressed_deprecations()

  Disables deprecation messages temporarily

      >>> with suppressed_deprecations():
      ...    call_some_deprecated_logic()

  New in version 0.12.