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
orBoolean
- 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)
Updated 11 months ago