fastapi-gae-logging 0.1.0__tar.gz → 0.2.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {fastapi_gae_logging-0.1.0 → fastapi_gae_logging-0.2.1}/PKG-INFO +1 -1
- fastapi_gae_logging-0.2.1/pyproject.toml +64 -0
- fastapi_gae_logging-0.1.0/pyproject.toml → fastapi_gae_logging-0.2.1/pyproject.toml.orig +7 -1
- {fastapi_gae_logging-0.1.0 → fastapi_gae_logging-0.2.1}/src/fastapi_gae_logging/__init__.py +3 -1
- {fastapi_gae_logging-0.1.0 → fastapi_gae_logging-0.2.1}/src/fastapi_gae_logging/fastapi_gae_logging.py +175 -25
- {fastapi_gae_logging-0.1.0 → fastapi_gae_logging-0.2.1}/README.md +0 -0
- {fastapi_gae_logging-0.1.0 → fastapi_gae_logging-0.2.1}/src/fastapi_gae_logging/py.typed +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.3
|
|
2
2
|
Name: fastapi-gae-logging
|
|
3
|
-
Version: 0.1
|
|
3
|
+
Version: 0.2.1
|
|
4
4
|
Summary: Custom Cloud Logging handler for FastAPI (or any Starlette based) applications deployed in Google App Engine. Groups logs coming from the same request lifecycle and propagates the maximum log level throughout the request lifecycle using middleware and context management.
|
|
5
5
|
Author: Chris Karvouniaris
|
|
6
6
|
Author-email: Chris Karvouniaris <christos.karvouniaris247@gmail.com>
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["uv_build>=0.9.17,<0.10.0"]
|
|
3
|
+
build-backend = "uv_build"
|
|
4
|
+
|
|
5
|
+
[tool.setuptools]
|
|
6
|
+
packages = ["fastapi_gae_logging"]
|
|
7
|
+
|
|
8
|
+
[tool.ruff]
|
|
9
|
+
line-length = 127
|
|
10
|
+
target-version = "py38"
|
|
11
|
+
|
|
12
|
+
[tool.ruff.lint]
|
|
13
|
+
select = [
|
|
14
|
+
"E",
|
|
15
|
+
"F",
|
|
16
|
+
"I",
|
|
17
|
+
"B",
|
|
18
|
+
"C90",
|
|
19
|
+
]
|
|
20
|
+
ignore = []
|
|
21
|
+
|
|
22
|
+
[tool.ruff.lint.mccabe]
|
|
23
|
+
max-complexity = 20
|
|
24
|
+
|
|
25
|
+
[tool.pytest.ini_options]
|
|
26
|
+
testpaths = ["tests"]
|
|
27
|
+
addopts = "-ra"
|
|
28
|
+
|
|
29
|
+
[project]
|
|
30
|
+
name = "fastapi-gae-logging"
|
|
31
|
+
version = "0.2.1"
|
|
32
|
+
description = "Custom Cloud Logging handler for FastAPI (or any Starlette based) applications deployed in Google App Engine. Groups logs coming from the same request lifecycle and propagates the maximum log level throughout the request lifecycle using middleware and context management."
|
|
33
|
+
readme = "README.md"
|
|
34
|
+
requires-python = ">=3.9"
|
|
35
|
+
dependencies = [
|
|
36
|
+
"google-cloud-logging>=3.13.0",
|
|
37
|
+
"starlette>=0.49.3",
|
|
38
|
+
]
|
|
39
|
+
classifiers = [
|
|
40
|
+
"Programming Language :: Python :: 3",
|
|
41
|
+
"Operating System :: OS Independent",
|
|
42
|
+
"License :: OSI Approved :: MIT License",
|
|
43
|
+
]
|
|
44
|
+
|
|
45
|
+
[[project.authors]]
|
|
46
|
+
name = "Chris Karvouniaris"
|
|
47
|
+
email = "christos.karvouniaris247@gmail.com"
|
|
48
|
+
|
|
49
|
+
[project.license]
|
|
50
|
+
text = "MIT"
|
|
51
|
+
|
|
52
|
+
[project.urls]
|
|
53
|
+
Homepage = "https://github.com/chrisK824/fastapi-gae-logging"
|
|
54
|
+
|
|
55
|
+
[dependency-groups]
|
|
56
|
+
dev = [
|
|
57
|
+
"fastapi>=0.128.0",
|
|
58
|
+
"httpx>=0.28.1",
|
|
59
|
+
"httpx2>=2.0.0",
|
|
60
|
+
"pytest>=8.4.2",
|
|
61
|
+
"python-multipart>=0.0.20",
|
|
62
|
+
"ruff>=0.14.10",
|
|
63
|
+
"uvicorn>=0.39.0",
|
|
64
|
+
]
|
|
@@ -7,7 +7,7 @@ packages = ["fastapi_gae_logging"]
|
|
|
7
7
|
|
|
8
8
|
[project]
|
|
9
9
|
name = "fastapi-gae-logging"
|
|
10
|
-
version = "0.1
|
|
10
|
+
version = "0.2.1"
|
|
11
11
|
description = "Custom Cloud Logging handler for FastAPI (or any Starlette based) applications deployed in Google App Engine. Groups logs coming from the same request lifecycle and propagates the maximum log level throughout the request lifecycle using middleware and context management."
|
|
12
12
|
readme = "README.md"
|
|
13
13
|
authors = [
|
|
@@ -33,6 +33,8 @@ Homepage = "https://github.com/chrisK824/fastapi-gae-logging"
|
|
|
33
33
|
dev = [
|
|
34
34
|
"fastapi>=0.128.0",
|
|
35
35
|
"httpx>=0.28.1",
|
|
36
|
+
"httpx2>=2.0.0",
|
|
37
|
+
"pytest>=8.4.2",
|
|
36
38
|
"python-multipart>=0.0.20",
|
|
37
39
|
"ruff>=0.14.10",
|
|
38
40
|
"uvicorn>=0.39.0",
|
|
@@ -48,3 +50,7 @@ ignore = []
|
|
|
48
50
|
|
|
49
51
|
[tool.ruff.lint.mccabe]
|
|
50
52
|
max-complexity = 20
|
|
53
|
+
|
|
54
|
+
[tool.pytest.ini_options]
|
|
55
|
+
testpaths = ["tests"]
|
|
56
|
+
addopts = "-ra"
|
|
@@ -3,11 +3,13 @@ from .fastapi_gae_logging import (
|
|
|
3
3
|
GaeLogSizeLimitFilter,
|
|
4
4
|
GaeUrlib3FullPoolFilter,
|
|
5
5
|
PayloadParser,
|
|
6
|
+
inject_gae_request_context,
|
|
6
7
|
)
|
|
7
8
|
|
|
8
9
|
__all__ = [
|
|
9
10
|
"FastAPIGAELoggingHandler",
|
|
10
11
|
"PayloadParser",
|
|
11
12
|
"GaeLogSizeLimitFilter",
|
|
12
|
-
"GaeUrlib3FullPoolFilter"
|
|
13
|
+
"GaeUrlib3FullPoolFilter",
|
|
14
|
+
"inject_gae_request_context"
|
|
13
15
|
]
|
|
@@ -1,4 +1,6 @@
|
|
|
1
1
|
import contextvars
|
|
2
|
+
import functools
|
|
3
|
+
import inspect
|
|
2
4
|
import logging
|
|
3
5
|
import re
|
|
4
6
|
import sys
|
|
@@ -6,7 +8,7 @@ import time
|
|
|
6
8
|
import traceback
|
|
7
9
|
from datetime import datetime
|
|
8
10
|
from enum import Enum
|
|
9
|
-
from typing import Any, Awaitable, Callable, Dict, List, Optional, Set
|
|
11
|
+
from typing import Any, Awaitable, Callable, Dict, List, NamedTuple, Optional, Set
|
|
10
12
|
|
|
11
13
|
from google.cloud.logging import Client
|
|
12
14
|
from google.cloud.logging_v2 import Logger, Resource
|
|
@@ -28,6 +30,74 @@ GAE_REQUEST_CONTEXT: contextvars.ContextVar[Optional[Dict[str, Any]]] = contextv
|
|
|
28
30
|
)
|
|
29
31
|
|
|
30
32
|
|
|
33
|
+
class TraceContext(NamedTuple):
|
|
34
|
+
"""Trace information extracted from incoming request headers."""
|
|
35
|
+
trace_id: Optional[str] = None
|
|
36
|
+
span_id: Optional[str] = None
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
# Ported from google.cloud.logging_v2.handlers._helpers so behavior matches the official library.
|
|
40
|
+
_VERSION_PART = r"(?!ff)[a-f\d]{2}"
|
|
41
|
+
_TRACE_ID_PART = r"(?![0]{32})[a-f\d]{32}"
|
|
42
|
+
_PARENT_ID_PART = r"(?![0]{16})[a-f\d]{16}"
|
|
43
|
+
_FLAGS_PART = r"[a-f\d]{2}"
|
|
44
|
+
_TRACEPARENT_RE = re.compile(
|
|
45
|
+
f"^\\s?({_VERSION_PART})-({_TRACE_ID_PART})-({_PARENT_ID_PART})-({_FLAGS_PART})(-.*)?\\s?$"
|
|
46
|
+
)
|
|
47
|
+
|
|
48
|
+
# "TRACE_ID[/SPAN_ID][;o=OPTIONS]"
|
|
49
|
+
_XCLOUD_TRACE_RE = re.compile(r"([\w-]+)?(\/?([\w-]+))?(;?o=(\d))?")
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
def parse_traceparent(header: Optional[str]) -> TraceContext:
|
|
53
|
+
"""Parses a W3C `traceparent` header (https://www.w3.org/TR/trace-context/).
|
|
54
|
+
|
|
55
|
+
Returns an empty TraceContext if the header is missing or can't be parsed.
|
|
56
|
+
"""
|
|
57
|
+
if not header:
|
|
58
|
+
return TraceContext()
|
|
59
|
+
|
|
60
|
+
match = _TRACEPARENT_RE.match(header)
|
|
61
|
+
if not match:
|
|
62
|
+
return TraceContext()
|
|
63
|
+
|
|
64
|
+
return TraceContext(trace_id=match.group(2), span_id=match.group(3))
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
def parse_xcloud_trace(header: Optional[str]) -> TraceContext:
|
|
68
|
+
"""Parses a legacy `X-Cloud-Trace-Context` header.
|
|
69
|
+
|
|
70
|
+
The decimal span id is converted to the 16-char hex form Cloud Logging expects.
|
|
71
|
+
A span id that is not a number, is 0, or is >= 2**64 is dropped; the trace id is kept.
|
|
72
|
+
"""
|
|
73
|
+
if not header:
|
|
74
|
+
return TraceContext()
|
|
75
|
+
|
|
76
|
+
match = _XCLOUD_TRACE_RE.match(header)
|
|
77
|
+
if not match:
|
|
78
|
+
return TraceContext()
|
|
79
|
+
|
|
80
|
+
trace_id = match.group(1)
|
|
81
|
+
span_id = match.group(3)
|
|
82
|
+
|
|
83
|
+
try:
|
|
84
|
+
span_int = int(span_id)
|
|
85
|
+
span_id = f"{span_int:016x}" if 0 < span_int < 2 ** 64 else None
|
|
86
|
+
except (ValueError, TypeError):
|
|
87
|
+
span_id = None
|
|
88
|
+
|
|
89
|
+
return TraceContext(trace_id=trace_id, span_id=span_id)
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
def extract_trace_context(headers: Dict[bytes, bytes]) -> TraceContext:
|
|
93
|
+
"""Extracts trace info from ASGI headers: `traceparent` first, then the legacy header."""
|
|
94
|
+
ctx = parse_traceparent(headers.get(b"traceparent", b"").decode("latin-1"))
|
|
95
|
+
if ctx.trace_id:
|
|
96
|
+
return ctx
|
|
97
|
+
|
|
98
|
+
return parse_xcloud_trace(headers.get(b"x-cloud-trace-context", b"").decode("latin-1"))
|
|
99
|
+
|
|
100
|
+
|
|
31
101
|
def get_gae_context() -> Dict[str, Any]:
|
|
32
102
|
"""Retrieves the current GAE request context.
|
|
33
103
|
|
|
@@ -36,19 +106,93 @@ def get_gae_context() -> Dict[str, Any]:
|
|
|
36
106
|
KeyErrors.
|
|
37
107
|
|
|
38
108
|
Returns:
|
|
39
|
-
Dict[str, Any]: The context dictionary containing '
|
|
109
|
+
Dict[str, Any]: The context dictionary containing 'trace_id', 'span_id', 'start_time',
|
|
40
110
|
and 'max_log_level'.
|
|
41
111
|
"""
|
|
42
112
|
ctx = GAE_REQUEST_CONTEXT.get()
|
|
43
113
|
if ctx is None:
|
|
44
114
|
return {
|
|
45
|
-
'
|
|
115
|
+
'trace_id': None,
|
|
116
|
+
'span_id': None,
|
|
46
117
|
'start_time': time.time(),
|
|
47
118
|
'max_log_level': logging.NOTSET
|
|
48
119
|
}
|
|
49
120
|
return ctx
|
|
50
121
|
|
|
51
122
|
|
|
123
|
+
def inject_gae_request_context(func: Callable) -> Callable:
|
|
124
|
+
"""
|
|
125
|
+
Captures the current thread's GAE logging context and wraps the target function
|
|
126
|
+
to ensure the context is injected when executed in a worker thread.
|
|
127
|
+
|
|
128
|
+
Use this utility when passing functions to thread pools (like `ThreadPoolExecutor`)
|
|
129
|
+
to ensure that logs generated inside the worker thread are correctly grouped under
|
|
130
|
+
the parent HTTP request trace in Google Cloud Logging. This safely propagates the
|
|
131
|
+
logging context without copying unrelated context variables (like database sessions),
|
|
132
|
+
preventing deadlocks.
|
|
133
|
+
|
|
134
|
+
The context is set for the duration of the call only and is reset afterwards, so
|
|
135
|
+
reused pool threads never leak one request's trace into a later, unrelated task.
|
|
136
|
+
|
|
137
|
+
Note:
|
|
138
|
+
- Do not use this as a static `@decorator` on a function definition. Decorators
|
|
139
|
+
are evaluated at module import time (before the request exists), so the captured
|
|
140
|
+
context will be empty. Always apply it dynamically at execution time.
|
|
141
|
+
- Only synchronous callables are supported. For an `async def` function the
|
|
142
|
+
context would be set only while the coroutine object is created, not while it
|
|
143
|
+
runs, so it would silently have no effect. Passing a coroutine function raises
|
|
144
|
+
`TypeError`.
|
|
145
|
+
- The request context is shared by reference, not copied. Log levels recorded
|
|
146
|
+
in worker threads therefore contribute to the severity of the parent request
|
|
147
|
+
log, as long as the task logs before the request has finished. Logs emitted
|
|
148
|
+
by tasks that outlive the request are still grouped under the trace, but can
|
|
149
|
+
no longer change the already-emitted request log severity.
|
|
150
|
+
- This is not needed for `starlette.concurrency.run_in_threadpool` or
|
|
151
|
+
`anyio.to_thread.run_sync`, which already copy the full context into the
|
|
152
|
+
worker thread. It is intended for raw `ThreadPoolExecutor` usage.
|
|
153
|
+
|
|
154
|
+
Args:
|
|
155
|
+
func (Callable): A synchronous callable to run in a worker thread.
|
|
156
|
+
|
|
157
|
+
Returns:
|
|
158
|
+
Callable: A wrapper that runs `func` with the captured GAE context active.
|
|
159
|
+
|
|
160
|
+
Raises:
|
|
161
|
+
TypeError: If `func` is a coroutine function.
|
|
162
|
+
|
|
163
|
+
Example:
|
|
164
|
+
```python
|
|
165
|
+
from concurrent.futures import ThreadPoolExecutor
|
|
166
|
+
from fastapi_gae_logging import inject_gae_request_context
|
|
167
|
+
|
|
168
|
+
def background_task(payload: dict):
|
|
169
|
+
logging.info(f"Processing {payload}") # This will be grouped correctly!
|
|
170
|
+
|
|
171
|
+
with ThreadPoolExecutor(max_workers=5) as pool:
|
|
172
|
+
# Wrap the function exactly at submission time
|
|
173
|
+
pool.submit(inject_gae_request_context(background_task), {"user": 123})
|
|
174
|
+
```
|
|
175
|
+
"""
|
|
176
|
+
if inspect.iscoroutinefunction(func):
|
|
177
|
+
raise TypeError(
|
|
178
|
+
"inject_gae_request_context only supports synchronous callables; "
|
|
179
|
+
f"got coroutine function {getattr(func, '__qualname__', func)!r}. "
|
|
180
|
+
"Async code already runs in the request's context."
|
|
181
|
+
)
|
|
182
|
+
|
|
183
|
+
gae_ctx = GAE_REQUEST_CONTEXT.get()
|
|
184
|
+
|
|
185
|
+
@functools.wraps(func)
|
|
186
|
+
def wrapper(*args, **kwargs):
|
|
187
|
+
token = GAE_REQUEST_CONTEXT.set(gae_ctx)
|
|
188
|
+
try:
|
|
189
|
+
return func(*args, **kwargs)
|
|
190
|
+
finally:
|
|
191
|
+
GAE_REQUEST_CONTEXT.reset(token)
|
|
192
|
+
|
|
193
|
+
return wrapper
|
|
194
|
+
|
|
195
|
+
|
|
52
196
|
def bytes_repr(num: float, suffix: str = 'B') -> str:
|
|
53
197
|
"""Converts a byte count into a human-readable string.
|
|
54
198
|
|
|
@@ -171,13 +315,13 @@ class LogInterceptor(logging.Filter):
|
|
|
171
315
|
if record.levelno > max_log_level:
|
|
172
316
|
gae_request_context_data['max_log_level'] = record.levelno
|
|
173
317
|
|
|
174
|
-
|
|
318
|
+
trace_id = gae_request_context_data.get("trace_id")
|
|
319
|
+
span_id = gae_request_context_data.get("span_id")
|
|
175
320
|
|
|
176
|
-
if
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
record._span_id = re.findall(r'^\w+', split_header[1])[0]
|
|
321
|
+
if trace_id:
|
|
322
|
+
record._trace = f"projects/{self.project_id}/traces/{trace_id}"
|
|
323
|
+
if span_id:
|
|
324
|
+
record._span_id = span_id
|
|
181
325
|
|
|
182
326
|
return True
|
|
183
327
|
|
|
@@ -310,22 +454,22 @@ class GAERequestLogger:
|
|
|
310
454
|
builtin_parsers=builtin_payload_parsers,
|
|
311
455
|
custom_parsers=custom_payload_parsers
|
|
312
456
|
)
|
|
313
|
-
self.
|
|
457
|
+
self._trace_prefix = f"projects/{logger.project}/traces/"
|
|
314
458
|
|
|
315
459
|
def _log_level_to_severity(self, log_level: int) -> str:
|
|
316
460
|
"""Converts Python logging levels to Cloud Logging severity strings."""
|
|
317
461
|
return self.LOG_LEVEL_TO_SEVERITY.get(log_level, self.LOG_LEVEL_TO_SEVERITY[logging.NOTSET])
|
|
318
462
|
|
|
319
463
|
@staticmethod
|
|
320
|
-
def _truncate_log_on_cap(log_payload: Any,
|
|
464
|
+
def _truncate_log_on_cap(log_payload: Any, trace: str) -> Any:
|
|
321
465
|
"""Truncates payload if it exceeds the GAE size limit to prevent crash."""
|
|
322
466
|
logging_payload_size = get_real_size(log_payload)
|
|
323
467
|
if logging_payload_size > GCLOUD_LOG_MAX_BYTE_SIZE:
|
|
324
|
-
print(f"Request payload that was skipped in parent log with
|
|
468
|
+
print(f"Request payload that was skipped in parent log with trace {trace}: {log_payload}")
|
|
325
469
|
log_payload = (f"Request logging payload with size {bytes_repr(logging_payload_size)} "
|
|
326
470
|
f"exceeds maximum size of {bytes_repr(GCLOUD_LOG_MAX_BYTE_SIZE)}, "
|
|
327
471
|
f"truncating request body payload from log and using print instead."
|
|
328
|
-
f"Check stdout/stderr for print with
|
|
472
|
+
f"Check stdout/stderr for print with trace {trace}.")
|
|
329
473
|
|
|
330
474
|
return log_payload
|
|
331
475
|
|
|
@@ -336,12 +480,14 @@ class GAERequestLogger:
|
|
|
336
480
|
latency, determines the final severity, and sends the log to GCP.
|
|
337
481
|
"""
|
|
338
482
|
gae_request_context_data = get_gae_context()
|
|
339
|
-
trace = gae_request_context_data['trace']
|
|
340
483
|
|
|
341
|
-
|
|
484
|
+
trace_id = gae_request_context_data.get("trace_id")
|
|
485
|
+
span_id = gae_request_context_data.get("span_id")
|
|
486
|
+
|
|
487
|
+
if not trace_id:
|
|
342
488
|
return
|
|
343
489
|
|
|
344
|
-
|
|
490
|
+
trace = f"{self._trace_prefix}{trace_id}"
|
|
345
491
|
severity = self._log_level_to_severity(log_level=gae_request_context_data['max_log_level'])
|
|
346
492
|
|
|
347
493
|
http_request = {
|
|
@@ -373,12 +519,13 @@ class GAERequestLogger:
|
|
|
373
519
|
f"content type {content_type} failed: {e} | {traceback.format_exc()}")
|
|
374
520
|
|
|
375
521
|
if request_payload:
|
|
376
|
-
logging_payload['request_payload'] = self._truncate_log_on_cap(request_payload,
|
|
522
|
+
logging_payload['request_payload'] = self._truncate_log_on_cap(request_payload, trace)
|
|
377
523
|
|
|
378
524
|
self.logger.log_struct(
|
|
379
525
|
info=logging_payload,
|
|
380
526
|
resource=self.resource,
|
|
381
|
-
trace=
|
|
527
|
+
trace=trace,
|
|
528
|
+
span_id=span_id,
|
|
382
529
|
http_request=http_request,
|
|
383
530
|
severity=severity
|
|
384
531
|
)
|
|
@@ -426,14 +573,17 @@ class FastAPIGAELoggingMiddleware:
|
|
|
426
573
|
await self.app(scope, receive, send)
|
|
427
574
|
return
|
|
428
575
|
|
|
429
|
-
headers = dict(scope.get("headers", []))
|
|
430
|
-
|
|
576
|
+
headers: Dict[bytes, bytes] = dict(scope.get("headers", []))
|
|
577
|
+
trace_ctx = extract_trace_context(headers)
|
|
431
578
|
|
|
432
|
-
GAE_REQUEST_CONTEXT.set(
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
579
|
+
GAE_REQUEST_CONTEXT.set(
|
|
580
|
+
{
|
|
581
|
+
"trace_id": trace_ctx.trace_id,
|
|
582
|
+
"span_id": trace_ctx.span_id,
|
|
583
|
+
"start_time": time.time(),
|
|
584
|
+
"max_log_level": logging.NOTSET,
|
|
585
|
+
}
|
|
586
|
+
)
|
|
437
587
|
|
|
438
588
|
# check if we need to log the request payload
|
|
439
589
|
method = scope.get("method", "GET")
|
|
File without changes
|
|
File without changes
|