You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+51-12Lines changed: 51 additions & 12 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
# json-logging
2
2
Python logging library to emit JSON log that can be easily indexed and searchable by logging infrastructure such as [ELK](https://www.elastic.co/webinars/introduction-elk-stack).
3
-
If you're using Cloud Foundry, it worth to check out this library [cf-python-logging-support](https://github.com/SAP/cf-python-logging-support) which I'm also original author and contributor.
3
+
If you're using Cloud Foundry, it worth to check out the library [SAP/cf-python-logging-support](https://github.com/SAP/cf-python-logging-support) which I'm also original author and contributor.
4
4
# Content
5
5
1.[Features](#1-features)
6
6
2.[Installation](#2-installation)
@@ -27,10 +27,11 @@ If you're using Cloud Foundry, it worth to check out this library [cf-python-log
27
27
# 2. Usage
28
28
This library is very intrusive, once configured library will try to configure all loggers (existing and newly created) to emit log in JSON format.
29
29
Install by running this command:
30
-
> pip install json-logging
30
+
> pip install json-logging
31
+
31
32
The most important method is **init(framework_name)**.
32
33
33
-
TODO: using ELK stack to view log
34
+
TODO: update guide on how to use ELK stack to view log
If you want to use root logger as main logger to emit log. Made sure you call **config_root_logger()** after initialize root logger (by
113
-
**logging.basicConfig()** or **logging.getLogger('root')**) [\[2\]](#2-python-logging-propagate)
114
+
logging.basicConfig() or logging.getLogger('root')) [\[2\]](#2-python-logging-propagate)
114
115
```python
115
116
logging.basicConfig()
116
117
json_logging.config_root_logger()
117
118
```
118
119
119
120
# 4. Configuration
120
121
logging library can be configured by setting the value in json_logging
122
+
121
123
Name | Description | Default value
122
124
--- | --- | ---
123
125
ENABLE_JSON_LOGGING | Whether to enable JSON logging mode.Can be set as an environment variable, enable when set to to either one in following list (case-insensitive) **['true', '1', 'y', 'yes']** | false
@@ -126,17 +128,18 @@ CORRELATION_ID_HEADERS | List of HTTP headers that will be used to look for corr
126
128
EMPTY_VALUE | Default value when a logging record property is None | '-'
127
129
CORRELATION_ID_GENERATOR | function to generate unique correlation-id | uuid.uuid1
128
130
JSON_SERIALIZER | function to encode object to JSON | json.dumps
129
-
LAYER | The execution layer in the component that emitted the message | 'python'
130
-
COMPONENT_TYPE | A human-friendly name representing the software component |
131
-
CREATE_CORRELATION_ID_IF_NOT_EXISTS | Whether to generate an new correlation-id in case one is not present.| True
131
+
COMPONENT_ID | Uniquely identifies the software component that has processed the current
132
+
request | EMPTY_VALUE
133
+
COMPONENT_NAME | A human-friendly name representing the software component | EMPTY_VALUE
134
+
COMPONENT_INSTANCE_INDEX | Instance's index of horizontally scaled service | 0
135
+
CREATE_CORRELATION_ID_IF_NOT_EXISTS | Whether to generate an new correlation-id in case one is not present| True
132
136
133
137
# 5. Python References
134
138
135
139
TODO: update Python API docs on Github page
136
140
137
141
# 6. Framework support plugin development
138
-
139
-
To add support for a new web framework, you need to extend following classes in **framework_base** and register support using **register_framework_support** method:
142
+
To add support for a new web framework, you need to extend following classes in [**framework_base**](/blob/master/json_logging/framework_base.py) and register support using [**json_logging.register_framework_support**](https://github.com/thangbn/json-logging-python/blob/master/json_logging/__init__.py#L38) method:
140
143
141
144
Class | Description | Mandatory
142
145
--- | --- | ---
@@ -145,7 +148,7 @@ ResponseAdapter | Helper class help to extract logging-relevant information from
145
148
FrameworkConfigurator | Class to perform logging configuration for given framework as needed | no
146
149
AppRequestInstrumentationConfigurator | Class to perform request instrumentation logging configuration | no
147
150
148
-
Take a look at **json_logging/base_framework.py**, **json_logging.flask** and **json_logging.sanic** packages for reference implementations
151
+
Take a look at [**json_logging/base_framework.py**](blob/master/json_logging/framework_base.py), [**json_logging.flask**](tree/master/json_logging/framework/flask) and [**json_logging.sanic**](/tree/master/json_logging/framework/sanic) packages for reference implementations.
149
152
150
153
# 7. FAQ & Troubleshooting
151
154
1. I configured everything, but no logs are printed out?
msg | The actual message string passed to the logger. | string | This is a log message
190
+
level | The log "level" indicating the severity of the log message. | string | INFO
191
+
thread | Identifies the execution thread in which this log message has been written. | string | http-nio-4655
192
+
logger | The logger name that emits the log message.
193
+
| string | requests-logger
194
+
195
+
- request logs:
196
+
Field | Description | Format | Example
197
+
--- | --- | --- | ---
198
+
request | request path that has been processed. | string | /get/api/v2
199
+
request_received_at | The date when an incoming request was received by the producer.| ISO 8601 YYYY-MM-DDTHH:MM:SS.milliZ The precision is in milliseconds. The timezone is UTC. | 2015-01-24 14:06:05.071Z
200
+
response_sent_at | The date when the response to an incoming request was sent to the consumer. | ditto | 2015-01-24 14:06:05.071Z
201
+
response_time_ms | How many milliseconds it took the producer to prepare the response. | float | 43.476
202
+
protocol | Which protocol was used to issue a request to a producer. In most cases, this will be HTTP (including a version specifier), but for outgoing requests reported by a producer it may contain other values. E.g. a database call via JDBC may report, e.g. "JDBC/1.2" | string | HTTP/1.1
203
+
method | The corresponding protocol method. | string | GET
204
+
remote_ip | IP address of the consumer (might be a proxy, might be the actual client) | string | 192.168.0.1
205
+
remote_host | host name of the consumer (might be a proxy, might be the actual client) | string | my.happy.host
206
+
remote_port | Which TCP port is used by the consumer to establish a connection to the remote producer. | string | 1234
207
+
remote_user | The username associated with the request | string | user_name
208
+
request_size_b | The size in bytes of the request entity or "body" (e.g., in case of POST requests). | long | 1234
209
+
response_status | The status code of the response. | long | 200
210
+
response_content_type | The MIME type associated with the entity of the response if available/specified | long | application/json
211
+
referer | For HTTP requests, identifies the address of the webpage (i.e. the URI or IRI) that linked to the resource being requested. | string | /index.html
212
+
x_forwarded_for | Comma-separated list of IP addresses, the left-most being the original client, followed by proxy server addresses that forwarded the client request. | string | 192.0.2.60,10.12.9.23
0 commit comments