0
# Fluent Logger
1

2
A Python structured logger for Fluentd/Fluent Bit event collectors that enables structured event logging from Python applications to centralized log processing systems. It provides multiple interfaces including direct FluentSender for programmatic event emission, standard Python logging handler integration, and asynchronous communication options to prevent blocking during log transmission.
3

4
## Package Information
5

6
- **Package Name**: fluent-logger
7
- **Version**: 0.11.1
8
- **Language**: Python
9
- **Installation**: `pip install fluent-logger`
10

11
## Core Imports
12

13
**Note**: The package has an empty `__init__.py`, so all functionality must be imported from specific modules:
14

15
```python
16
from fluent import sender
17
```
18

19
For event-based interface:
20

21
```python
22
from fluent import event
23
```
24

25
For Python logging integration:
26

27
```python
28
from fluent import handler
29
```
30

31
For asynchronous versions:
32

33
```python
34
from fluent import asyncsender
35
from fluent import asynchandler
36
```
37

38
For version information:
39

40
```python
41
from fluent.__about__ import __version__
42
```
43

44
## Basic Usage
45

46
```python
47
from fluent import sender
48

49
# Create a FluentSender for local Fluentd
50
logger = sender.FluentSender('app')
51

52
# Send an event with current timestamp
53
logger.emit('follow', {'from': 'userA', 'to': 'userB'})
54

55
# Send event with specific timestamp
56
import time
57
cur_time = int(time.time())
58
logger.emit_with_time('follow', cur_time, {'from': 'userA', 'to': 'userB'})
59

60
# Check for errors
61
if not logger.emit('follow', {'from': 'userA', 'to': 'userB'}):
62
    print(logger.last_error)
63
    logger.clear_last_error()
64

65
# Clean up
66
logger.close()
67
```
68

69
## Architecture
70

71
The fluent-logger package is built around several key components:
72

73
- **FluentSender**: Core synchronous sender that manages TCP/Unix socket connections to Fluentd
74
- **AsyncFluentSender**: Asynchronous version using background threads and queues for non-blocking operation
75
- **Event-based API**: Simplified wrapper interface using global sender instances
76
- **Logging Integration**: Full Python logging.Handler compatibility with structured formatting
77
- **Buffer Management**: Automatic buffering, reconnection, and overflow handling for reliability
78

79
## Capabilities
80

81
### Core Sender Interface
82

83
Direct FluentSender interface for programmatic event emission with full control over connection parameters, error handling, and message formatting.
84

85
```python { .api }
86
class FluentSender:
87
    def __init__(
88
        self,
89
        tag: str,
90
        host: str = "localhost",
91
        port: int = 24224,
92
        bufmax: int = 1048576,
93
        timeout: float = 3.0,
94
        verbose: bool = False,
95
        buffer_overflow_handler = None,
96
        nanosecond_precision: bool = False,
97
        msgpack_kwargs = None,
98
        *,
99
        forward_packet_error: bool = True,
100
        **kwargs
101
    ): ...
102

103
    def emit(self, label: str, data: dict) -> bool: ...
104
    def emit_with_time(self, label: str, timestamp, data: dict) -> bool: ...
105
    def close(self) -> None: ...
106
    
107
    def __enter__(self): ...
108
    def __exit__(self, typ, value, traceback): ...
109
```
110

111
[Core Sender](./core-sender.md)
112

113
### Event-Based Interface
114

115
Simplified API wrapper using global sender instances for quick integration and reduced boilerplate code.
116

117
```python { .api }
118
# Global functions
119
def setup(tag: str, **kwargs) -> None: ...
120
def get_global_sender(): ...
121
def close() -> None: ...
122

123
# Event class
124
class Event:
125
    def __init__(self, label: str, data: dict, **kwargs): ...
126
```
127

128
[Event Interface](./event-interface.md)
129

130
### Python Logging Integration
131

132
Full logging.Handler compatibility with structured formatting, custom formatters, and seamless integration with existing Python logging workflows.
133

134
```python { .api }
135
class FluentHandler(logging.Handler):
136
    def __init__(
137
        self,
138
        tag: str,
139
        host: str = "localhost",
140
        port: int = 24224,
141
        timeout: float = 3.0,
142
        verbose: bool = False,
143
        buffer_overflow_handler = None,
144
        msgpack_kwargs = None,
145
        nanosecond_precision: bool = False,
146
        **kwargs
147
    ): ...
148
    
149
    def __enter__(self): ...
150
    def __exit__(self, exc_type, exc_val, exc_tb): ...
151

152
class FluentRecordFormatter(logging.Formatter):
153
    def __init__(
154
        self,
155
        fmt = None,
156
        datefmt = None,
157
        style: str = "%",
158
        fill_missing_fmt_key: bool = False,
159
        format_json: bool = True,
160
        exclude_attrs = None
161
    ): ...
162
```
163

164
[Logging Integration](./logging-integration.md)
165

166
### Asynchronous Communication
167

168
Non-blocking asynchronous versions of both the core sender and logging handler interfaces, using background threads and queues to prevent application blocking during log transmission.
169

170
```python { .api }
171
class FluentSender(fluent.sender.FluentSender):
172
    def __init__(
173
        self,
174
        tag: str,
175
        host: str = "localhost",
176
        port: int = 24224,
177
        bufmax: int = 1048576,
178
        timeout: float = 3.0,
179
        verbose: bool = False,
180
        buffer_overflow_handler = None,
181
        nanosecond_precision: bool = False,
182
        msgpack_kwargs = None,
183
        queue_maxsize: int = 100,
184
        queue_circular: bool = False,
185
        queue_overflow_handler = None,
186
        **kwargs
187
    ): ...
188

189
    def close(self, flush: bool = True) -> None: ...
190
    
191
    @property
192
    def queue_maxsize(self) -> int: ...
193
    
194
    @property
195
    def queue_blocking(self) -> bool: ...
196
    
197
    @property
198
    def queue_circular(self) -> bool: ...
199
```
200

201
[Async Communication](./async-communication.md)
202

203
## Types
204

205
```python { .api }
206
class EventTime:
207
    """msgpack ExtType for nanosecond-precision timestamps"""
208
    def __new__(cls, timestamp: float, nanoseconds: int = None): ...
209
    
210
    @classmethod
211
    def from_unix_nano(cls, unix_nano: int): ...
212
```
213

214
## Version Information
215

216
```python { .api }
217
# Access package version
218
from fluent.__about__ import __version__
219
# __version__ = "0.11.1"
220
```