Usage

Configure logging programmatically

import seqlog

seqlog.log_to_seq(
   server_url="http://my-seq-server:5341/",
   api_key="My API Key",
   level=logging.INFO,
   batch_size=10,
   auto_flush_timeout=10,  # seconds
   override_root_logger=True,
   json_encoder_class=json.encoder.JSONEncoder  # Optional; only specify this if you want to use a custom JSON encoder
)

For the best experience, use {x}-style named format arguments (passing those format arguments as keyword arguments to the log functions info, warning, error, critical, etc). Using unnamed “holes” (i.e. {}) is not currently supported.

For example:

logging.info("Hello, {name}!", name="World")

If you specify ordinal arguments, the log message is interpreted as a “%s”-style format string. The ordinal format arguments are stored in the log entry properties using the 0-based ordinal index as the property name.

logging.info("Hello, %s!", "World")

Note that mixing named and ordinal arguments is not currently supported.

Configure logging from a file

Seqlog can also use a YAML-format file to describe the desired logging configuration. This file has the schema specified in Python’s logging.config module.

First, create your configuration file (e.g. /foo/bar/my_config.yml):

# This is the Python logging schema version (currently, only the value 1 is supported here).
version: 1

# Configure logging from scratch.
disable_existing_loggers: True

# Configure the root logger to use Seq
root:
  level: INFO
  handlers:
  - seq
  - console

# You can also configure non-root loggers.
loggers:
  another_logger:
      propagate: False
      level: INFO
      handlers:
      - seq
      - console

handlers:
# Log to STDOUT
  console:
    class: seqlog.structured_logging.ConsoleStructuredLogHandler
    formatter: seq

# Log to Seq
  seq:
    class: seqlog.structured_logging.SeqLogHandler
    formatter: seq

    # Seq-specific settings (add any others you need, they're just kwargs for SeqLogHandler's constructor).
    server_url: 'http://localhost:5341'
    api_key: 'your_api_key_if_you_have_one'

    # Use a custom JSON encoder, if you need to.
    json_encoder_class: json.encoder.JSONEncoder

formatters:
  seq:
    style: '{'

Then, call seqlog.configure_from_file():

seqlog.configure_from_file('/foo/bar/my_config.yml')

# Use the root logger.
root_logger = logging.getLogger()
root_logger.info('This is the root logger.')

# Use another logger
another_logger = logging.getLogger('another_logger')
another_logger.info('This is another logger.')

Configuring logging from a dictionary

Seqlog can also use a dictionary to describe the desired logging configuration. This dictionary has the schema specified in Python’s logging.config module.

config = {
  # configuration goes here
}

seqlog.configure_from_dict(config)

# Use the root logger.
root_logger = logging.getLogger()
root_logger.info('This is the root logger.')

# Use another logger
another_logger = logging.getLogger('another_logger')
another_logger.info('This is another logger.')

Batching and auto-flush

By default SeqLog will wait until it has a batch of 10 messages before sending them to Seq. You can control the batch size by passing a value for batch_size.

If you also want it to publish the current batch of events when not enough of them have arrived within a certain period, you can pass auto_flush_timeout (a float representing the number of seconds before an incomplete batch is published).

Overriding the root logger

By default, SeqLog does not modify the root logger (and so calls to logging.info() and friends do not support named format arguments). To also override the root logger, pass True for override_root_logger.

Additional LogHandlers

By default, log_to_seq only configures a single SeqLogHandler.

To configure additional LogHandlers, pass them via additional_handlers.

Global log properties

SeqLog can also add static properties to each log entry that is sent to Seq. By default, the following properties are added:

• MachineName The local machine’s fully-qualified host name.
• ProcessId The current process Id.

To configure global log properties, call set_global_log_properties, passing the properties as keyword arguments:

import seqlog

seqlog.set_global_log_properties(
    GlobalProperty1="foo",
    GlobalProperty2="bar"
    GlobalProperty3=26
)

Note that you can also clear the global log properties (so no properties are added) by calling clear_global_log_properties, and reset the global log properties to their defaults by calling reset_global_log_properties.