fastapi-gae-logging 0.1.0__tar.gz → 0.2.0__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.0
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,58 @@
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
+ [project]
26
+ name = "fastapi-gae-logging"
27
+ version = "0.2.0"
28
+ 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
+ readme = "README.md"
30
+ requires-python = ">=3.9"
31
+ dependencies = [
32
+ "google-cloud-logging>=3.13.0",
33
+ "starlette>=0.49.3",
34
+ ]
35
+ classifiers = [
36
+ "Programming Language :: Python :: 3",
37
+ "Operating System :: OS Independent",
38
+ "License :: OSI Approved :: MIT License",
39
+ ]
40
+
41
+ [[project.authors]]
42
+ name = "Chris Karvouniaris"
43
+ email = "christos.karvouniaris247@gmail.com"
44
+
45
+ [project.license]
46
+ text = "MIT"
47
+
48
+ [project.urls]
49
+ Homepage = "https://github.com/chrisK824/fastapi-gae-logging"
50
+
51
+ [dependency-groups]
52
+ dev = [
53
+ "fastapi>=0.128.0",
54
+ "httpx>=0.28.1",
55
+ "python-multipart>=0.0.20",
56
+ "ruff>=0.14.10",
57
+ "uvicorn>=0.39.0",
58
+ ]
@@ -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.0"
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 = [
@@ -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,6 +1,6 @@
1
1
  import contextvars
2
+ import functools
2
3
  import logging
3
- import re
4
4
  import sys
5
5
  import time
6
6
  import traceback
@@ -36,19 +36,61 @@ def get_gae_context() -> Dict[str, Any]:
36
36
  KeyErrors.
37
37
 
38
38
  Returns:
39
- Dict[str, Any]: The context dictionary containing 'trace', 'start_time',
39
+ Dict[str, Any]: The context dictionary containing 'trace_id', 'span_id', 'start_time',
40
40
  and 'max_log_level'.
41
41
  """
42
42
  ctx = GAE_REQUEST_CONTEXT.get()
43
43
  if ctx is None:
44
44
  return {
45
- 'trace': None,
45
+ 'trace_id': None,
46
+ 'span_id': None,
46
47
  'start_time': time.time(),
47
48
  'max_log_level': logging.NOTSET
48
49
  }
49
50
  return ctx
50
51
 
51
52
 
53
+ def inject_gae_request_context(func: Callable) -> Callable:
54
+ """
55
+ Captures the current thread's GAE logging context and wraps the target function
56
+ to ensure the context is injected when executed in a worker thread.
57
+
58
+ Use this utility when passing functions to thread pools (like `ThreadPoolExecutor`)
59
+ to ensure that logs generated inside the worker thread are correctly grouped under
60
+ the parent HTTP request trace in Google Cloud Logging. This safely propagates the
61
+ logging context without copying unrelated context variables (like database sessions),
62
+ preventing deadlocks.
63
+
64
+ 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.
68
+
69
+ Example:
70
+ ```python
71
+ from concurrent.futures import ThreadPoolExecutor
72
+ from fastapi_gae_logging import inject_gae_request_context
73
+
74
+ def background_task(payload: dict):
75
+ logging.info(f"Processing {payload}") # This will be grouped correctly!
76
+
77
+ with ThreadPoolExecutor(max_workers=5) as pool:
78
+ # Wrap the function exactly at submission time
79
+ pool.submit(inject_gae_request_context(background_task), {"user": 123})
80
+ ```
81
+ """
82
+ gae_ctx = GAE_REQUEST_CONTEXT.get()
83
+
84
+ @functools.wraps(func)
85
+ def wrapper(*args, **kwargs):
86
+ if gae_ctx is not None:
87
+ GAE_REQUEST_CONTEXT.set(gae_ctx)
88
+
89
+ return func(*args, **kwargs)
90
+
91
+ return wrapper
92
+
93
+
52
94
  def bytes_repr(num: float, suffix: str = 'B') -> str:
53
95
  """Converts a byte count into a human-readable string.
54
96
 
@@ -171,13 +213,13 @@ class LogInterceptor(logging.Filter):
171
213
  if record.levelno > max_log_level:
172
214
  gae_request_context_data['max_log_level'] = record.levelno
173
215
 
174
- trace = gae_request_context_data['trace']
216
+ trace_id = gae_request_context_data.get("trace_id")
217
+ span_id = gae_request_context_data.get("span_id")
175
218
 
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]
219
+ if trace_id:
220
+ record._trace = f"projects/{self.project_id}/traces/{trace_id}"
221
+ if span_id:
222
+ record._span_id = span_id
181
223
 
182
224
  return True
183
225
 
@@ -310,22 +352,22 @@ class GAERequestLogger:
310
352
  builtin_parsers=builtin_payload_parsers,
311
353
  custom_parsers=custom_payload_parsers
312
354
  )
313
- self._trace_parent = f"projects/{logger.project}/traces/"
355
+ self._trace_prefix = f"projects/{logger.project}/traces/"
314
356
 
315
357
  def _log_level_to_severity(self, log_level: int) -> str:
316
358
  """Converts Python logging levels to Cloud Logging severity strings."""
317
359
  return self.LOG_LEVEL_TO_SEVERITY.get(log_level, self.LOG_LEVEL_TO_SEVERITY[logging.NOTSET])
318
360
 
319
361
  @staticmethod
320
- def _truncate_log_on_cap(log_payload: Any, trace_id: str) -> Any:
362
+ def _truncate_log_on_cap(log_payload: Any, trace: str) -> Any:
321
363
  """Truncates payload if it exceeds the GAE size limit to prevent crash."""
322
364
  logging_payload_size = get_real_size(log_payload)
323
365
  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}")
366
+ print(f"Request payload that was skipped in parent log with trace {trace}: {log_payload}")
325
367
  log_payload = (f"Request logging payload with size {bytes_repr(logging_payload_size)} "
326
368
  f"exceeds maximum size of {bytes_repr(GCLOUD_LOG_MAX_BYTE_SIZE)}, "
327
369
  f"truncating request body payload from log and using print instead."
328
- f"Check stdout/stderr for print with trace_id {trace_id}.")
370
+ f"Check stdout/stderr for print with trace {trace}.")
329
371
 
330
372
  return log_payload
331
373
 
@@ -336,12 +378,14 @@ class GAERequestLogger:
336
378
  latency, determines the final severity, and sends the log to GCP.
337
379
  """
338
380
  gae_request_context_data = get_gae_context()
339
- trace = gae_request_context_data['trace']
340
381
 
341
- if not trace:
382
+ trace_id = gae_request_context_data.get("trace_id")
383
+ span_id = gae_request_context_data.get("span_id")
384
+
385
+ if not trace_id:
342
386
  return
343
387
 
344
- trace_id = f"{self._trace_parent}{trace.split('/', 1)[0]}"
388
+ trace = f"{self._trace_prefix}{trace_id}"
345
389
  severity = self._log_level_to_severity(log_level=gae_request_context_data['max_log_level'])
346
390
 
347
391
  http_request = {
@@ -373,12 +417,13 @@ class GAERequestLogger:
373
417
  f"content type {content_type} failed: {e} | {traceback.format_exc()}")
374
418
 
375
419
  if request_payload:
376
- logging_payload['request_payload'] = self._truncate_log_on_cap(request_payload, trace_id)
420
+ logging_payload['request_payload'] = self._truncate_log_on_cap(request_payload, trace)
377
421
 
378
422
  self.logger.log_struct(
379
423
  info=logging_payload,
380
424
  resource=self.resource,
381
- trace=trace_id,
425
+ trace=trace,
426
+ span_id=span_id,
382
427
  http_request=http_request,
383
428
  severity=severity
384
429
  )
@@ -426,11 +471,33 @@ class FastAPIGAELoggingMiddleware:
426
471
  await self.app(scope, receive, send)
427
472
  return
428
473
 
429
- headers = dict(scope.get("headers", []))
430
- trace_header = headers.get(b"x-cloud-trace-context", b"").decode("latin-1") or None
474
+ 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]
431
497
 
432
498
  GAE_REQUEST_CONTEXT.set({
433
- 'trace': trace_header,
499
+ 'trace_id': trace_id,
500
+ 'span_id': span_id,
434
501
  'start_time': time.time(),
435
502
  'max_log_level': logging.NOTSET
436
503
  })