Registry / observability / logzio-python-handler

logzio-python-handler

JSON →
library4.1.9pypypi✓ verified 22d ago

The `logzio-python-handler` library provides a Python logging handler that sends application logs to a Logz.io account. It supports bulk sending over HTTPS with SSL, handling logs asynchronously in a background thread, and offers optional OpenTelemetry trace context integration. As of version `4.1.9`, the library is actively maintained with frequent updates, primarily focusing on dependency management and robustness improvements.

pip install logzio-python-handler
INSTALL
IMPORT
SIG · LOGZIO-PYTHON-HAND
L
logzio-python-handler
observabilitypythonv4.1.9
Install
3.1s avg
Import
350ms
Disk
27MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v4.1.9 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.910 runs
installs and imports cleanly · install 0.0s · import 0.359s · 27.7MB
glibc
py 3.103.910 runs
installs and imports cleanly · install 3.1s · import 0.340s · 29MB
27MB installed
● package 27MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

LogzioHandler
from logzio.handler import LogzioHandler
ExtraFieldsLogFilter
from logzio.handler import ExtraFieldsLogFilter
For dynamically adding extra fields to logs.
LogzioFlusher
from logzio.flusher import LogzioFlusher
Primarily for serverless environments to ensure logs are flushed.

This quickstart demonstrates how to configure the `LogzioHandler` with Python's standard `logging` module. It uses environment variables for the Logz.io token and log type, falling back to a console logger if the token isn't set. It shows how to log informational, warning, and exception messages.

import logging import os from logzio.handler import LogzioHandler # Replace with your Logz.io token and log type LOGZIO_TOKEN = os.environ.get('LOGZIO_TOKEN', 'YOUR_LOGZIO_TOKEN') LOGZIO_TYPE = os.environ.get('LOGZIO_TYPE', 'python-application') if LOGZIO_TOKEN == 'YOUR_LOGZIO_TOKEN': print("WARNING: Please set the LOGZIO_TOKEN environment variable or replace 'YOUR_LOGZIO_TOKEN' in the script.") print("Skipping Logz.io handler configuration for quickstart.") # Fallback to console logging if token is not set logging.basicConfig(level=logging.INFO) logger = logging.getLogger(__name__) else: logger = logging.getLogger(__name__) logger.setLevel(logging.INFO) try: handler = LogzioHandler( LOGZIO_TOKEN, logzio_type=LOGZIO_TYPE # url="https://listener.logz.io:8071" # Default, uncomment to specify a different listener URL # debug=True # Uncomment for debug output to stdout ) logger.addHandler(handler) print(f"Logz.io handler configured for type: {LOGZIO_TYPE}") except Exception as e: print(f"Error configuring Logz.io handler: {e}") print("Falling back to console logging.") logging.basicConfig(level=logging.INFO) logger = logging.getLogger(__name__) logger.info("This is an informational message sent via Logz.io handler.") logger.warning("This is a warning message.") try: 1 / 0 except ZeroDivisionError: logger.exception("An error occurred during division. Full stack trace will be sent.") # In a real application, the handler manages a background thread for sending logs. # For simple scripts, a short delay might be needed to ensure logs are sent # before the script exits, though graceful shutdown attempts to drain remaining logs. import time time.sleep(1) # Give the handler a moment to flush logs for short scripts
Debug
Known issues
breakingVersion 3.0.0 of `logzio-python-handler` (released before current 4.x series) dropped support for Python 2.7, 3.3, and 3.4. Users on these older Python versions must upgrade to Python 3.5 or newer to use versions 3.0.0 or later.
fix
Upgrade your Python environment to version 3.5 or newer.
affects: >=3.0.0
gotchaThe handler uses a background thread to send logs asynchronously. While version 4.1.7 included fixes to prevent the main thread from blocking, applications may still experience a short delay during shutdown as the handler attempts a final log drain. Ensure your application's graceful termination allows sufficient time for this.
fix
Implement proper shutdown hooks or a small delay in short-lived scripts if logs appear to be missing. For serverless environments, consider using `LogzioFlusher`.
affects: <4.1.7 (more prominent blocking); All versions (shutdown delay)
gotchaProviding an invalid Logz.io token or listener URL will prevent logs from being sent. Older versions might enter an endless loop attempting to send, while newer versions will drop unauthorized logs. This can silently cause data loss.
fix
Always verify your Logz.io token and listener URL are correct. Check Logz.io documentation for regional listener addresses.
affects: All versions
gotchaHistorically, very large exception logs might have their `logzio_type` overwritten to `logzio-invalid-log` if they exceeded indexing limits, making them harder to query. While the system now truncates them to fit, be aware of potential truncation or unexpected type changes for extremely verbose exceptions.
fix
Monitor log sizes for exceptions. If critical information is being truncated, consider structuring your exception logging to send key details in separate, smaller fields or custom parsing rules in Logz.io.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'logzio'
The `logzio-python-handler` package has not been installed in the Python environment where the code is being executed.
fix
pip install logzio-python-handler
HTTPSConnectionPool(host='listener.logz.io', port=8071): Max retries exceeded with url: /?token=... (Caused by NewConnectionError(...))
This error indicates a network connectivity issue from your host/server to the Logz.io listener, or a firewall/proxy blocking the connection.
fix
Verify network connectivity from your host to `listener.logz.io` on the configured port (e.g., 8071 for HTTPS). Check local firewall rules, proxy settings, or corporate network restrictions. Also, ensure the listener URL in your handler configuration is correct.
You are not authorized with Logz.io! Token OK? dropping logs...
The Logz.io shipping token configured in your `LogzioHandler` is incorrect, expired, or does not have the necessary permissions, leading to an authentication failure with the Logz.io API.
fix
Verify that the Logz.io shipping token used in your `LogzioHandler` instantiation is correct and active in your Logz.io account. Double-check for typos or accidental truncation of the token.
Logs not appearing in Logz.io when using logging.config.dictConfig with LogzioHandler
When configuring `LogzioHandler` using `logging.config.dictConfig`, the parameters for the handler (like token, log_type, timeout, url, etc.) must be provided in a specific, exact order. Incorrect ordering can lead to misconfiguration and logs not being sent.
fix
Ensure that the `args` tuple for the `LogzioHandler` in your `dictConfig` lists the parameters in the precise order specified by the `logzio-python-handler` documentation: `('token', 'log_type', 'logs_drain_timeout', 'url', 'debug', 'networking_timeout', 'retries_no', 'retries_interval')`. All preceding optional parameters must be included if a later one is set.
Upgrade
Version history
4.1.9latest on PyPI · released Feb 1, 2026
Audit
Dependencies
requestsrequiredHTTP client for sending logs. Regularly updated for security and stability.
protobufrequiredUsed internally by the library. Regularly updated for security and stability.
setuptoolsrequiredBuild-time dependency, regularly updated.
wheelrequiredBuild-time dependency, regularly updated.
opentelemetry-instrumentation-loggingoptionalRequired for OpenTelemetry trace context integration.
Agent activity
15 hits · last 30 days
node
10
OpenAI (training)
4
Resources
logzio-python-handler — pip install logzio-python-handler · libregistry