logdna/python - Githubissues

Python package for logging to LogDNA

Installation
Setup
Usage
- Usage with fileConfig
API
Development
- Scripts
License

Installation

$ pip install logdna

Setup

import logging
from logdna import LogDNAHandler
import os

# Set your key as an env variable
# then import here, its best not to
# hard code your key!
key=os.environ['INGESTION_KEY']

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 meta objects are searchable
options['index_meta'] = True
options['custom_fields'] = 'meta'

test = LogDNAHandler(key, options)

log.addHandler(test)

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

Required

LogDNA Ingestion Key

Optional

Hostname - (string)
MAC Address - (string)
IP Address - (string)
Index Meta - (bool) - 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', extra={ 'level': 'MyCustomLevel' })

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

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

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

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

Usage with fileConfig

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_INGESTION_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_INGESTION_KEY.)

API

LogDNAHandler(key: string, [options: dict])

key

Required
Type: string
Values: <your ingestion key>

The LogDNA API Key associated with your account.

options

app

Optional
Type: string
Default: ''
Values: <your custom app>

The default app named that is included in every every log line sent through this instance.

env

Optional
Type: string
Default: ''
Values: <your custom env>

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

hostname

Optional
Type: string
Default: ''
Values: <your custom hostname>

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

include_standard_meta

Optional
Type: bool
Default: False

Python LogRecord objects includes 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.

WARNING This option is deprecated and will be removed in the upcoming major release.

index_meta

Optional
Type: bool
Default: False

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

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

WARNING If this option is True, your metadata objects MUST have consistent types across all log messages or the metadata object might not be parsed properly.

level

Optional
Type: string
Default: Info
Values: Debug, Trace, Info, Warn, Error, Fatal, <your custom level>

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

verbose

Optional
Type: string or bool
Default: True
Values: False or any level

Sets the verbosity of log statements for failures.

request_timeout

Optional
Type: int
Default: 30000

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

url

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

A custom ingestion endpoint to stream log lines into.

custom_fields

Optional
Type: list<string>
Default: ['args', 'name', 'pathname', 'lineno']

List of fields out of record object to include in the meta object. By default, args, name, pathname, and lineno will be included.

log_error_response

Optional
Type: bool
Default: False

Enables logging of the API response when an HTTP error is encountered

log(line, [options])

line

Required
Type: string
Default: ''

The log line to be sent to LogDNA.

options

level

Optional
Type: string
Default: Info
Values: Debug, Trace, Info, Warn, Error, Fatal, <your custom level>

The level passed along with this log line.

app

Optional
Type: string
Default: ''
Values: <your custom app>

The app passed along with this log line.

env

Optional
Type: string
Default: ''
Values: <your custom env>

The environment passed with this log line.

index_meta

Optional
Type: bool
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
Type: float
Default: time.time()

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

Development

This project makes use of the poetry package manager for local development.

$ poetry install

Scripts

lint Run linting rules w/o attempting to fix them

$ poetry run task lint

lint:fix

Run lint rules against all local python files and attempt to fix where possible.

$ poetry run task lint:fix

test:

Runs all unit tests and generates coverage reports

poetry run task test

Contributors ✨

Thanks goes to these wonderful people (emoji key):

_{Muaz Siddiqui} 💻 📖 ⚠️	_{Samir Musali} 💻 📖 ⚠️	_vilyapilya 💻 🚧 ⚠️	_{Mike Hu} 📖	_{Eric Satterwhite} 💻 📖 ⚠️ 🔧	_{Łukasz Bołdys (Lukasz Boldys)} 💻 🐛	_Ryan 📖
_{Mike Huang} 💻 🐛	_{Dan Maas} 💻	_DChai 📖	_{Jakob de Maeyer} 💻	_{Andrey Babak} 💻	_{Mike S} 💻 📖	_{Brennan Ashton} 💻
_{Christian Hotz-Behofsits} 💻 🐛	_{Kurtiss Hare} 🐛	_{Alexey Kinev} 🐛	_matthiasfru 🐛