Splunk Logging Handler

3.0.0 · active · verified Sun Apr 12

The `splunk-handler` library provides a Python logging handler for sending log events to a Splunk Enterprise instance. It leverages the Splunk HTTP Event Collector (HEC) for data ingestion. The current version is 3.0.0, and the project maintains an active release cadence, addressing bug fixes, new features, and Python compatibility updates.

Warnings

breaking Version 3.0.0 removed official support for Python 2.7, 3.4, and 3.5. Applications running on these Python versions must either stay on an older `splunk-handler` version (e.g., <3.0.0) or upgrade their Python runtime.
Fix: Upgrade Python to 3.6+ or pin `splunk-handler` version to <3.0.0.
gotcha In serverless environments like AWS Lambda, where the main thread can terminate unexpectedly, logs might be dropped. To prevent this, explicitly call `splunk_handler.force_flush()` as the last action in your Lambda handler to ensure all queued logs are sent.
Fix: Call `from splunk_handler import force_flush` and `force_flush()` at the end of your main application or function execution.
gotcha The `SplunkHandler` requires a Splunk Enterprise server with the HTTP Event Collector (HEC) enabled and configured. Misconfiguration of HEC (e.g., incorrect token, port, or protocol) will result in logs not being ingested by Splunk.
Fix: Verify HEC configuration in Splunk, including token, port, and allowed indexes. Ensure network connectivity between the application and the Splunk HEC endpoint.
gotcha If your Splunk instance uses a self-signed SSL certificate, `verify=True` (the default) will cause connection errors. You may need to set `verify=False` or, preferably, provide the certificate authority (CA) bundle to `requests` for proper SSL verification.
Fix: Set `verify=False` (less secure) or configure `requests` to trust your custom CA certificate by passing `verify='/path/to/your/ca-bundle.pem'` to the handler.
gotcha While race conditions for large payloads were fixed in v2.2.2, general asynchronous logging can still lead to lost events if the application exits abruptly without proper shutdown. Ensure the `flush_interval` is appropriate for your traffic and application lifecycle.
Fix: Ensure graceful shutdown of your application, allowing the handler to flush its queue. Consider using `splunk_handler.wait_until_empty()` or `splunk_handler.force_flush()` at application exit points for critical logs.

Install

pip install splunk-handler Install latest version

Imports

SplunkHandler

from splunk_handler import SplunkHandler

force_flush
```
from splunk_handler import force_flush
```
Specifically needed for environments like AWS Lambda to ensure logs are flushed before process termination.

Quickstart

This quickstart demonstrates how to configure and use `splunk-handler` to send log messages to Splunk Enterprise via the HTTP Event Collector. It uses environment variables for sensitive connection details and includes an example of `force_flush` for critical environments like AWS Lambda. Ensure your Splunk HEC is properly configured and accessible from where this code runs.

import logging
import os
from splunk_handler import SplunkHandler, force_flush

# Configure Splunk HEC details via environment variables
SPLUNK_HOST = os.environ.get('SPLUNK_HOST', 'splunk.example.com')
SPLUNK_PORT = os.environ.get('SPLUNK_PORT', '8088')
SPLUNK_TOKEN = os.environ.get('SPLUNK_TOKEN', 'YOUR_SPLUNK_HEC_TOKEN')
SPLUNK_INDEX = os.environ.get('SPLUNK_INDEX', 'main')

# Initialize the SplunkHandler
try:
    splunk_handler = SplunkHandler(
        host=SPLUNK_HOST,
        port=SPLUNK_PORT,
        token=SPLUNK_TOKEN,
        index=SPLUNK_INDEX,
        protocol='https', # Use 'http' if SSL is not configured
        verify=True,      # Set to False if using self-signed certs and not providing CA
        flush_interval=1.0 # Send logs every 1 second for demonstration
    )
    # Add the handler to the root logger
    logging.getLogger('').addHandler(splunk_handler)
    logging.getLogger('').setLevel(logging.INFO)

    # Example log messages
    logging.info('Hello from splunk-handler!')
    logging.warning('This is a warning message.')
    logging.error('An error occurred: %s', 'something went wrong')

    # For environments like AWS Lambda, ensure logs are flushed before exiting.
    # In a typical application, the atexit hook handles this, but explicit call might be needed.
    force_flush()
    print('Logs sent to Splunk (check your Splunk instance).')

except Exception as e:
    print(f"Failed to configure Splunk handler or send logs: {e}")
    print("Please ensure SPLUNK_HOST, SPLUNK_PORT, SPLUNK_TOKEN, and SPLUNK_INDEX are correctly set.")
    print("Also, verify that Splunk HEC is enabled and accessible.")

view raw JSON →