logdna 1.4.1

A Python Package for Sending Logs to LogDNA

Python package for logging to LogDNA

---

• Install
• Setup
• Usage
• API
• License

Install

$ pip install logdna

Setup

import logging
from logdna import LogDNAHandler

key = 'YOUR INGESTION KEY HERE'

log = logging.getLogger('logdna')
log.setLevel(logging.INFO)

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

# Defaults to false, when true ensures meta object will be searchable
options['index_meta'] = True

test = LogDNAHandler(key, options)

log.addHandler(test)

log.warn("Warning message", {'app': 'bloop'})
log.info("Info message")

Required

• LogDNA Ingestion Key

Optional

• Hostname - (String) - max length 32 chars
• MAC Address - (String)
• IP Address - (String)
• Max Length - (Boolean) - formatted as options['max_length']
• Index Meta - (Boolean) - formatted as options['index_meta']

Usage

After initial setup, logging is as easy as:

# Simplest use case
log.info('My Sample Log Line')

# Add a custom level
log.info('My Sample Log Line', { 'level': 'MyCustomLevel' })

# Include an App name with this specific log
log.info('My Sample Log Line', { 'level': 'Warn', 'app': 'myAppName'})

# Pass any associated objects along as metadata
meta = {
    'foo': 'bar',
    'nested': {
      'nest1': 'nested text'
    }
}

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

log.info('My Sample Log Line', opts)

Usage with File Config

To use LogDNAHandler with fileConfig (e.g., in a Django settings.py file):

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': os.environ.get('LOGDNA_INGEST_KEY'),
            'options': {
                'app': '<app name>',
                'env': os.environ.get('ENVIRONMENT'),
                'index_meta': <True|False>,
            },
        },
    },
    'loggers': {
        '': {
            'handlers': ['logdna'],
            'level': logging.DEBUG
        },
    },
}

(This example assumes you have set environment variables for ENVIRONMENT and LOGDNA_INGEST_KEY)

API

LogDNAHandler(key, [options])

---

key

• Required
• Type: String
• Values: YourAPIKey

The LogDNA API Key associated with your account.

options

app

• Optional
• Type: String
• Default: ''
• Values: YourCustomApp
• Max Length: 32

The default app passed along with every log sent through this instance.

env

• Optional
• Type: String
• Default: ''
• Values: YourCustomEnv
• Max Length: 32

The default env passed along with every log sent through this instance.

hostname

• Optional
• Type: String
• Default: ''
• Values: YourCustomHostname
• Max Length: 32

The default hostname passed along with every log sent through this instance.

include_standard_meta

• Optional
• Type: Boolean
• Default: False

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

index_meta

• Optional
• Type: Boolean
• Default: False

We allow meta objects to be passed with each line. By default these meta objects will be stringified and will not be searchable, but will be displayed for informational purposes.

If this option is turned to true then meta objects will be parsed and will be searchable up to three levels deep. Any fields deeper than three levels will be stringified and cannot be searched.

WARNING When this option is true, your metadata objects across all types of log messages MUST have consistent types or the metadata object may not be parsed properly!

level

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

The default level passed along with every log sent through this instance.

verbose

• Optional
• Type: String or Boolean
• Default: true
• Values: False or any level

The verbosity of the log statements in each failure.

request_timeout

• Optional
• Type: int
• Default: 30000

The amount of time the request should wait for LogDNA to respond before timing out.

tags

• Optional
• Type: String[]
• Default: []

List of tags used to dynamically group hosts. More information on tags is available at How Do I Use Host Tags?

url

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

The custom ingestion endpoint to stream the log lines into.

log(line, [options])

---

line

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

The line which will be sent to the LogDNA system.

options

level

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

The level passed along with this log line.

app

• Optional
• Type: String
• Default: ''
• Values: YourCustomApp
• Max Length: 32

The app passed along with this log line.

env

• Optional
• Type: String
• Default: ''
• Values: YourCustomEnv
• Max Length: 32

The environment passed with this log line.

meta

• Optional
• Type: JSON
• Default: None

A meta object for additional metadata about the log line that is passed. Please ensure values are JSON serializable, values that are not JSON serializable will be removed and the respective keys will be added to the __errors string.

index_meta

• Optional
• Type: Boolean
• Default: False

We allow meta objects to be passed with each line. By default these meta objects will be stringified and will not be searchable, but will be displayed for informational purposes.

If this option is turned to true then meta objects will be parsed and will be searchable up to three levels deep. Any fields deeper than three levels will be stringified and cannot be searched.

WARNING When this option is true, your metadata objects across all types of log messages MUST have consistent types or the metadata object may not be parsed properly!

timestamp

• Optional
• Default: time.time()

A timestamp in ms, must be within one day otherwise it will be dropped and time.time() will be used in its place.

License

MIT © LogDNA

Happy Logging!