GitHub

Send logs from Python applications to LogDNA.

Requirements

Requires Python 3 and Pip.

Installation

Run the following command:

$ pip install logdna

Or add logdna to your requirements.txt file and run:

$ pip install -r requirements.txt

Configuration

LogDNA providers a handler that you can add to Python's logging facility. Create a logger using logging.getLogger(), then import LogDNAHandler from the logdna module. Initialize a new LogDNAHandler object, then add it to the logger using addHandler():

import logging
from logdna import LogDNAHandler

apiKey = 'YOUR LOGDNA INGESTION KEY'

logger = logging.getLogger('logdna')

options = {
  'hostname': 'pytest',
  'ip': '10.0.1.1',
  'mac': 'C0:FF:EE:C0:FF:EE',
  'index_meta': True
}

handler = LogDNAHandler(apiKey, options)

logger.addHandler(handler)

apiKey

• Required
• Type: String

The LogDNA Ingestion Key associated with your account.

options

• Optional
• Type: JSON
• Default: null

An array of optional arguments used to configure the logger.

app

• Type: String
• Default: ''
• Example: YourCustomApp
• Max Length: 32

The name of the application.

hostname

• Type: String
• Default: ''
• Example: YourCustomHostname
• Max Length: 32

The name of the host.

mac

• Type: String
• Default ''
• Example: 52:54:00:41:65:41

The network MAC address of the host.

ip

• Type: String
• Default: ''
• Example: 10.0.0.1

The IP address of the host.

level

• Type: String
• Default: Info
• Examples: Debug, Trace, Info, Warn, Error, Fatal, YourCustomLevel
• Max Length: 32

The default level (or severity) of each log event.

env

• Type: String
• Default: ''
• Example: Development, Staging, Production
• Max Length: 32

The environment that the application is running in.

meta

• Type: JSON
• Default: null

A JSON object that provides additional context about the log event. You can control how LogDNA parses metadata using index_meta.

include_standard_meta

• Type: Boolean
• Default: False

Python LogRecord objects include language-specific information that may be useful metadata in logs. Setting include_standard_meta to True automatically populates meta objects with name, pathname, and lineno from the LogRecord. See the Python documentation on LogRecord for more information.

index_meta

• Type: Boolean
• Default: False

We allow metadata to be passed with each line. If this option is disabled (it is by default), LogDNA will store metadata objects as one string and will not index them or make them searchable.

If this option is set to True, then meta objects will be parsed, indexed, and made searchable up to three levels deep. Any fields deeper than three levels will be stringified and cannot be searched.

WARNING: When this option is enabled, your metadata must have a consistent typing across all of your logs. Otherwise, it may not be parsed properly!

verbose

• Type: String or Boolean
• Default: True
• Values: False, or any log level

Sets the verbosity of log statements for failures.

request_timeout

• Type: int
• Defualt: 30000

The amount of time (in milliseconds) the request will wait for LogDNA to respond before timing out.

tags

• Type: String[]
• Default: []

List of tags used to group log messages. Read the LogDNA documentation on tags for more information.

url

• Type: String
• Default: https://logs.logdna.com/logs/ingest

The URL to send logs to. Defaults to LogDNA’s cloud ingestion servers.

Using File-based Configuration

You can store your LogDNAHandler configuration in a file and read it with fileConfig (e.g. in a Django settings.py file).

Add the following to your config file (add, remove, or modify each option to your needs):

import os
import logging
from logdna import LogDNAHandler #  required to register `logging.handlers.LogDNAHandler`

LOGGING = {
    # Other logging settings...
    'handlers': {
        'logdna': {
            'level': logging.DEBUG,
            'class': 'logging.handlers.LogDNAHandler',
            'key': '<LogDNA ingestion key>',
            'options': {
                'app': '<app name>',
                'env': '<environment>',
                'index_meta': <True|False>,
            },
        },
    },
    'loggers': {
        '': {
            'handlers': ['logdna'],
            'level': logging.DEBUG
        },
    },
}

Usage

log(line, [options])

Generates a log message and sends it to LogDNA.

line

• Required
• Type: String
• Default: ''
• Max Length: 3200

The text that makes up the log message.

options

• Optional
• Type: JSON
• Default: null

An array of optional arguments used to configure the log message. This supports the same arguments as the options object in the Configuration section, as well as the following arguments:

timestamp

• Type: float
• Default: Current value of time.time()

The time in seconds since the epoch to use for the log timestamp. It must be within one day or the current time - if it is not, it is ignored and time.time() is used in its place.

Examples

To send a log, use the log method:

logger.log('This is a log.')

Send logs with a particular level using the log.<level> methods:

logger.info('This is an info log.')
logger.warning('This is a warning log.')
logger.error('This is an error log.')

You can also pass options to a logger call to set custom options for a specific log event. Here, we set the level and add an app name for a specific log:

log.info('An info log', { 'level': 'Warn', 'app': 'myAppName'})

Here, we also add metadata to our log using the meta object:

meta = {
    'foo': 'bar',
    'nested': {
        'nest1': 'nested text'
    }
}

opts = {
    'level': 'warn',
    'meta': meta
}

log.info('An info log', opts)

setLevel(level)

Sets the default level for new log events.

log.setLevel(logging.INFO)