narrativetrace-structlog 0.1.0__tar.gz

narrativetrace_structlog-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+.mutmut-cache
+mutants/
+# pytest-benchmark autosave (poe bench-gate): per-machine comparison history, never comparable
+# across machines -- stays local to whichever machine runs the nightly, like .venv/.uv-cache.
+.benchmarks/
+htmlcov/
+.coverage
+.coverage.*
+dist/
+build/
+*.egg-info/
+
+# Cache for security-tool binaries auto-fetched by scripts/run_security_tool.py
+.tools/
+
+# Local tooling state (contains credentials — never commit)
+.devcontainer/claude-home/
+.agent-run*
+
+# Local tooling state (holds host-absolute paths)
+.claude/settings.local.json

narrativetrace_structlog-0.1.0/LICENSE

@@ -0,0 +1,99 @@
+Business Source License 1.1
+
+License text copyright © 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+Parameters
+
+Licensor:             Empower Agile
+
+Licensed Work:        NarrativeTrace for Python (the narrativetrace PyPI distributions) version {{VERSION}}. The Licensed Work is (c) 2026 Empower Agile.
+
+Additional Use Grant: You may make production use of the Licensed Work for any
+                      purpose, including internal use and use in products and
+                      services you provide to your own customers, provided that
+                      such production use does not include offering the
+                      Licensed Work, or a product or service whose value
+                      derives substantially from the Licensed Work, to third
+                      parties as a logging, tracing, or code-narrative product
+                      or service.
+
+Change Date:          Four years from the date the Licensed Work is published. ({{CHANGE_DATE}} for this version)
+
+Change License:       Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Licensed
+Work, please contact Empower Agile at hello@narrativetrace.ai.
+
+Notice
+
+The Business Source License (this document, or the "License") is not an Open
+Source license. However, the Licensed Work will eventually be made available
+under an Open Source License, as stated in this License.
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN “AS IS” BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License’s text to license
+your works, and to refer to it using the trademark “Business Source License”,
+as long as you comply with the Covenants of Licensor below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License’s text and the “Business
+Source License” name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where “compatible” means that software provided under the Change License can
+   be included in a program with software provided under GPL Version 2.0 or a
+   later version. Licensor may specify additional Change Licenses without
+   limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text “None”.
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.

narrativetrace_structlog-0.1.0/PKG-INFO

@@ -0,0 +1,29 @@
+Metadata-Version: 2.5
+Name: narrativetrace-structlog
+Version: 0.1.0
+Summary: structlog processor injecting narrativetrace correlation keys
+Project-URL: Homepage, https://github.com/narrativetrace/narrativetrace-python
+Project-URL: Source, https://github.com/narrativetrace/narrativetrace-python
+Author: narrativetrace contributors
+License-Expression: BUSL-1.1
+License-File: LICENSE
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: narrativetrace
+Provides-Extra: structlog
+Requires-Dist: structlog>=24; extra == 'structlog'
+Description-Content-Type: text/markdown
+
+# narrativetrace-structlog
+
+A [structlog](https://www.structlog.org) processor that injects [narrativetrace](../narrativetrace)
+correlation keys (`traceId`, `traceName`, `spanId`, `nt.class`, HTTP/request keys, …) into every
+event dict — the same canonical key set the stdlib `NarrativeContextFilter` stamps onto log
+records, so both logging front-ends stay in lockstep.
+
+```python
+import structlog
+from narrativetrace_structlog import narrative_context_processor
+
+structlog.configure(processors=[narrative_context_processor, structlog.processors.JSONRenderer()])
+```

narrativetrace_structlog-0.1.0/README.md

@@ -0,0 +1,13 @@
+# narrativetrace-structlog
+
+A [structlog](https://www.structlog.org) processor that injects [narrativetrace](../narrativetrace)
+correlation keys (`traceId`, `traceName`, `spanId`, `nt.class`, HTTP/request keys, …) into every
+event dict — the same canonical key set the stdlib `NarrativeContextFilter` stamps onto log
+records, so both logging front-ends stay in lockstep.
+
+```python
+import structlog
+from narrativetrace_structlog import narrative_context_processor
+
+structlog.configure(processors=[narrative_context_processor, structlog.processors.JSONRenderer()])
+```

narrativetrace_structlog-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "narrativetrace-structlog"
+version = "0.1.0"
+description = "structlog processor injecting narrativetrace correlation keys"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "BUSL-1.1"
+# See packages/narrativetrace/pyproject.toml: one byte-identical copy of the root LICENSE per
+# distribution, because PEP 639 forbids reaching out of the project directory.
+license-files = ["LICENSE"]
+authors = [{ name = "narrativetrace contributors" }]
+classifiers = ["Typing :: Typed"]
+dependencies = ["narrativetrace"]
+
+[project.urls]
+Homepage = "https://github.com/narrativetrace/narrativetrace-python"
+Source = "https://github.com/narrativetrace/narrativetrace-python"
+
+[project.optional-dependencies]
+structlog = ["structlog>=24"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/narrativetrace_structlog"]
+
+[dependency-groups]
+dev = ["structlog>=24"]

narrativetrace_structlog-0.1.0/src/narrativetrace_structlog/__init__.py

@@ -0,0 +1,36 @@
+"""structlog processor injecting narrativetrace correlation keys.
+
+The SLF4J/MDC enrichment onto structlog. :func:`narrative_context_processor`
+merges the *same* canonical keys as the stdlib :class:`~narrativetrace.NarrativeContextFilter`
+(via :func:`narrativetrace.current_scope_keys`) into every structlog event dict, so the two
+logging front-ends never drift — the cautionary tale being the TypeScript runtime's
+enricher-vs-winston/pino key drift.
+
+Usage::
+
+    import structlog
+    from narrativetrace_structlog import narrative_context_processor
+
+    structlog.configure(
+        processors=[narrative_context_processor, structlog.processors.JSONRenderer()]
+    )
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from narrativetrace import current_scope_keys
+
+__version__ = "0.1.0"
+
+__all__ = ["narrative_context_processor"]
+
+
+def narrative_context_processor(
+    _logger: Any, _method_name: str, event_dict: dict[str, Any]
+) -> dict[str, Any]:
+    """A structlog processor adding the current scope's correlation keys (without overwriting)."""
+    for key, value in current_scope_keys().items():
+        event_dict.setdefault(key, value)
+    return event_dict

narrativetrace_structlog-0.1.0/tests/test_processor.py

@@ -0,0 +1,66 @@
+"""Pins the structlog processor to the same key set as the stdlib NarrativeContextFilter."""
+
+from __future__ import annotations
+
+import logging
+
+import pytest
+from narrativetrace_structlog import narrative_context_processor
+
+from narrativetrace.events import EnterEvent
+from narrativetrace.ids import SpanId, TraceId
+from narrativetrace.logging_bridge import (
+    _REQUEST_SCOPE,
+    _SCOPE_STACK,
+    LoggingTraceConsumer,
+    NarrativeContextFilter,
+    request_log_scope,
+)
+from narrativetrace.signature import MethodSignature
+from narrativetrace.span import SpanContext
+
+
+@pytest.fixture(autouse=True)
+def _reset_scope() -> None:
+    _SCOPE_STACK.set(None)
+    _REQUEST_SCOPE.set(None)
+
+
+def _enter_span() -> None:
+    span = SpanContext(TraceId("0" * 32), SpanId("a" * 16))
+    LoggingTraceConsumer().accept(EnterEvent(span, 0, MethodSignature("OrderService", "place", [])))
+
+
+class TestProcessor:
+    def test_injects_span_keys(self) -> None:
+        _enter_span()
+        event = narrative_context_processor(None, "info", {"event": "hi"})
+        assert event["traceId"] == "0" * 32
+        assert event["nt.class"] == "OrderService"
+        assert event["nt.method"] == "place"
+
+    def test_injects_request_scope_keys(self) -> None:
+        with request_log_scope({"httpMethod": "GET", "traceId": "req"}):
+            event = narrative_context_processor(None, "info", {"event": "hi"})
+        assert event["httpMethod"] == "GET"
+
+    def test_does_not_overwrite_existing_event_keys(self) -> None:
+        _enter_span()
+        event = narrative_context_processor(None, "info", {"traceId": "preset"})
+        assert event["traceId"] == "preset"
+
+    def test_no_keys_outside_a_trace(self) -> None:
+        assert narrative_context_processor(None, "info", {"event": "hi"}) == {"event": "hi"}
+
+    def test_emits_identical_keys_to_stdlib_filter(self) -> None:
+        """The structlog processor and the stdlib filter must produce the same key set."""
+        _enter_span()
+        with request_log_scope({"httpMethod": "GET"}):
+            processor_keys = set(narrative_context_processor(None, "info", {})) - {"event"}
+
+            record = logging.LogRecord("t", logging.INFO, __file__, 1, "m", None, None)
+            NarrativeContextFilter().filter(record)
+            base = set(logging.LogRecord("t", logging.INFO, __file__, 1, "m", None, None).__dict__)
+            filter_keys = set(record.__dict__) - base
+
+        assert processor_keys == filter_keys