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.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.3
2
2
  Name: fastapi-gae-logging
3
- Version: 0.1.0
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.0"
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 'trace', 'start_time',
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
- 'trace': None,
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
- trace = gae_request_context_data['trace']
318
+ trace_id = gae_request_context_data.get("trace_id")
319
+ span_id = gae_request_context_data.get("span_id")
175
320
 
176
- if trace:
177
- split_header = trace.split('/', 1)
178
- record._trace = f"projects/{self.project_id}/traces/{split_header[0]}"
179
- if len(split_header) > 1:
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._trace_parent = f"projects/{logger.project}/traces/"
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, trace_id: str) -> 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 trace_id {trace_id}: {log_payload}")
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 trace_id {trace_id}.")
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
- if not trace:
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
- trace_id = f"{self._trace_parent}{trace.split('/', 1)[0]}"
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, trace_id)
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=trace_id,
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
- trace_header = headers.get(b"x-cloud-trace-context", b"").decode("latin-1") or None
576
+ headers: Dict[bytes, bytes] = dict(scope.get("headers", []))
577
+ trace_ctx = extract_trace_context(headers)
431
578
 
432
- GAE_REQUEST_CONTEXT.set({
433
- 'trace': trace_header,
434
- 'start_time': time.time(),
435
- 'max_log_level': logging.NOTSET
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")