graypy

library2.1.0pypypi✓ verified 84d ago

graypy is a Python library that provides logging handlers for sending messages in the Graylog Extended Log Format (GELF). It integrates with Python's standard `logging` module and supports various transport protocols including UDP, TCP, TLS, HTTP, and RabbitMQ. The current version is 2.1.0, and while there isn't a strict release cadence, major versions have introduced breaking changes.

observability http-networking

pip install graypy

github ↗package ↗

INSTALL

IMPORT

SIG · GRAYPY

graypy

observabilitypythonv2.1.0

Install

1.5s avg

Import

90ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.1.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.920 runs

installs and imports cleanly · install 0.0s · import 0.095s · 18MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.5s · import 0.084s · 19MB

16MB installed

● package 16MB

Code

Verified usage

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

GELFUDPHandler

✓ from graypy import GELFUDPHandler

GELFTCPHandler

✓ from graypy import GELFTCPHandler

GELFTLSHandler

✓ from graypy import GELFTLSHandler

GELFHTTPHandler

✓ from graypy import GELFHTTPHandler

GELFRabbitHandler

✓ from graypy import GELFRabbitHandler

GELFHandler

✓ from graypy import GELFUDPHandler

✗ from graypy import GELFHandler

`GELFHandler` was deprecated and removed in graypy 1.x.x; use `GELFUDPHandler` instead.

GELFTcpHandler

✓ from graypy import GELFTCPHandler

✗ from graypy import GELFTcpHandler

`GELFTcpHandler` was deprecated and restructured into `GELFTCPHandler` and `GELFTLSHandler` in graypy 1.x.x.

This quickstart demonstrates how to configure a basic UDP logging handler (`GELFUDPHandler`) to send messages to a Graylog server. It uses environment variables for the Graylog host and port, which is a common practice for configuration management. Ensure your Graylog server has a GELF UDP input configured on the specified port.

import logging import graypy import os # Configure Graylog host and port, using environment variables for security GRAYLOG_HOST = os.environ.get('GRAYLOG_HOST', 'localhost') GRAYLOG_PORT = int(os.environ.get('GRAYLOG_PORT', 12201)) # Get a logger instance my_logger = logging.getLogger('my_app_logger') my_logger.setLevel(logging.DEBUG) # Create a GELF UDP handler handler = graypy.GELFUDPHandler(GRAYLOG_HOST, GRAYLOG_PORT) my_logger.addHandler(handler) # Send a log message my_logger.debug('Hello Graylog from graypy!') my_logger.info('This is an informational message.') my_logger.warning('Something might be wrong here.') try: 1 / 0 except ZeroDivisionError: my_logger.exception('An error occurred!') print(f"Log messages sent to Graylog at {GRAYLOG_HOST}:{GRAYLOG_PORT} (UDP).")

Debug

Known issues

breakingThe `GELFHandler` and `GELFTcpHandler` classes were removed in `graypy` version 1.x.x. Users migrating from 0.x.x to 1.x.x or newer must update their code to use `GELFUDPHandler`, `GELFTCPHandler`, or `GELFTLSHandler` respectively.

fix

Replace `GELFHandler` with `GELFUDPHandler` and `GELFTcpHandler` with `GELFTCPHandler` or `GELFTLSHandler` based on your protocol requirements.

affects: >=1.0.0

gotcha`GELFUDPHandler` sends logs via UDP, which is a connectionless protocol and does not guarantee message delivery. Critical logs that must not be lost should be sent via `GELFTCPHandler`, `GELFTLSHandler`, `GELFHTTPHandler`, or `GELFRabbitHandler` for more reliable transport.

fix

For high-priority or critical logs, consider using `GELFTCPHandler`, `GELFTLSHandler`, or `GELFRabbitHandler` and configure a corresponding input on your Graylog server.

affects: All

gotchaWhen using `GELFRabbitHandler`, you must manually configure RabbitMQ with a GELF-compatible queue and bind it to a logging exchange. Graylog then consumes messages from this AMQP queue.

fix

Refer to `graypy` documentation and RabbitMQ configuration guides for proper setup of queues and exchanges for AMQP-based GELF logging.

affects: All

gotchaThere is no formal changelog maintained for `graypy` on GitHub, which can make it challenging to track specific changes, new features, or breaking alterations between versions.

fix

Monitor the GitHub repository issues and commits for updates, or pin `graypy` to a specific version to avoid unexpected changes.

affects: All

gotchaWhen deploying `graypy` in containerized environments (e.g., with Docker or Kubernetes, especially with Django applications), ensure that the application container and the Graylog container are on the same network and configured with correct hostnames or IP addresses for communication.

fix

Verify container networking configurations, ensuring proper hostname resolution or direct IP addressing between your application and Graylog instances.

affects: All

Errors

Common errors & fixes

AttributeError: module 'graypy' has no attribute 'GELFRabbitHandler'

This error occurs when attempting to use `GELFRabbitHandler` without the necessary AMQP dependencies installed, or if the `graypy` version does not correctly expose this handler.

fix

Install `graypy` with the AMQP extra: `pip install graypy[amqp]`

AttributeError: module 'graypy' has no attribute 'GELFHandler'

The `GELFHandler` class was deprecated in newer versions of `graypy` and replaced with more specific handlers like `GELFUDPHandler`, `GELFTCPHandler`, etc.

fix

Replace `GELFHandler` with the appropriate specific handler, such as `graypy.GELFUDPHandler` or `graypy.GELFTCPHandler`, depending on your Graylog input configuration.

GELFChunkOverflowWarning

This warning indicates that a GELF message exceeded the configured chunk size (especially common with UDP), leading to potential message truncation or dropping if not handled.

fix

Increase the `chunk_size` parameter in your `graypy` handler's constructor, or configure a different chunking strategy (e.g., `GELFTruncatingChunker` for `GELFUDPHandler`) to allow for larger messages or truncation instead of dropping.

Upgrade

Version history

2.1.0latest on PyPI · released Sep 30, 2019

Audit

Dependencies

No dependency data recorded yet.

Agent activity

24 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/severb/graypy ↗

packagehttps://pypi.org/project/graypy/ ↗