{"id":4772,"library":"splunk-handler","title":"Splunk Logging Handler","description":"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.","status":"active","version":"3.0.0","language":"en","source_language":"en","source_url":"https://github.com/zach-taylor/splunk_handler","tags":["logging","splunk","log-handler","observability"],"install":[{"cmd":"pip install splunk-handler","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Used for making HTTP requests to the Splunk HTTP Event Collector.","package":"requests","optional":false}],"imports":[{"symbol":"SplunkHandler","correct":"from splunk_handler import SplunkHandler"},{"note":"Specifically needed for environments like AWS Lambda to ensure logs are flushed before process termination.","symbol":"force_flush","correct":"from splunk_handler import force_flush"}],"quickstart":{"code":"import logging\nimport os\nfrom splunk_handler import SplunkHandler, force_flush\n\n# Configure Splunk HEC details via environment variables\nSPLUNK_HOST = os.environ.get('SPLUNK_HOST', 'splunk.example.com')\nSPLUNK_PORT = os.environ.get('SPLUNK_PORT', '8088')\nSPLUNK_TOKEN = os.environ.get('SPLUNK_TOKEN', 'YOUR_SPLUNK_HEC_TOKEN')\nSPLUNK_INDEX = os.environ.get('SPLUNK_INDEX', 'main')\n\n# Initialize the SplunkHandler\ntry:\n    splunk_handler = SplunkHandler(\n        host=SPLUNK_HOST,\n        port=SPLUNK_PORT,\n        token=SPLUNK_TOKEN,\n        index=SPLUNK_INDEX,\n        protocol='https', # Use 'http' if SSL is not configured\n        verify=True,      # Set to False if using self-signed certs and not providing CA\n        flush_interval=1.0 # Send logs every 1 second for demonstration\n    )\n    # Add the handler to the root logger\n    logging.getLogger('').addHandler(splunk_handler)\n    logging.getLogger('').setLevel(logging.INFO)\n\n    # Example log messages\n    logging.info('Hello from splunk-handler!')\n    logging.warning('This is a warning message.')\n    logging.error('An error occurred: %s', 'something went wrong')\n\n    # For environments like AWS Lambda, ensure logs are flushed before exiting.\n    # In a typical application, the atexit hook handles this, but explicit call might be needed.\n    force_flush()\n    print('Logs sent to Splunk (check your Splunk instance).')\n\nexcept Exception as e:\n    print(f\"Failed to configure Splunk handler or send logs: {e}\")\n    print(\"Please ensure SPLUNK_HOST, SPLUNK_PORT, SPLUNK_TOKEN, and SPLUNK_INDEX are correctly set.\")\n    print(\"Also, verify that Splunk HEC is enabled and accessible.\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade Python to 3.6+ or pin `splunk-handler` version to <3.0.0.","message":"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.","severity":"breaking","affected_versions":"<3.0.0 to 3.0.0"},{"fix":"Call `from splunk_handler import force_flush` and `force_flush()` at the end of your main application or function execution.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Verify HEC configuration in Splunk, including token, port, and allowed indexes. Ensure network connectivity between the application and the Splunk HEC endpoint.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}