1. Introduction

• HTTP
• UDP
• TCP

2. Behavior and Context

The sink maps standard log levels to GELF numeric severity and enriches structured fields using _-prefixed keys, per GELF conventions.

Transport behavior:

• HTTP: JSON POST to /gelf
• UDP: datagram send
• TCP: stream send with required null-byte terminator

3. Purpose

• Graylog Compatibility: Native GELF-formatted events.
• Transport Choice: Select protocol based on reliability/performance needs.
• Structured Metadata: Preserve context via GELF additional fields.

4. High-Level API & Examples

Example 1: HTTP GELF

from jazzmine.logging.sinks.gelf_sink import GraylogLogger

sink = GraylogLogger(
    sink_config={
        "type": "graylog",
        "host": "graylog.internal",
        "port": 12201,
        "protocol": "http",
    },
    logger_name="gateway",
    level="INFO",
    use_json=True,
)

sink.initialize()
sink.error("auth failed", user_id="u_15", reason="invalid_token")

Example 2: UDP GELF

sink = GraylogLogger(
    sink_config={
        "type": "graylog",
        "host": "graylog.internal",
        "port": 12201,
        "protocol": "udp",
    },
    logger_name="worker",
    level="INFO",
    use_json=True,
)

5. Detailed Class Functionality

initialize()

• Reads host, port, protocol.
• For HTTP, sets URL endpoint.
• For UDP/TCP, creates socket and (for TCP) establishes connection.
• Marks sink initialized.

_format_gelf(level, msg, **kwargs)

Constructs GELF payload with:

• version
• host name
• short_message
• UNIX timestamp
• GELF numeric level mapping
• _logger and additional _key fields from kwargs

log(...)

• HTTP: requests.post JSON payload
• UDP: sendto bytes
• TCP: sendall bytes + null terminator

alog(...)

• HTTP: sends via shared aiohttp session
• UDP/TCP: delegates to sync log

shutdown()

• Closes socket for UDP/TCP modes.
• Closes async session if allocated.

6. Error Handling

• Network/serialization errors are swallowed.
• Invalid protocol values are not explicitly rejected; unsupported values lead to no transport path.

7. Remarks

• UDP is low-overhead but lossy; use TCP/HTTP when delivery reliability is more important.
• Ensure Graylog input is configured for selected protocol and port.