Developer Interface

class jsonscribe.AttributeSetter(*args, **kwargs)[source]

Ensure that attributes exist on LogRecord s.


add_fields (dict) – maps fields to create on LogRecord instances to their default values

The values in the add_fields mapping can be strings that start with 'ext://' to invoke custom behaviors. The following values are recognized:


Generate a new UUIDv4 instance via uuid.uuid4()


Generate a new timezone-aware UTC datetime.datetime instance


Determine if the specified record is to be logged.

Is the specified record to be logged? Returns 0 for no, nonzero for yes. If deemed appropriate, the record may be modified in-place.

class jsonscribe.JSONFormatter(*args, **kwargs)[source]

Format log records as JSON documents.

  • include_fields (list) – fields from a LogRecord that are included in the JSON bodies

  • use_loggly_names (bool) – if specified and True, then spaces, hyphens, and underscores are removed from field names.

This class will format logging.LogRecord instances into JSON bodies that are output as single lines by most logging.Handler instances. The result is your log messages collected together as a nice json-lines file.

You have to set the list of fields to include in the JSON bodies during initialization. If you are using the logging.config.dictConfig() function to configure the logging layer, then use the following syntax to configure the formatter factory with the fields that you want to include in the log messages:

'formatters': {
    'json': {
        '()': 'jsonscribe.JSONFormatter',
        'include_fields': ['message']

You can use any of the fields of LogRecord and they will be included. This includes fields that you add using either the extras keyword parameter or a logging.LoggerAdapter. If you happen to reference a field that does not exist, then None is used by default. This avoids completely blowing up because when you make a mistake logging.

A few fields have special handling applied to them. The exc_info field is formatted as an array of strings instead of a blob of newline separated text. Other fields are passed as-is to the JSON encoder with _jsonify() used as the default keyword to the encoder.


A single json.JSONEncoder instance is used throughout the lifetime of the formatter instance. You can modify it if necessary.


The use_loggly_names parameter SHOULD be set to True in the configuration if the logs are being sent to Failure to do this will result in some fields not being correctly indexed.


Provide formatting for common object types.


obj – an object that the default json.JSONEncoder cannot format


a decent str representation of obj

Unlike the standard JSON library, this hook will not raise an exception for an unserializable object. It returns the objects repr instead.


Format a log record to a JSON object.


record (logging.LogRecord) – the record to format


the JSON formatted version of record as a string

Return type


class jsonscribe.utils.UTCZone[source]

Free-standing implementation of the UTC timezone.

This is implemented to provide some compatibility with older Python versions.


datetime -> DST offset as timedelta positive east of UTC.


datetime in UTC -> datetime in local time.


datetime -> string name of time zone.


datetime -> timedelta showing offset from UTC, negative values indicating West of UTC

jsonscribe.utils.utc = <jsonscribe.utils.UTCZone object>

UTC timezone instance.

Use this with to produce a timezone aware UTC timestamp.