Logz.io Python Handler

Warnings

• breaking Version 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.
• gotcha The 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`.
• gotcha Providing 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.
• gotcha Historically, 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.

Install

• pip install logzio-python-handler Core handler
• pip install 'logzio-python-handler[opentelemetry-logging]' With OpenTelemetry trace context support

Imports

• 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.

Quickstart

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