Python package for logging to LogDNA
$ pip install logdna
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
test = LogDNAHandler(key, options)
log.addHandler(test)
log.warning("Warning message", {'app': 'bloop'})
log.info("Info message")
Required
Optional
- Hostname - (string) - max length 32 chars
- MAC Address - (string)
- IP Address - (string)
- Max Length - (bool) - formatted as options['max_length']
- Index Meta - (bool) - formatted as options['index_meta']
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 associated objects along as metadata
meta = {
'foo': 'bar',
'nested': {
'nest1': 'nested text'
}
}
opts = {
'level': 'warn',
'meta': meta
}
log.info('My Sample Log Line', opts)
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
)
- Required
- Type: string
- Values:
YourAPIKey
The LogDNA API Key associated with your account.
- Optional
- Type: string
- Default:
''
- Values:
YourCustomApp
- Max Length:
32
The default app passed along with every log sent through this instance.
- Optional
- Type: string
- Default:
''
- Values:
YourCustomEnv
- Max Length:
32
The default env passed along with every log sent through this instance.
- Optional
- Type: string
- Default:
''
- Values:
YourCustomHostname
- Max Length:
32
The default hostname passed along with every log sent through this instance.
- 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.
- 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 may not be parsed properly.
- 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.
Sets the verbosity of log statements for failures.
- Optional
- Type: int
- Default:
30000
The amount of time (in ms) the request should wait for LogDNA to respond before timing out.
List of tags used to dynamically group hosts. More information on tags is available at How Do I Use Host Tags?
- Optional
- Type: string
- Default:
'https://logs.logdna.com/logs/ingest'
A custom ingestion endpoint to stream log lines into.
- Required
- Type: string
- Default:
''
- Max Length:
32000
The log line to be sent to LogDNA.
- Optional
- Type: string
- Default:
Info
- Values:
Debug
,Trace
,Info
,Warn
,Error
,Fatal
,YourCustomLevel
- Max Length:
32
The level passed along with this log line.
- Optional
- Type: string
- Default:
''
- Values:
YourCustomApp
- Max Length:
32
The app passed along with this log line.
- Optional
- Type: string
- Default:
''
- Values:
YourCustomEnv
- Max Length:
32
The environment passed with this log line.
- Optional
- Type: dict
- Default:
None
A standard dictonary containing additional metadata about the log line that is passed. Please ensure values are JSON serializable.
NOTE: Values that are not JSON serializable will be removed and the respective keys will be added to the __errors
string.
- 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!
- 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.
This project makes use of the poetry package manager for local development.
$ poetry install
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
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!
MIT © LogDNA Copyright © 2017 LogDNA, released under an MIT license. See the LICENSE file and https://opensource.org/licenses/MIT
Happy Logging!