-
Notifications
You must be signed in to change notification settings - Fork 2
/
README.md.j2
144 lines (98 loc) · 5.32 KB
/
README.md.j2
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
# stlog
[](https://github.com/fabien-marty/stlog/actions/workflows/lint.yaml)
[](https://app.codecov.io/github/fabien-marty/stlog)
[](https://pypi.org/project/stlog/)
[Full documentation](https://fabien-marty.github.io/stlog/)
<!--intro-start-->
## What is it?
**ST**andard **ST**ructured **LOG** (`stlog`) is Python 3.7+ [structured logging](#structured) library:
- built on {{pythonlogging}} and {{contextvars}}
- very easy to configure with "good/opinionated" default values
- which produces great output **for both humans and machines**
- which believes in {{twelvefactorapp}} principles about config and logs
- **dependency free** (but can use fancy stuff (colors, augmented traceback...) from {{rich}} *(if installed)*)
## Features
- **standard, standard, standard**: all stlog objects are built on {{pythonlogging}} and are compatible with:
- other existing handlers, formatters...
- libraries which are using a standard logger *(and `stlog` can automatically reinject the global context in log records produced by these libraries)*
- easy shorcuts to configure your logging
- provides nice outputs **for humans AND for machines** *(you can produce both at the same time)*
- structured with 4 levels of context you can choose or combine:
- a global one set by environment variables *(read at process start)*
- a kind of global one (thanks to {{contextvars}})
- a context linked to the logger object itself (defined during its building)
- a context linked to the log message itself
- a lot of configuration you can do with environment variables (in the spirit of {{twelvefactorapp}} principles)
## Non-Features
- *"A twelve-factor app never concerns itself with routing or storage of its output stream."*
- we are going to make an exception on this for log files *(see roadmap)*
- but we don't want to introduce complex/network outputs like syslog, elasticsearch, loki...
- standard, standard, standard: we do not want to move away from {{pythonlogging}} compatibility
## <a name="structured"></a> What is *structured logging*?
> Structured logging is a technique used in software development to produce log messages that are more easily parsed and analyzed by machines.
> Unlike traditional logging, which typically consists of free-form text messages, structured logging uses a well-defined format that includes
> named fields with specific data types.
>
> The benefits of structured logging are many. By using a standard format, it becomes easier to automate the processing and analysis of logs.
> This can help with tasks like troubleshooting issues, identifying patterns, and monitoring system performance. It can also make it easier
> to integrate logs with other systems, such as monitoring and alerting tools.
>
> Some common formats for structured logging include JSON, XML, and key-value pairs. In each case, the format includes a set of fields that provide information about the log message, such as the severity level, timestamp, source of the message, and any relevant metadata.
>
> Structured logging is becoming increasingly popular as more developers recognize its benefits. Many logging frameworks and libraries now include support for structured logging, making it easier for developers to adopt the technique in their own projects.
>
> (thanks to ChatGPT)
<!--intro-end-->
## Quickstart
<!--quickstart-start-->
### Installation
```
pip install stlog
```
### Very minimal usage
```python
{{ "cat docs/python/qs0.py" |shell(die_on_error=True) }}
```
Output (without `rich` library installed):
```
{{ "STLOG_USE_RICH=0 ; python docs/python/qs0.py" |shell(die_on_error=True) }}
```
Output (with `rich` library installed):
{{ ("python ./docs/python/termtosvg.py --pathprefix '" + pathprefix + "' qs0.py") |shell(die_on_error=True) }}
### Basic usage
```python
{{ "cat docs/python/qs1.py" |shell(die_on_error=True) }}
```
Output (without `rich` library installed):
```
{{ "STLOG_USE_RICH=0 ; python docs/python/qs1.py" |shell(die_on_error=True) }}
```
Output (with `rich` library installed):
{{ ("python ./docs/python/termtosvg.py --pathprefix '" + pathprefix + "' qs1.py") |shell(die_on_error=True) }}
### Usage with context
```python
{{ "cat docs/python/qs2.py" |shell(die_on_error=True) }}
```
Output (without `rich` library installed):
```
{{ "STLOG_USE_RICH=0 ; python docs/python/qs2.py" |shell(die_on_error=True) }}
```
Output (with `rich` library installed):
{{ ("python ./docs/python/termtosvg.py --pathprefix '" + pathprefix + "' qs2.py ") |shell(die_on_error=True) }}
What about if you want to get a more parsing friendly output (for example in JSON on `stdout`) while keeping the human output on `stderr` (without any context)?
```python
{{ "cat docs/python/qs3.py" |shell(die_on_error=True) }}
```
Human output (on `stderr`):
```
{{ "python docs/python/qs3.py >/dev/null" |shell(die_on_error=True) }}
```
JSON ouput (on `stdout`) for machines:
```json
{{ "python docs/python/qs3.py 2>/dev/null" |shell(die_on_error=True) }}
```
<!--quickstart-end-->
## Roadmap
- [ ] add `file` outputs
- [x] add a full `logfmt` formatter
- [ ] more configuration options through env vars