Registry / observability / logtail-python

logtail-python

library0.4.0pypypi✓ verified 21d ago

Logtail-python is the official Python client library for Logtail.com (part of Better Stack). It provides a `logging.Handler` to easily send logs from your Python applications, including Django and FastAPI, to Logtail for centralized log management, aggregation, and analysis. It is actively maintained with frequent updates, currently at version 0.3.4.

observability communication

pip install logtail-python

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · LOGTAIL-PYTHON

logtail-python

observabilitypythonv0.4.0

Install

2.3s avg

Import

368ms

Disk

20MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.4.0 · 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.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.374s · 22.2MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.3s · import 0.362s · 23MB

20MB installed

● package 20MB

Code

Verified usage

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

LogtailHandler

✓ from logtail import LogtailHandler

This quickstart sets up a basic Python logger with `LogtailHandler` to send logs to Logtail. It demonstrates logging INFO, WARNING, and an exception with extra structured data. Remember to replace `YOUR_LOGTAIL_SOURCE_TOKEN` with your actual token or set `LOGTAIL_SOURCE_TOKEN` as an environment variable, and verify your `INGESTING_HOST` if not using the default.

import logging import os from logtail import LogtailHandler # Ensure SOURCE_TOKEN is set in your environment variables # or replace with your actual source token for testing. SOURCE_TOKEN = os.environ.get('LOGTAIL_SOURCE_TOKEN', 'YOUR_LOGTAIL_SOURCE_TOKEN') INGESTING_HOST = os.environ.get('LOGTAIL_INGESTING_HOST', 'in.logtail.com') # Default host, may vary by region/setup handler = LogtailHandler( source_token=SOURCE_TOKEN, host=INGESTING_HOST ) logger = logging.getLogger(__name__) logger.setLevel(logging.INFO) # Clear existing handlers to prevent duplicate logs if running multiple times # or if root logger already has handlers. Optional, but good practice. logger.handlers = [] logger.addHandler(handler) logger.info('Hello from Logtail-python!', extra={'service': 'my-app', 'environment': 'development'}) logger.warning('This is a warning message.', extra={'user_id': 123}) try: 1 / 0 except ZeroDivisionError: logger.exception('An error occurred during division.') print("Logs sent to Logtail (check your Logtail Live tail). If nothing appears, ensure your SOURCE_TOKEN and INGESTING_HOST are correct.")

Debug

Known issues

gotchaStarting from v0.3.3, the `host` parameter for `LogtailHandler` should *not* include the protocol (e.g., `https://`). If you were previously passing `https://in.logtail.com`, you should now pass `in.logtail.com` to avoid potential issues or misconfigurations.

fix

Remove the protocol (e.g., `https://`) from the `host` parameter when initializing `LogtailHandler`.

affects: >=0.3.3

gotchaWhen shutting down your application, using `os._exit()` will terminate all threads immediately, which can result in unsent logs. For graceful termination and to ensure all buffered logs are sent to Logtail, use `sys.exit()` instead.

fix

Always use `sys.exit()` for application termination to allow the logging handler's background flusher to send all pending logs.

affects: All

gotchaAvoid configuring logging directly on the root logger (`logging.getLogger()`) in production applications. It can lead to less control and unexpected log destinations. Instead, get a named logger (`logging.getLogger(__name__)`) and add your `LogtailHandler` to it.

fix

Use `logger = logging.getLogger(__name__)` and explicitly add `logger.addHandler(handler)` to gain fine-grained control over your logging configuration.

affects: All

gotchaWhile the library attempts to handle circular references in log records (improved in v0.2.10, v0.3.1, v0.3.2), passing extremely complex or deeply nested objects in `extra` data might still lead to serialization issues or performance overhead. Ensure that extra data is generally JSON-serializable.

fix

Sanitize or simplify complex objects passed in the `extra` dictionary to ensure they are easily serializable.

affects: All (mitigated in >=0.2.10)

Errors

Common errors & fixes

ImportError: cannot import name 'LogtailHandler' from 'logtail'

The `logtail-python` package is either not installed, or the `LogtailHandler` is being imported from the wrong module or an incorrect alias.

fix

Ensure the `logtail-python` package is installed (`pip install logtail-python`) and import `LogtailHandler` directly from the `logtail` module: `from logtail import LogtailHandler`.

API Key not set

The `source_token` required for authenticating with the Logtail service has not been provided or is incorrect when initializing the `LogtailHandler`.

fix

Pass your Logtail source token as the `source_token` argument when initializing `LogtailHandler`: `handler = LogtailHandler(source_token='YOUR_SOURCE_TOKEN')` or ensure it's set as an environment variable that the handler can pick up if configured to do so.

AttributeError: 'Logger' object has no attribute 'LogtailHandler'

This error typically occurs when trying to access `LogtailHandler` directly as an attribute of a `logging.Logger` object, instead of instantiating `LogtailHandler` and then adding it to the logger.

fix

First, import and instantiate `LogtailHandler`, then add the handler instance to your logger: `from logtail import LogtailHandler
import logging
handler = LogtailHandler(source_token='YOUR_SOURCE_TOKEN')
logger = logging.getLogger(__name__)
logger.addHandler(handler)`.

ConnectionRefusedError: [Errno 111] Connection refused

The Python application is unable to establish a connection with the Logtail ingestion server, possibly due to network issues, an incorrect `host` configuration in `LogtailHandler`, or firewall restrictions.

fix

Verify that your `host` parameter in `LogtailHandler` is correct (e.g., `https://in.logtail.com`), check your network connectivity, and ensure no firewalls are blocking outbound connections to the Logtail ingestion endpoint. If deploying to a platform, check its network policies.

Missing logs from the end of your application run

This is not a traceback, but a common behavioral problem where logs are not sent before the application terminates, especially if it exits abruptly without allowing the `LogtailHandler` to flush its buffer.

fix

Ensure your application terminates gracefully. Use `sys.exit()` instead of `os._exit()` to allow background threads, including the Logtail flusher, to complete their tasks before the program exits.

Upgrade

Version history

0.4.0latest on PyPI · released Jul 1, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

18 hits · last 30 days

node

OpenAI (training)

Amazon

Resources

githubhttps://github.com/logtail/logtail-python ↗

packagehttps://pypi.org/project/logtail-python/ ↗

homepagehttps://logs.betterstack.com ↗