@@ -20,165 +20,9 @@ we will be following (ECS.major).(ECS.minor).(package minor) as our versioning s
20
20
$ python -m pip install ecs-logging
21
21
```
22
22
23
- ## Getting Started
23
+ ## Documentation
24
24
25
- ` ecs-logging-python ` has formatters for the standard library
26
- [ ` logging ` ] ( https://docs.python.org/3/library/logging.html ) module
27
- and the [ ` structlog ` ] ( https://www.structlog.org/en/stable/ ) package.
28
-
29
- ## Standard Library ` logging ` Module
30
-
31
- ``` python
32
- import logging
33
- import ecs_logging
34
-
35
- # Get the Logger
36
- logger = logging.getLogger(" app" )
37
- logger.setLevel(logging.DEBUG )
38
-
39
- # Add an ECS formatter to the Handler
40
- handler = logging.StreamHandler()
41
- handler.setFormatter(ecs_logging.StdlibFormatter())
42
- logger.addHandler(handler)
43
-
44
- # Emit a log!
45
- logger.debug(" Example message!" , extra = {" http.request.method" : " get" })
46
- ```
47
- ``` json
48
- {
49
- "@timestamp" : " 2020-03-20T18:11:37.895Z" ,
50
- "ecs" : {
51
- "version" : " 1.6.0"
52
- },
53
- "http" : {
54
- "request" : {
55
- "method" : " get"
56
- }
57
- },
58
- "log" : {
59
- "level" : " debug" ,
60
- "logger" : " app" ,
61
- "origin" : {
62
- "file" : {
63
- "line" : 14 ,
64
- "name" : " test.py"
65
- },
66
- "function" : " func"
67
- },
68
- "original" : " Example message!"
69
- },
70
- "message" : " Example message!"
71
- }
72
- ```
73
-
74
- ##### Excluding Fields
75
-
76
- You can exclude fields from being collected by using the ` exclude_fields ` option
77
- in the ` StdlibFormatter ` constructor:
78
-
79
- ``` python
80
- from ecs_logging import StdlibFormatter
81
-
82
- formatter = StdlibFormatter(
83
- exclude_fields = [
84
- # You can specify individual fields to ignore:
85
- " log.original" ,
86
- # or you can also use prefixes to ignore
87
- # whole categories of fields:
88
- " process" ,
89
- " log.origin" ,
90
- ]
91
- )
92
- ```
93
-
94
- ##### Limiting Stack Traces
95
-
96
- The ` StdlibLogger ` automatically gathers ` exc_info ` into ECS ` error.* ` fields.
97
- If you'd like to control the number of stack frames that are included
98
- in ` error.stack_trace ` you can use the ` stack_trace_limit ` parameter
99
- (by default all frames are collected):
100
-
101
- ``` python
102
- from ecs_logging import StdlibFormatter
103
-
104
- formatter = StdlibFormatter(
105
- # Only collects 3 stack frames
106
- stack_trace_limit = 3 ,
107
- )
108
- formatter = StdlibFormatter(
109
- # Disable stack trace collection
110
- stack_trace_limit = 0 ,
111
- )
112
- ```
113
-
114
- ## Structlog Example
115
-
116
- ``` python
117
- import structlog
118
- import ecs_logging
119
-
120
- # Configure Structlog
121
- structlog.configure(
122
- processors = [ecs_logging.StructlogFormatter()],
123
- wrapper_class = structlog.BoundLogger,
124
- context_class = dict ,
125
- logger_factory = structlog.PrintLoggerFactory(),
126
- )
127
-
128
- # Get the Logger
129
- logger = structlog.get_logger(" app" )
130
-
131
- # Add additional context
132
- logger = logger.bind(** {
133
- " http" : {
134
- " version" : " 2" ,
135
- " request" : {
136
- " method" : " get" ,
137
- " bytes" : 1337 ,
138
- },
139
- },
140
- " url" : {
141
- " domain" : " example.com" ,
142
- " path" : " /" ,
143
- " port" : 443 ,
144
- " scheme" : " https" ,
145
- " registered_domain" : " example.com" ,
146
- " top_level_domain" : " com" ,
147
- " original" : " https://example.com" ,
148
- }
149
- })
150
-
151
- # Emit a log!
152
- logger.debug(" Example message!" )
153
- ```
154
- ``` json
155
- {
156
- "@timestamp" : " 2020-03-26T13:08:11.728Z" ,
157
- "ecs" : {
158
- "version" : " 1.6.0"
159
- },
160
- "http" : {
161
- "request" : {
162
- "bytes" : 1337 ,
163
- "method" : " get"
164
- },
165
- "version" : " 2"
166
- },
167
- "log" : {
168
- "level" : " debug"
169
- },
170
- "message" : " Example message!" ,
171
- "url" : {
172
- "domain" : " example.com" ,
173
- "original" : " https://example.com" ,
174
- "path" : " /" ,
175
- "port" : 443 ,
176
- "registered_domain" : " example.com" ,
177
- "scheme" : " https" ,
178
- "top_level_domain" : " com"
179
- }
180
- }
181
- ```
25
+ See the [ ECS Logging Python reference] ( https://www.elastic.co/guide/en/ecs-logging/python/current/index.html ) on elastic.co to get started.
182
26
183
27
## Elastic APM Log Correlation
184
28
0 commit comments