policyengine-observability 3.0.1__tar.gz → 3.0.2__tar.gz

{policyengine_observability-3.0.1 → policyengine_observability-3.0.2}/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [3.0.2] - 2026-09-30
+
+### Fixed
+
+- Add process-scoped service instance identities and preserve dispatch attributes on nested operations.
+
+
 ## [3.0.1] - 2026-09-28
 
 ### Fixed

{policyengine_observability-3.0.1 → policyengine_observability-3.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: policyengine-observability
-Version: 3.0.1
+Version: 3.0.2
 Summary: Shared PolicyEngine observability runtime for logs, timings, metrics, and OpenTelemetry.
 Author-email: PolicyEngine <hello@policyengine.org>
 License-File: LICENSE
@@ -374,15 +374,42 @@ def worker(payload, *, observability_context=None):
 PolicyEngine request ID, and scalar attributes named by
 `dispatch_attribute_keys`. Starting the remote operation restores only those
 configured dispatch attributes. They remain available to nested
-`capture_context()` calls and are attached to logs and every nested span inside
-the operation. They are never added to metric labels unless separately
-included in `metric_attribute_keys`.
+`capture_context()` calls and are attached to logs, nested operations, and
+nested spans inside the operation. They are never added to metric labels
+unless separately included in `metric_attribute_keys`.
 
 Keep this context separate from the application payload. Invalid or stale
 trace context can reduce correlation, but it does not prevent the observed
 application code from running. A recent direct dispatch continues the trace;
 delayed, retry, and aggregate work starts a trace linked to the dispatch span.
 
+## Process identity
+
+OpenTelemetry resource attributes require `service.instance.id` to identify
+one telemetry-producing process. Deployment revisions identify code shared by
+multiple containers and workers, so they must not be used alone as the process
+identity. Construct the deployment identity after the application process has
+started:
+
+```python
+import os
+
+from policyengine_observability import DeploymentIdentity, process_instance_id
+
+service_name = "example-api"
+deployment = DeploymentIdentity(
+    environment="production",
+    platform="google_cloud_run",
+    region="us-central1",
+    instance_id=process_instance_id(service_name, os.getenv("K_REVISION")),
+)
+```
+
+The helper returns one stable value for a service within the current process.
+It combines the optional platform identifier with a process ID and random UUID,
+so separate workers and containers cannot publish cumulative metrics under the
+same resource identity. A child process receives a new value on its first call.
+
 ## Process restoration and shutdown
 
 After a process image or memory snapshot is restored, rebuild process-local

{policyengine_observability-3.0.1 → policyengine_observability-3.0.2}/README.md

@@ -328,15 +328,42 @@ def worker(payload, *, observability_context=None):
 PolicyEngine request ID, and scalar attributes named by
 `dispatch_attribute_keys`. Starting the remote operation restores only those
 configured dispatch attributes. They remain available to nested
-`capture_context()` calls and are attached to logs and every nested span inside
-the operation. They are never added to metric labels unless separately
-included in `metric_attribute_keys`.
+`capture_context()` calls and are attached to logs, nested operations, and
+nested spans inside the operation. They are never added to metric labels
+unless separately included in `metric_attribute_keys`.
 
 Keep this context separate from the application payload. Invalid or stale
 trace context can reduce correlation, but it does not prevent the observed
 application code from running. A recent direct dispatch continues the trace;
 delayed, retry, and aggregate work starts a trace linked to the dispatch span.
 
+## Process identity
+
+OpenTelemetry resource attributes require `service.instance.id` to identify
+one telemetry-producing process. Deployment revisions identify code shared by
+multiple containers and workers, so they must not be used alone as the process
+identity. Construct the deployment identity after the application process has
+started:
+
+```python
+import os
+
+from policyengine_observability import DeploymentIdentity, process_instance_id
+
+service_name = "example-api"
+deployment = DeploymentIdentity(
+    environment="production",
+    platform="google_cloud_run",
+    region="us-central1",
+    instance_id=process_instance_id(service_name, os.getenv("K_REVISION")),
+)
+```
+
+The helper returns one stable value for a service within the current process.
+It combines the optional platform identifier with a process ID and random UUID,
+so separate workers and containers cannot publish cumulative metrics under the
+same resource identity. A child process receives a new value on its first call.
+
 ## Process restoration and shutdown
 
 After a process image or memory snapshot is restored, rebuild process-local

{policyengine_observability-3.0.1 → policyengine_observability-3.0.2}/docs/engineering/skills/repository-guidance.md

@@ -67,8 +67,8 @@ uv run --extra dev towncrier check --compare-with origin/main
   `remote_context`; do not insert it into business request models.
 - Restore only attributes explicitly listed in `dispatch_attribute_keys`.
   Those attributes must remain available to nested dispatches and structured
-  logs and must be attached to nested spans, but must not become metric labels
-  unless independently allowlisted in `metric_attribute_keys`.
+  logs and must be attached to nested operations and spans, but must not become
+  metric labels unless independently allowlisted in `metric_attribute_keys`.
 - Accept explicitly supplied safe scalar attributes in local logs and spans by
   default. Use `application_attribute_keys` only when a consumer requires a
   strict local allowlist. Do not use that optional local policy to decide what

{policyengine_observability-3.0.1 → policyengine_observability-3.0.2}/policyengine_observability/__init__.py

@@ -21,6 +21,7 @@ from .destinations import (
     StdoutLogDestination,
 )
 from .google_auth import GoogleIdTokenAuth
+from .identity import process_instance_id
 from .integrations import instrument_httpx
 from .runtime import (
     REQUEST_ID_HEADER,
@@ -61,4 +62,5 @@ __all__ = [
     "instrument_flask",
     "instrument_httpx",
     "instrument_logging",
+    "process_instance_id",
 ]

policyengine_observability-3.0.2/policyengine_observability/identity.py

@@ -0,0 +1,36 @@
+"""Stable identities for individual telemetry-producing processes."""
+
+from __future__ import annotations
+
+import os
+from uuid import uuid4
+
+_PROCESS_IDENTITIES: dict[tuple[int, str, str], str] = {}
+
+
+def process_instance_id(
+    service_name: str,
+    platform_instance_id: str | None = None,
+) -> str:
+    """Return a stable, unique identity for one service process.
+
+    Platform identifiers such as a Cloud Run revision identify deployed code,
+    not an individual process. The process ID distinguishes local workers and
+    the UUID distinguishes processes in separate containers that reuse the
+    same operating-system process ID. Including ``os.getpid()`` in the cache
+    key causes a forked child to receive a new identity on its first call.
+    """
+
+    service = service_name.strip()
+    if not service:
+        raise ValueError("service_name must be non-empty")
+    platform_id = (platform_instance_id or "unassigned").strip()
+    if not platform_id:
+        platform_id = "unassigned"
+    process_id = os.getpid()
+    key = (process_id, service, platform_id)
+    existing = _PROCESS_IDENTITIES.get(key)
+    if existing is not None:
+        return existing
+    generated = f"{platform_id}:{process_id}:{uuid4().hex}"
+    return _PROCESS_IDENTITIES.setdefault(key, generated)

{policyengine_observability-3.0.1 → policyengine_observability-3.0.2}/policyengine_observability/runtime.py

@@ -548,6 +548,7 @@ class ObservabilityRuntime:
                 if link is not None:
                     links.append(link)
                 parent = self._otel.empty_context()
+        safe = {**safe, **self._active_dispatch_attributes()}
         active_request = self._request_state.get()
         if request_id is None and active_request is not None:
             request_id = active_request.request_id

{policyengine_observability-3.0.1 → policyengine_observability-3.0.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "policyengine-observability"
-version = "3.0.1"
+version = "3.0.2"
 description = "Shared PolicyEngine observability runtime for logs, timings, metrics, and OpenTelemetry."
 readme = "README.md"
 authors = [{ name = "PolicyEngine", email = "hello@policyengine.org" }]

policyengine_observability-3.0.2/tests/test_identity.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import re
+
+import pytest
+
+from policyengine_observability import identity, process_instance_id
+
+
+def test_process_instance_id_is_stable_within_one_process() -> None:
+    first = process_instance_id("example-api", "revision-1")
+    second = process_instance_id("example-api", "revision-1")
+
+    assert first == second
+    assert re.fullmatch(r"revision-1:\d+:[0-9a-f]{32}", first)
+
+
+def test_process_instance_id_separates_services_and_deployments() -> None:
+    first = process_instance_id("example-api", "revision-1")
+
+    assert process_instance_id("other-api", "revision-1") != first
+    assert process_instance_id("example-api", "revision-2") != first
+
+
+def test_process_instance_id_changes_after_process_duplication(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(identity.os, "getpid", lambda: 10_001)
+    parent = process_instance_id("example-api", "revision-1")
+    monkeypatch.setattr(identity.os, "getpid", lambda: 10_002)
+    child = process_instance_id("example-api", "revision-1")
+
+    assert parent != child
+
+
+def test_process_instance_id_rejects_empty_service_name() -> None:
+    with pytest.raises(ValueError, match="service_name must be non-empty"):
+        process_instance_id("  ")

{policyengine_observability-3.0.1 → policyengine_observability-3.0.2}/tests/test_runtime.py

@@ -270,6 +270,62 @@ def test_nested_span_inherits_active_dispatch_attributes(monkeypatch) -> None:
     observed.shutdown()
 
 
+def test_nested_operation_inherits_active_dispatch_attributes(
+    monkeypatch,
+) -> None:
+    observability_id = "00000000-0000-4000-8000-000000000001"
+    observed, output = make_runtime(
+        application_attribute_keys=frozenset({"simulation_role"}),
+        dispatch_attribute_keys=frozenset({"observability_id"}),
+    )
+    operation_span_attributes = []
+
+    with observed.operation(
+        "simulation.run",
+        remote_context={
+            "captured_at": "not-a-date",
+            "observability_id": observability_id,
+        },
+    ):
+        monkeypatch.setattr(
+            observed._otel,
+            "start_span",
+            lambda _name, **kwargs: operation_span_attributes.append(
+                kwargs["attributes"]
+            ),
+        )
+        with observed.operation(
+            "simulation.plan",
+            attributes={
+                "simulation_role": "baseline",
+                "observability_id": "00000000-0000-4000-8000-000000000099",
+            },
+        ):
+            assert observed.capture_context()["observability_id"] == (
+                observability_id
+            )
+
+    emitted = records(output)
+    nested_completion = next(
+        item
+        for item in emitted
+        if item.get("operation.name") == "simulation.plan"
+    )
+    assert nested_completion["attributes"] == {
+        "simulation_role": "baseline",
+        "observability_id": observability_id,
+    }
+    assert operation_span_attributes == [
+        {
+            "operation.name": "simulation.plan",
+            "operation.kind": "operation",
+            "simulation_role": "baseline",
+            "observability_id": observability_id,
+        }
+    ]
+    observed.shutdown()
+
+
 def test_local_operation_attributes_override_remote_dispatch_values() -> None:
     observed, output = make_runtime(
         dispatch_attribute_keys=frozenset({"job_id"})

{policyengine_observability-3.0.1 → policyengine_observability-3.0.2}/uv.lock

@@ -895,7 +895,7 @@ wheels = [
 
 [[package]]
 name = "policyengine-observability"
-version = "3.0.1"
+version = "3.0.2"
 source = { editable = "." }
 
 [package.optional-dependencies]