add w3c trace context, send trace_id top-level from middleware

Author: Polliog

CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.9.2] - 2026-06-11
+
+### Added
+
+- W3C Trace Context support (`logtide_sdk.tracecontext`): `parse_traceparent`, `format_traceparent`, `generate_trace_id`, `generate_span_id`, `resolve_trace_id` — all exported from the package root
+- All log methods (sync and async) accept keyword-only `trace_id` and `span_id`, sent as top-level fields
+- `LogEntry.span_id` field, serialized as top-level `span_id`
+
+### Changed
+
+- **Middleware (Flask, Django, Starlette/FastAPI) now resolve the inbound trace context per the W3C spec**: `traceparent` header first, legacy `X-Trace-ID` as deprecated fallback, otherwise a new W3C trace ID is generated. The resolved trace ID is sent as the top-level `trace_id` field instead of `metadata["trace_id"]`, so trace correlation in the platform UI now works for middleware logs
+- Auto-generated trace IDs (`auto_trace_id`, `with_new_trace_id`) are now 32-char lowercase-hex W3C IDs instead of UUIDs
+
 ## [0.9.1] - 2026-05-29
 
 ### Fixed

logtide_sdk/__init__.py

@@ -1,6 +1,14 @@
 """LogTide SDK - Official Python SDK for LogTide."""
 
 from logtide_sdk.client import LogTideClient, serialize_exception
+from logtide_sdk.tracecontext import (
+    TraceContext,
+    format_traceparent,
+    generate_span_id,
+    generate_trace_id,
+    parse_traceparent,
+    resolve_trace_id,
+)
 from logtide_sdk.enums import CircuitState, LogLevel
 from logtide_sdk.exceptions import BufferFullError, CircuitBreakerOpenError, LogTideError
 from logtide_sdk.handler import LogTideHandler
@@ -41,6 +49,12 @@
     "LogsResponse",
     "PayloadLimitsOptions",
     "QueryOptions",
+    "TraceContext",
+    "format_traceparent",
+    "generate_span_id",
+    "generate_trace_id",
+    "parse_traceparent",
+    "resolve_trace_id",
     "serialize_exception",
 ]
 

logtide_sdk/async_client.py

@@ -4,7 +4,6 @@
 import dataclasses
 import json
 import time
-import uuid
 from collections.abc import Callable
 from threading import Lock as ThreadingLock
 from typing import Any
@@ -22,6 +21,7 @@
 from logtide_sdk.enums import CircuitState, LogLevel
 from logtide_sdk.exceptions import CircuitBreakerOpenError
 from logtide_sdk.json_encoder import logtide_json_dumps
+from logtide_sdk.tracecontext import generate_trace_id
 from logtide_sdk.models import (
     AggregatedStatsOptions,
     AggregatedStatsResponse,
@@ -154,7 +154,7 @@ async def log(self, entry: LogEntry) -> None:
 
         if entry.trace_id is None:
             if self.options.auto_trace_id:
-                entry.trace_id = str(uuid.uuid4())
+                entry.trace_id = generate_trace_id()
             elif self._trace_id is not None:
                 entry.trace_id = self._trace_id
 
@@ -184,7 +184,13 @@ async def log(self, entry: LogEntry) -> None:
             await self.flush()
 
     async def debug(
-        self, service: str, message: str, metadata: dict[str, Any] | None = None
+        self,
+        service: str,
+        message: str,
+        metadata: dict[str, Any] | None = None,
+        *,
+        trace_id: str | None = None,
+        span_id: str | None = None,
     ) -> None:
         """Log a DEBUG-level message."""
         await self.log(
@@ -193,11 +199,19 @@ async def debug(
                 level=LogLevel.DEBUG,
                 message=message,
                 metadata=metadata or {},
+                trace_id=trace_id,
+                span_id=span_id,
             )
         )
 
     async def info(
-        self, service: str, message: str, metadata: dict[str, Any] | None = None
+        self,
+        service: str,
+        message: str,
+        metadata: dict[str, Any] | None = None,
+        *,
+        trace_id: str | None = None,
+        span_id: str | None = None,
     ) -> None:
         """Log an INFO-level message."""
         await self.log(
@@ -206,11 +220,19 @@ async def info(
                 level=LogLevel.INFO,
                 message=message,
                 metadata=metadata or {},
+                trace_id=trace_id,
+                span_id=span_id,
             )
         )
 
     async def warn(
-        self, service: str, message: str, metadata: dict[str, Any] | None = None
+        self,
+        service: str,
+        message: str,
+        metadata: dict[str, Any] | None = None,
+        *,
+        trace_id: str | None = None,
+        span_id: str | None = None,
     ) -> None:
         """Log a WARN-level message."""
         await self.log(
@@ -219,6 +241,8 @@ async def warn(
                 level=LogLevel.WARN,
                 message=message,
                 metadata=metadata or {},
+                trace_id=trace_id,
+                span_id=span_id,
             )
         )
 
@@ -227,6 +251,9 @@ async def error(
         service: str,
         message: str,
         metadata_or_error: dict[str, Any] | Exception | None = None,
+        *,
+        trace_id: str | None = None,
+        span_id: str | None = None,
     ) -> None:
         """Log an ERROR-level message. Accepts an Exception for automatic serialization."""
         metadata = self._process_metadata_or_error(metadata_or_error)
@@ -236,6 +263,8 @@ async def error(
                 level=LogLevel.ERROR,
                 message=message,
                 metadata=metadata,
+                trace_id=trace_id,
+                span_id=span_id,
             )
         )
 
@@ -244,6 +273,9 @@ async def critical(
         service: str,
         message: str,
         metadata_or_error: dict[str, Any] | Exception | None = None,
+        *,
+        trace_id: str | None = None,
+        span_id: str | None = None,
     ) -> None:
         """Log a CRITICAL-level message. Accepts an Exception for automatic serialization."""
         metadata = self._process_metadata_or_error(metadata_or_error)
@@ -253,6 +285,8 @@ async def critical(
                 level=LogLevel.CRITICAL,
                 message=message,
                 metadata=metadata,
+                trace_id=trace_id,
+                span_id=span_id,
             )
         )
 

logtide_sdk/client.py

@@ -6,7 +6,6 @@
 import re
 import time
 import traceback
-import uuid
 from collections.abc import Callable, Iterator
 from contextlib import contextmanager
 from threading import Event, Lock, Thread, Timer
@@ -18,6 +17,7 @@
 from logtide_sdk.enums import CircuitState, LogLevel
 from logtide_sdk.exceptions import CircuitBreakerOpenError
 from logtide_sdk.json_encoder import logtide_json_dumps
+from logtide_sdk.tracecontext import generate_trace_id
 from logtide_sdk.models import (
     AggregatedStatsOptions,
     AggregatedStatsResponse,
@@ -202,7 +202,7 @@ def with_new_trace_id(self) -> Iterator[None]:
             with client.with_new_trace_id():
                 client.info('worker', 'Background job')
         """
-        with self.with_trace_id(str(uuid.uuid4())):
+        with self.with_trace_id(generate_trace_id()):
             yield
 
     # -----------------------------------------------------------------------
@@ -223,7 +223,7 @@ def log(self, entry: LogEntry) -> None:
         # Inject trace ID
         if entry.trace_id is None:
             if self.options.auto_trace_id:
-                entry.trace_id = str(uuid.uuid4())
+                entry.trace_id = generate_trace_id()
             elif self._trace_id is not None:
                 entry.trace_id = self._trace_id
 
@@ -255,36 +255,66 @@ def log(self, entry: LogEntry) -> None:
         if should_flush:
             self.flush()
 
-    def debug(self, service: str, message: str, metadata: dict[str, Any] | None = None) -> None:
+    def debug(
+        self,
+        service: str,
+        message: str,
+        metadata: dict[str, Any] | None = None,
+        *,
+        trace_id: str | None = None,
+        span_id: str | None = None,
+    ) -> None:
         """Log a DEBUG-level message."""
         self.log(
             LogEntry(
                 service=service,
                 level=LogLevel.DEBUG,
                 message=message,
                 metadata=metadata or {},
+                trace_id=trace_id,
+                span_id=span_id,
             )
         )
 
-    def info(self, service: str, message: str, metadata: dict[str, Any] | None = None) -> None:
+    def info(
+        self,
+        service: str,
+        message: str,
+        metadata: dict[str, Any] | None = None,
+        *,
+        trace_id: str | None = None,
+        span_id: str | None = None,
+    ) -> None:
         """Log an INFO-level message."""
         self.log(
             LogEntry(
                 service=service,
                 level=LogLevel.INFO,
                 message=message,
                 metadata=metadata or {},
+                trace_id=trace_id,
+                span_id=span_id,
             )
         )
 
-    def warn(self, service: str, message: str, metadata: dict[str, Any] | None = None) -> None:
+    def warn(
+        self,
+        service: str,
+        message: str,
+        metadata: dict[str, Any] | None = None,
+        *,
+        trace_id: str | None = None,
+        span_id: str | None = None,
+    ) -> None:
         """Log a WARN-level message."""
         self.log(
             LogEntry(
                 service=service,
                 level=LogLevel.WARN,
                 message=message,
                 metadata=metadata or {},
+                trace_id=trace_id,
+                span_id=span_id,
             )
         )
 
@@ -293,6 +323,9 @@ def error(
         service: str,
         message: str,
         metadata_or_error: dict[str, Any] | Exception | None = None,
+        *,
+        trace_id: str | None = None,
+        span_id: str | None = None,
     ) -> None:
         """
         Log an ERROR-level message.
@@ -309,6 +342,8 @@ def error(
                 level=LogLevel.ERROR,
                 message=message,
                 metadata=metadata,
+                trace_id=trace_id,
+                span_id=span_id,
             )
         )
 
@@ -317,6 +352,9 @@ def critical(
         service: str,
         message: str,
         metadata_or_error: dict[str, Any] | Exception | None = None,
+        *,
+        trace_id: str | None = None,
+        span_id: str | None = None,
     ) -> None:
         """
         Log a CRITICAL-level message.
@@ -333,6 +371,8 @@ def critical(
                 level=LogLevel.CRITICAL,
                 message=message,
                 metadata=metadata,
+                trace_id=trace_id,
+                span_id=span_id,
             )
         )
 

logtide_sdk/middleware/django.py

@@ -13,6 +13,7 @@
     )
 
 from logtide_sdk.client import LogTideClient, serialize_exception
+from logtide_sdk.tracecontext import resolve_trace_id
 
 
 class LogTideDjangoMiddleware:
@@ -64,9 +65,13 @@ def __call__(self, request: HttpRequest) -> HttpResponse:
         if self._should_skip(request.path):
             return self.get_response(request)
 
-        # Extract trace ID from headers (kept local — not set on the shared client
-        # to avoid race conditions across concurrent requests).
-        trace_id: str | None = request.headers.get("X-Trace-ID")
+        # Resolve the inbound trace context (kept local — not set on the shared
+        # client to avoid race conditions across concurrent requests).
+        # Order: W3C traceparent -> legacy X-Trace-ID -> generated (spec 005).
+        trace_id: str = resolve_trace_id(
+            request.headers.get("traceparent"),
+            request.headers.get("X-Trace-ID"),
+        )
 
         # Log request
         start_time = time.time()
@@ -103,13 +108,12 @@ def _log_request(self, request: HttpRequest, trace_id: str | None = None) -> Non
         }
         if self.include_headers:
             metadata["headers"] = dict(request.headers)
-        if trace_id:
-            metadata["trace_id"] = trace_id
 
         self.client.info(
             self.service_name,
             f"{request.method} {request.path}",
             metadata,
+            trace_id=trace_id,
         )
 
     def _log_response(
@@ -128,17 +132,15 @@ def _log_response(
         }
         if self.include_headers:
             metadata["response_headers"] = dict(response.items())
-        if trace_id:
-            metadata["trace_id"] = trace_id
 
         message = f"{request.method} {request.path} {response.status_code} ({duration_ms:.0f}ms)"
 
         if response.status_code >= 500:
-            self.client.error(self.service_name, message, metadata)
+            self.client.error(self.service_name, message, metadata, trace_id=trace_id)
         elif response.status_code >= 400:
-            self.client.warn(self.service_name, message, metadata)
+            self.client.warn(self.service_name, message, metadata, trace_id=trace_id)
         else:
-            self.client.info(self.service_name, message, metadata)
+            self.client.info(self.service_name, message, metadata, trace_id=trace_id)
 
     def _log_error(
         self,
@@ -154,12 +156,11 @@ def _log_error(
             "duration_ms": round(duration_ms, 2),
             "exception": serialize_exception(error),
         }
-        if trace_id:
-            metadata["trace_id"] = trace_id
         self.client.error(
             self.service_name,
             f"Request error: {request.method} {request.path} - {str(error)}",
             metadata,
+            trace_id=trace_id,
         )
 
     def _get_client_ip(self, request: HttpRequest) -> str | None: