fastapi-gae-logging 0.2.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.2.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>
@@ -22,9 +22,13 @@ ignore = []
22
22
  [tool.ruff.lint.mccabe]
23
23
  max-complexity = 20
24
24
 
25
+ [tool.pytest.ini_options]
26
+ testpaths = ["tests"]
27
+ addopts = "-ra"
28
+
25
29
  [project]
26
30
  name = "fastapi-gae-logging"
27
- version = "0.2.0"
31
+ version = "0.2.1"
28
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."
29
33
  readme = "README.md"
30
34
  requires-python = ">=3.9"
@@ -52,6 +56,8 @@ Homepage = "https://github.com/chrisK824/fastapi-gae-logging"
52
56
  dev = [
53
57
  "fastapi>=0.128.0",
54
58
  "httpx>=0.28.1",
59
+ "httpx2>=2.0.0",
60
+ "pytest>=8.4.2",
55
61
  "python-multipart>=0.0.20",
56
62
  "ruff>=0.14.10",
57
63
  "uvicorn>=0.39.0",
@@ -7,7 +7,7 @@ packages = ["fastapi_gae_logging"]
7
7
 
8
8
  [project]
9
9
  name = "fastapi-gae-logging"
10
- version = "0.2.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"
@@ -1,12 +1,14 @@
1
1
  import contextvars
2
2
  import functools
3
+ import inspect
3
4
  import logging
5
+ import re
4
6
  import sys
5
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
 
@@ -61,10 +131,34 @@ def inject_gae_request_context(func: Callable) -> Callable:
61
131
  logging context without copying unrelated context variables (like database sessions),
62
132
  preventing deadlocks.
63
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
+
64
137
  Note:
65
- Do not use this as a static `@decorator` on a function definition. Decorators
66
- are evaluated at module import time (before the request exists), so the captured
67
- context will be empty. Always apply it dynamically at execution time.
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.
68
162
 
69
163
  Example:
70
164
  ```python
@@ -79,14 +173,22 @@ def inject_gae_request_context(func: Callable) -> Callable:
79
173
  pool.submit(inject_gae_request_context(background_task), {"user": 123})
80
174
  ```
81
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
+
82
183
  gae_ctx = GAE_REQUEST_CONTEXT.get()
83
184
 
84
185
  @functools.wraps(func)
85
186
  def wrapper(*args, **kwargs):
86
- if gae_ctx is not None:
87
- GAE_REQUEST_CONTEXT.set(gae_ctx)
88
-
89
- return func(*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)
90
192
 
91
193
  return wrapper
92
194
 
@@ -472,35 +574,16 @@ class FastAPIGAELoggingMiddleware:
472
574
  return
473
575
 
474
576
  headers: Dict[bytes, bytes] = dict(scope.get("headers", []))
475
-
476
- trace_id = None
477
- span_id = None
478
-
479
- # Modern standard trace header
480
- traceparent_bytes = headers.get(b"traceparent", b"")
481
- if traceparent_bytes:
482
- traceparent = traceparent_bytes.decode("latin-1")
483
- parts = traceparent.split("-")
484
- if len(parts) >= 3 and parts[1] and parts[2]:
485
- trace_id = parts[1]
486
- span_id = parts[2]
487
-
488
- # Legacy Google Cloud header
489
- if not trace_id:
490
- x_cloud_trace_bytes = headers.get(b"x-cloud-trace-context", b"")
491
- if x_cloud_trace_bytes:
492
- x_cloud_trace = x_cloud_trace_bytes.decode("latin-1")
493
- parts = x_cloud_trace.split("/")
494
- trace_id = parts[0]
495
- if len(parts) > 1:
496
- span_id = parts[1].split(";")[0]
497
-
498
- GAE_REQUEST_CONTEXT.set({
499
- 'trace_id': trace_id,
500
- 'span_id': span_id,
501
- 'start_time': time.time(),
502
- 'max_log_level': logging.NOTSET
503
- })
577
+ trace_ctx = extract_trace_context(headers)
578
+
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
+ )
504
587
 
505
588
  # check if we need to log the request payload
506
589
  method = scope.get("method", "GET")