Log

vortex uses the spdlog library for high-performance logging in C++. This module provides a simplified Python wrapper for spdlog so that Python users of vortex can configure logging.

C++

This module exists only as Python bindings. C++ users may configure spdlog directly according to its documentation.

Overview

The log module exposes logger objects and sinks. Much like the Python logging framework, loggers create records with a configured name whereas sinks format and process those records. Logger objects have a severity level to determine which events produce records.

Note

vortex configures spdlog for asynchronous record sinking in a single background thread when compiled in release mode. This scheme offloads handling from critical threads and preserves ordering of log records, but temporal ordering with respect to other console output is not guaranteed.

Loggers

Create a Logger directly or use a helper function below.

class vortex.log.Logger

Loggers create records and then route them to associated sinks.

__init__(name, sink=None, sinks=None)

Create a logger with the given name and optionally attack the provided sink/sinks. Sinks may be added or removed after the logger is created.

Parameters:

  • name (str) – The name of the logger

  • sink (vortex.log.Sink) – A single sink to attach to this logger. Mutually exclusive with sinks argument.

  • sinks ([vortex.log.Sink]) – A list of sinks to attach to this logger. Mutually exclusive with sink argument.

property name: str

Name of this logger. Read only.

property level: int

Severity level for events to produce a record.

property sinks: [vortex.log.Sink]

List of attached sinks. Read-only.

Caution

This property is not thread-safe. Do not read this property when adding or removing sinks elsewhere.

set_pattern(pattern)

Change the pattern for this logger. The pattern is applied to all attached sinks as well. See the spdlog reference for pattern fields. The default pattern is d-%b-%Y %H:%M:%S.%f] %-10n %^(%L) %v%$.

Parameters:

pattern (str) – The new pattern.

add_sink(sink)

Attach a sink to this logger. Attaching a sink that is already attached has no effect.

Caution

This method is not thread-safe. Do not call this method when a log record might be emitted (e.g., when the engine is running) or while manipulating the list of attached sinks elsewhere.

Parameters:

sink (vortex.log.Sink) – The sink to attach.

remove_sink(sink)

Remove a sink from this logger. Removing a sink that is not attached has no effect.

Caution

This method is not thread-safe. Do not call this method when a log record might be emitted (e.g., when the engine is running) or while manipulating the list of attached sinks elsewhere.

log(level, msg)

Emit a log record with the given severity level. See spdlog’s source for further details.

Level

Value

trace

0

debug

1

info

2

warn

3

error

4

critical

5

off

6
Parameters:

  • level (int) – Severity level of the message.

  • msg (str) – Message to log.

trace(msg)

Log a message at the trace level.

Parameters:

msg (str) – Message to log.

debug(msg)

Log a message at the debug level.

Parameters:

msg (str) – Message to log.

info(msg)

Log a message at the info level.

Parameters:

msg (str) – Message to log.

warn(msg)

Log a message at the warn level.

Parameters:

msg (str) – Message to log.

error(msg)

Log a message at the error level.

Parameters:

msg (str) – Message to log.

critical(msg)

Log a message at the critical level.

Parameters:

msg (str) – Message to log.

flush()

Flush all attached sinks.

clone(name)

Copy the current logger. This logger and its copy have the same sinks attached.

Parameters:

name (str) – Name of the copied logger.

Returns:

vortex.log.Logger – The copy.

Sinks

Sinks receive log records and route them for further processing.

class vortex.log.Sink

Abstract base class for all sinks.

property level: int

Severity level for log records undergo processing.

set_pattern(pattern)

Set the formatting pattern for this sink. See Logger.set_pattern.

Note

Calling Logger.set_pattern propagates the new pattern to all attached sinks, overwriting any local changes by this method.

flush()

Ensure all log records have completed processing.

class vortex.log.StdOutSink

Base: Sink

A sink that formats log records to standard out.

All members are inherited.

class vortex.log.StdErrSink

Base: Sink

A sink that formats log records to standard error.

All members are inherited.

class vortex.log.ConsoleSink

An alias for StdErrSink.

class vortex.log.FileSink

Base: Sink

A sink that formats log records to a file.

property filename: str

Path of file to store log output. Read-only.

change(filename, truncate=False)

Change the file path of the sink.

Note

This method is thread-safe.

Parameters:

  • filename (str) – The new file path.

  • truncate (bool) – Erase the new file upon opening it if True.

class vortex.log.PythonSink

Base: Sink

A sink that injects log records into the Python logging system. Internally, this sink creates and caches a Python logging.Logger of the appropriate name and forwards logging.LogRecords to logging.Logger.handle(). Severity levels are translated from spdlog to Python after by multiplying their numeric value by multiplying by 10. The log scope is the name of the Logger.

spdlog

Python

Level

Value

Level

Value

trace

0

NOTSET

0

debug

1

DEBUG

10

info

2

INFO

20

warn

3

WARNING

30

error

4

ERROR

40

critical

5

CRITICAL

50

off

6

Attention

Avoid configuring this sink to accept high-frequency log output (e.g., trace-level) as this may degrade logging or application performance.

Note

It is most efficient to create a single application-wide PythonSink since this avoid duplication of Python logging.Loggers.

Helpers

These functions create a logger and sink with a single function call, which is helpful for simple applications or debugging.

Note

These functions are inefficient for larger applications since a new, independent sink is created each call. Larger applications should instead prefer to create sinks manually and attach all required loggers.

Attention

In earlier undocumented versions, these functions returned previously-created loggers if a logger of the same name was requested. This is no longer the case since a new logger and sink pair is created during each call.

vortex.get_console_logger(name, level=2)

Create a Logger using the given name and level and attach a new StdErrSink to it.

Returns:

vortex.log.Logger – The new logger.

vortex.get_file_logger(name, filename, level=2)

Create a Logger using the given name and level and attach a new FileSink with the given filename.

Returns:

vortex.log.Logger – The new logger.

vortex.get_python_logger(name, scope='vortex', level=2)

Create a Logger using the given name and level and attach a new PythonSink with the given scope. The logger’s resulting name is {scope}.{name}.

Returns:

vortex.log.Logger – The new logger.