nodus-observability 0.1.0__tar.gz

nodus_observability-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shawn Knight
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nodus_observability-0.1.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: nodus-observability
+Version: 0.1.0
+Summary: OTel tracing, Prometheus metrics, structured JSON logging, and trace ContextVars
+Author: Shawn Knight
+License: MIT
+Project-URL: Homepage, https://github.com/Masterplanner25/nodus-observability
+Project-URL: Repository, https://github.com/Masterplanner25/nodus-observability
+Keywords: observability,opentelemetry,prometheus,logging,tracing,nodus
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: logging
+Requires-Dist: python-json-logger>=2.0.0; extra == "logging"
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.0.0; extra == "otel"
+Requires-Dist: opentelemetry-sdk>=1.0.0; extra == "otel"
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.0.0; extra == "otel"
+Requires-Dist: opentelemetry-instrumentation-fastapi>=0.60b0; extra == "otel"
+Provides-Extra: metrics
+Requires-Dist: prometheus-client>=0.10.0; extra == "metrics"
+Provides-Extra: all
+Requires-Dist: nodus-observability[logging,metrics,otel]; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: python-json-logger>=2.0.0; extra == "dev"
+Dynamic: license-file
+
+# nodus-observability
+
+OpenTelemetry bootstrap, Prometheus registry, structured JSON logging, and async-safe trace ContextVars. Zero required dependencies beyond `python-json-logger` — OTel and Prometheus are optional extras.
+
+## Install
+
+```bash
+pip install nodus-observability                    # core only
+pip install "nodus-observability[metrics]"         # + prometheus-client
+pip install "nodus-observability[otel]"            # + opentelemetry stack
+pip install "nodus-observability[all]"             # everything
+```
+
+## Trace context
+
+```python
+from nodus_observability import set_trace_id, get_trace_id, reset_trace_id, ensure_trace_id
+
+tok = set_trace_id("req-abc-123")
+print(get_trace_id())    # "req-abc-123"
+reset_trace_id(tok)
+```
+
+## Structured logging
+
+```python
+from nodus_observability import configure_logging, get_trace_id
+
+configure_logging(
+    env="production",
+    log_level="INFO",
+    get_trace_id_fn=get_trace_id,   # inject trace_id from ContextVar
+)
+```
+
+## OTel tracing
+
+```python
+from nodus_observability import init_otel, get_tracer
+
+init_otel(service_name="my-service")   # reads OTEL_EXPORTER_OTLP_ENDPOINT
+tracer = get_tracer("my-module")
+
+with tracer.start_as_current_span("my-operation") as span:
+    span.set_status("ok")
+```
+
+## Prometheus metrics
+
+```python
+from nodus_observability import create_registry, Counter
+
+REGISTRY = create_registry()   # never use the default global registry
+
+requests_total = Counter(
+    "myapp_requests_total",
+    "Total requests",
+    ["method", "status"],
+    registry=REGISTRY,
+)
+requests_total.labels(method="GET", status="200").inc()
+```
+
+## Extracted from
+
+`AINDY/platform_layer/trace_context.py`, `otel.py`, `metrics.py`, and `log_config.py` in the A.I.N.D.Y. runtime.

nodus_observability-0.1.0/README.md

@@ -0,0 +1,66 @@
+# nodus-observability
+
+OpenTelemetry bootstrap, Prometheus registry, structured JSON logging, and async-safe trace ContextVars. Zero required dependencies beyond `python-json-logger` — OTel and Prometheus are optional extras.
+
+## Install
+
+```bash
+pip install nodus-observability                    # core only
+pip install "nodus-observability[metrics]"         # + prometheus-client
+pip install "nodus-observability[otel]"            # + opentelemetry stack
+pip install "nodus-observability[all]"             # everything
+```
+
+## Trace context
+
+```python
+from nodus_observability import set_trace_id, get_trace_id, reset_trace_id, ensure_trace_id
+
+tok = set_trace_id("req-abc-123")
+print(get_trace_id())    # "req-abc-123"
+reset_trace_id(tok)
+```
+
+## Structured logging
+
+```python
+from nodus_observability import configure_logging, get_trace_id
+
+configure_logging(
+    env="production",
+    log_level="INFO",
+    get_trace_id_fn=get_trace_id,   # inject trace_id from ContextVar
+)
+```
+
+## OTel tracing
+
+```python
+from nodus_observability import init_otel, get_tracer
+
+init_otel(service_name="my-service")   # reads OTEL_EXPORTER_OTLP_ENDPOINT
+tracer = get_tracer("my-module")
+
+with tracer.start_as_current_span("my-operation") as span:
+    span.set_status("ok")
+```
+
+## Prometheus metrics
+
+```python
+from nodus_observability import create_registry, Counter
+
+REGISTRY = create_registry()   # never use the default global registry
+
+requests_total = Counter(
+    "myapp_requests_total",
+    "Total requests",
+    ["method", "status"],
+    registry=REGISTRY,
+)
+requests_total.labels(method="GET", status="200").inc()
+```
+
+## Extracted from
+
+`AINDY/platform_layer/trace_context.py`, `otel.py`, `metrics.py`, and `log_config.py` in the A.I.N.D.Y. runtime.

nodus_observability-0.1.0/nodus_observability/__init__.py

@@ -0,0 +1,81 @@
+"""nodus-observability — OTel tracing, Prometheus metrics, structured logging, trace context.
+
+Trace context (ContextVars — zero dependencies):
+    get_trace_id / set_trace_id / reset_trace_id / ensure_trace_id
+    get_parent_event_id / set_parent_event_id / reset_parent_event_id
+    is_pipeline_active / set_pipeline_active / reset_pipeline_active
+    get_current_request / set_current_request / reset_current_request
+    get_current_execution_context / set_current_execution_context / reset_current_execution_context
+
+OTel tracing (optional — install with [otel] extra):
+    init_otel(service_name)        — bootstrap TracerProvider + OTLP exporter
+    get_tracer(name)               — retrieve tracer (noop when OTEL absent)
+    span_context_from_trace_id     — convert hex trace ID to SpanContext
+
+Prometheus metrics (optional — install with [metrics] extra):
+    create_registry()              — fresh CollectorRegistry (never use the global one)
+    Counter, Histogram, Gauge      — re-exported from prometheus_client
+
+Structured logging:
+    configure_logging(...)         — set up root logger with JSON + correlation fields
+"""
+from .context import (
+    ensure_trace_id,
+    get_current_execution_context,
+    get_current_request,
+    get_current_trace_id,
+    get_parent_event_id,
+    get_trace_id,
+    is_pipeline_active,
+    reset_current_execution_context,
+    reset_current_request,
+    reset_current_trace_id,
+    reset_parent_event_id,
+    reset_pipeline_active,
+    reset_trace_id,
+    set_current_execution_context,
+    set_current_request,
+    set_current_trace_id,
+    set_parent_event_id,
+    set_pipeline_active,
+    set_trace_id,
+)
+from .logging import configure_logging
+from .metrics import Counter, Gauge, Histogram, create_registry
+from .otel import _NoopSpan, _NoopTracer, get_tracer, init_otel, span_context_from_trace_id
+
+__all__ = [
+    # Context
+    "ensure_trace_id",
+    "get_current_execution_context",
+    "get_current_request",
+    "get_current_trace_id",
+    "get_parent_event_id",
+    "get_trace_id",
+    "is_pipeline_active",
+    "reset_current_execution_context",
+    "reset_current_request",
+    "reset_current_trace_id",
+    "reset_parent_event_id",
+    "reset_pipeline_active",
+    "reset_trace_id",
+    "set_current_execution_context",
+    "set_current_request",
+    "set_current_trace_id",
+    "set_parent_event_id",
+    "set_pipeline_active",
+    "set_trace_id",
+    # Logging
+    "configure_logging",
+    # Metrics
+    "Counter",
+    "Gauge",
+    "Histogram",
+    "create_registry",
+    # OTel
+    "_NoopSpan",
+    "_NoopTracer",
+    "get_tracer",
+    "init_otel",
+    "span_context_from_trace_id",
+]

nodus_observability-0.1.0/nodus_observability/context.py

@@ -0,0 +1,109 @@
+"""Async-safe trace and execution context via Python ContextVars."""
+from __future__ import annotations
+
+import uuid
+from contextvars import ContextVar, Token
+from typing import Any
+
+_trace_id_ctx: ContextVar[str] = ContextVar("trace_id", default="-")
+_parent_event_id_ctx: ContextVar[str] = ContextVar("parent_event_id", default="-")
+_pipeline_active_ctx: ContextVar[bool] = ContextVar("pipeline_active", default=False)
+_current_request_ctx: ContextVar[Any] = ContextVar("current_request", default=None)
+_current_execution_context_ctx: ContextVar[Any] = ContextVar(
+    "current_execution_context", default=None
+)
+
+
+def get_trace_id(default: str | None = None) -> str | None:
+    trace_id = _trace_id_ctx.get()
+    if trace_id == "-":
+        return default
+    return trace_id
+
+
+def set_trace_id(trace_id: str) -> Token:
+    return _trace_id_ctx.set(str(trace_id))
+
+
+def reset_trace_id(token: Token) -> None:
+    _trace_id_ctx.reset(token)
+
+
+def ensure_trace_id(trace_id: str | None = None) -> str:
+    """Return existing trace ID or generate/set a new one."""
+    current = get_trace_id()
+    if current:
+        return current
+    generated = str(trace_id or uuid.uuid4())
+    _trace_id_ctx.set(generated)
+    return generated
+
+
+def get_parent_event_id(default: str | None = None) -> str | None:
+    parent_event_id = _parent_event_id_ctx.get()
+    if parent_event_id == "-":
+        return default
+    return parent_event_id
+
+
+def set_parent_event_id(parent_event_id: str | None) -> Token:
+    return _parent_event_id_ctx.set("-" if not parent_event_id else str(parent_event_id))
+
+
+def reset_parent_event_id(token: Token) -> None:
+    _parent_event_id_ctx.reset(token)
+
+
+def is_pipeline_active() -> bool:
+    return bool(_pipeline_active_ctx.get())
+
+
+def set_pipeline_active(active: bool = True) -> Token:
+    return _pipeline_active_ctx.set(bool(active))
+
+
+def reset_pipeline_active(token: Token) -> None:
+    _pipeline_active_ctx.reset(token)
+
+
+def get_current_request(default: Any = None) -> Any:
+    current = _current_request_ctx.get()
+    if current is None:
+        return default
+    return current
+
+
+def set_current_request(request: Any) -> Token:
+    return _current_request_ctx.set(request)
+
+
+def reset_current_request(token: Token) -> None:
+    _current_request_ctx.reset(token)
+
+
+def get_current_execution_context(default: Any = None) -> Any:
+    current = _current_execution_context_ctx.get()
+    if current is None:
+        return default
+    return current
+
+
+def set_current_execution_context(context: Any) -> Token:
+    return _current_execution_context_ctx.set(context)
+
+
+def reset_current_execution_context(token: Token) -> None:
+    _current_execution_context_ctx.reset(token)
+
+
+# Aliases — prefer the shorter names in new code
+def get_current_trace_id(default: str | None = None) -> str | None:
+    return get_trace_id(default=default)
+
+
+def set_current_trace_id(trace_id: str) -> Token:
+    return set_trace_id(trace_id)
+
+
+def reset_current_trace_id(token: Token) -> None:
+    reset_trace_id(token)

nodus_observability-0.1.0/nodus_observability/logging.py

@@ -0,0 +1,165 @@
+"""Structured JSON logging with pluggable correlation context."""
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any, Callable, Optional
+
+_HANDLER_MARKER = "_nodus_structured_logging_handler"
+
+
+class _CorrelationFilter(logging.Filter):
+    """Inject trace_id, user_id, and env into every log record.
+
+    Fields added (all strings):
+      ``trace_id`` — from ``get_trace_id_fn()`` or empty string
+      ``user_id``  — from ``get_request_fn()`` / ``get_context_fn()`` or empty string
+      ``env``      — deployment environment label
+    """
+
+    def __init__(
+        self,
+        env: str = "development",
+        *,
+        get_trace_id_fn: Optional[Callable[[], Optional[str]]] = None,
+        get_request_fn: Optional[Callable[[], Any]] = None,
+        get_context_fn: Optional[Callable[[], Any]] = None,
+    ) -> None:
+        super().__init__()
+        self._env = env
+        self._get_trace_id = get_trace_id_fn or (lambda: None)
+        self._get_request = get_request_fn or (lambda: None)
+        self._get_context = get_context_fn or (lambda: None)
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        try:
+            record.trace_id = self._get_trace_id() or ""
+            request = self._get_request()
+            request_state = getattr(request, "state", None)
+            record.user_id = ""
+            if request_state is not None:
+                record.user_id = str(getattr(request_state, "user_id", "") or "")
+            if not record.user_id:
+                execution_context = self._get_context()
+                if isinstance(execution_context, dict):
+                    record.user_id = str(execution_context.get("user_id", "") or "")
+                elif execution_context is not None:
+                    record.user_id = str(getattr(execution_context, "user_id", "") or "")
+        except Exception:
+            record.trace_id = ""
+            record.user_id = ""
+        record.env = self._env
+        return True
+
+
+def configure_logging(
+    *,
+    env: str = "development",
+    log_level: str = "INFO",
+    json_logs: Optional[bool] = None,
+    force: bool = False,
+    get_trace_id_fn: Optional[Callable[[], Optional[str]]] = None,
+    get_request_fn: Optional[Callable[[], Any]] = None,
+    get_context_fn: Optional[Callable[[], Any]] = None,
+) -> None:
+    """Configure the root logger with structured correlation output.
+
+    ``json_logs`` defaults to True in production/staging, False in dev/test.
+    Override via the ``LOG_FORMAT`` environment variable (``json`` or ``text``).
+
+    Args:
+        env: Deployment environment name (``"development"``, ``"production"``, etc.).
+        log_level: Root log level string (``"DEBUG"``, ``"INFO"``, etc.).
+        json_logs: Force JSON (True) or plain text (False).  Auto-detected when None.
+        force: Replace existing handlers even when one already exists.
+        get_trace_id_fn: Callable returning the current trace ID string or None.
+        get_request_fn: Callable returning the current HTTP request object or None.
+        get_context_fn: Callable returning the current execution context or None.
+
+    Usage with nodus-observability's own context module::
+
+        from nodus_observability import configure_logging, get_trace_id
+        configure_logging(env="development", get_trace_id_fn=get_trace_id)
+
+    Usage with AINDY trace_context::
+
+        from nodus_observability import configure_logging
+        from AINDY.platform_layer.trace_context import get_current_trace_id, get_current_request, get_current_execution_context
+        configure_logging(
+            env="production",
+            get_trace_id_fn=get_current_trace_id,
+            get_request_fn=get_current_request,
+            get_context_fn=get_current_execution_context,
+        )
+    """
+    if json_logs is None:
+        fmt_env = os.getenv("LOG_FORMAT", "").lower()
+        if fmt_env == "json":
+            json_logs = True
+        elif fmt_env == "text":
+            json_logs = False
+        else:
+            json_logs = env.lower() in {"production", "prod", "staging"}
+
+    correlation_filter = _CorrelationFilter(
+        env=env,
+        get_trace_id_fn=get_trace_id_fn,
+        get_request_fn=get_request_fn,
+        get_context_fn=get_context_fn,
+    )
+
+    if json_logs:
+        try:
+            from pythonjsonlogger import jsonlogger
+
+            formatter = jsonlogger.JsonFormatter(
+                fmt="%(asctime)s %(levelname)s %(name)s %(message)s %(trace_id)s %(user_id)s %(env)s",
+                datefmt="%Y-%m-%dT%H:%M:%S",
+                rename_fields={
+                    "asctime": "timestamp",
+                    "levelname": "level",
+                    "name": "logger",
+                },
+            )
+        except ImportError:
+            formatter = logging.Formatter(
+                "%(asctime)s %(levelname)s %(name)s [trace_id=%(trace_id)s user_id=%(user_id)s env=%(env)s] %(message)s",
+                datefmt="%Y-%m-%dT%H:%M:%S",
+            )
+    else:
+        formatter = logging.Formatter(
+            "%(asctime)s %(levelname)s %(name)s [trace_id=%(trace_id)s user_id=%(user_id)s env=%(env)s] %(message)s",
+            datefmt="%Y-%m-%dT%H:%M:%S",
+        )
+
+    handler = logging.StreamHandler()
+    handler.setFormatter(formatter)
+    handler.addFilter(correlation_filter)
+    setattr(handler, _HANDLER_MARKER, True)
+
+    root = logging.getLogger()
+    current_handler = next(
+        (
+            candidate
+            for candidate in root.handlers
+            if getattr(candidate, _HANDLER_MARKER, False)
+        ),
+        None,
+    )
+    should_replace = force or current_handler is None or len(root.handlers) != 1
+
+    if should_replace:
+        root.handlers.clear()
+        root.addHandler(handler)
+    else:
+        current_handler.setFormatter(formatter)
+        for existing_filter in list(current_handler.filters):
+            current_handler.removeFilter(existing_filter)
+        current_handler.addFilter(correlation_filter)
+
+    root.setLevel(getattr(logging, log_level.upper(), logging.INFO))
+
+    if env.lower() in {"production", "prod"}:
+        logging.getLogger("uvicorn.access").setLevel(logging.WARNING)
+        logging.getLogger("sqlalchemy.engine").setLevel(logging.WARNING)
+        logging.getLogger("apscheduler").setLevel(logging.WARNING)

nodus_observability-0.1.0/nodus_observability/metrics.py

@@ -0,0 +1,49 @@
+"""Prometheus metrics helpers.
+
+The core pattern: always use a dedicated ``CollectorRegistry`` rather than
+the default global registry.  This prevents metric registration conflicts
+when multiple libraries or tests share the same Python process.
+
+Usage::
+
+    from nodus_observability import create_registry, Counter, Histogram, Gauge
+
+    REGISTRY = create_registry()
+
+    requests_total = Counter(
+        "myapp_requests_total",
+        "Total HTTP requests",
+        ["method", "status"],
+        registry=REGISTRY,
+    )
+"""
+from __future__ import annotations
+
+try:
+    from prometheus_client import CollectorRegistry, Counter, Gauge, Histogram
+
+    _PROMETHEUS_AVAILABLE = True
+except ImportError:
+    CollectorRegistry = None  # type: ignore[assignment,misc]
+    Counter = None  # type: ignore[assignment,misc]
+    Gauge = None  # type: ignore[assignment,misc]
+    Histogram = None  # type: ignore[assignment,misc]
+    _PROMETHEUS_AVAILABLE = False
+
+
+def create_registry() -> "CollectorRegistry":
+    """Return a fresh Prometheus CollectorRegistry.
+
+    Always prefer a dedicated registry over the default global one to avoid
+    metric name conflicts across libraries and test runs.
+
+    Raises:
+        ImportError: If ``prometheus-client`` is not installed.  Install with
+            ``pip install 'nodus-observability[metrics]'``.
+    """
+    if not _PROMETHEUS_AVAILABLE:
+        raise ImportError(
+            "prometheus-client is required for metrics support. "
+            "Install with: pip install 'nodus-observability[metrics]'"
+        )
+    return CollectorRegistry(auto_describe=True)

nodus_observability-0.1.0/nodus_observability/otel.py

@@ -0,0 +1,109 @@
+"""OpenTelemetry bootstrap with noop fallback."""
+from __future__ import annotations
+
+import logging
+import os
+
+logger = logging.getLogger(__name__)
+_initialized = False
+
+try:
+    from opentelemetry import trace
+    from opentelemetry.sdk.resources import Resource, SERVICE_NAME
+    from opentelemetry.sdk.trace import TracerProvider
+    from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+    _OTEL_AVAILABLE = True
+except ImportError:
+    trace = None
+    Resource = None
+    SERVICE_NAME = None
+    TracerProvider = None
+    BatchSpanProcessor = None
+    _OTEL_AVAILABLE = False
+
+
+class _NoopSpan:
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
+        return False
+
+    def set_status(self, *args, **kwargs):
+        return None
+
+    def record_exception(self, *args, **kwargs):
+        return None
+
+
+class _NoopTracer:
+    def start_as_current_span(self, *args, **kwargs):
+        return _NoopSpan()
+
+
+def init_otel(service_name: str = "app") -> None:
+    """Initialize OTEL TracerProvider. Safe to call multiple times (idempotent).
+
+    Reads ``OTEL_EXPORTER_OTLP_ENDPOINT`` from the environment.  When the
+    variable is not set, tracing is a no-op.  When the opentelemetry packages
+    are not installed, tracing is silently disabled.
+    """
+    global _initialized
+    if _initialized:
+        return
+    if not _OTEL_AVAILABLE:
+        logger.info("[otel] OpenTelemetry packages not installed — tracing is no-op")
+        _initialized = True
+        return
+
+    resource = Resource.create({SERVICE_NAME: service_name})
+    provider = TracerProvider(resource=resource)
+
+    otlp_endpoint = os.getenv("OTEL_EXPORTER_OTLP_ENDPOINT")
+    if otlp_endpoint:
+        try:
+            from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (
+                OTLPSpanExporter,
+            )
+
+            exporter = OTLPSpanExporter(endpoint=otlp_endpoint, insecure=True)
+            provider.add_span_processor(BatchSpanProcessor(exporter))
+            logger.info("[otel] OTLP exporter configured: %s", otlp_endpoint)
+        except Exception as exc:
+            logger.warning("[otel] OTLP exporter setup failed (tracing disabled): %s", exc)
+    else:
+        logger.info("[otel] OTEL_EXPORTER_OTLP_ENDPOINT not set — tracing is no-op")
+
+    trace.set_tracer_provider(provider)
+    _initialized = True
+
+
+def get_tracer(name: str = "app"):
+    """Return a tracer. Returns a no-op tracer when OTEL is unavailable."""
+    if not _OTEL_AVAILABLE:
+        return _NoopTracer()
+    return trace.get_tracer(name)
+
+
+def span_context_from_trace_id(trace_id_hex: str | None):
+    """Convert a hex trace ID string to an OTEL SpanContext for linking.
+
+    Returns None when OTEL is unavailable or the ID is not parseable.
+    """
+    if not _OTEL_AVAILABLE or not trace_id_hex:
+        return None
+    try:
+        tid = int(trace_id_hex.replace("-", "")[:32], 16)
+        sid = tid & ((1 << 64) - 1)
+        if sid == 0:
+            sid = 1
+        return trace.SpanContext(
+            trace_id=tid,
+            span_id=sid,
+            is_remote=True,
+            trace_flags=trace.TraceFlags(trace.TraceFlags.SAMPLED),
+            trace_state=trace.TraceState(),
+        )
+    except Exception:
+        return None

nodus_observability-0.1.0/nodus_observability.egg-info/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: nodus-observability
+Version: 0.1.0
+Summary: OTel tracing, Prometheus metrics, structured JSON logging, and trace ContextVars
+Author: Shawn Knight
+License: MIT
+Project-URL: Homepage, https://github.com/Masterplanner25/nodus-observability
+Project-URL: Repository, https://github.com/Masterplanner25/nodus-observability
+Keywords: observability,opentelemetry,prometheus,logging,tracing,nodus
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: logging
+Requires-Dist: python-json-logger>=2.0.0; extra == "logging"
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.0.0; extra == "otel"
+Requires-Dist: opentelemetry-sdk>=1.0.0; extra == "otel"
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.0.0; extra == "otel"
+Requires-Dist: opentelemetry-instrumentation-fastapi>=0.60b0; extra == "otel"
+Provides-Extra: metrics
+Requires-Dist: prometheus-client>=0.10.0; extra == "metrics"
+Provides-Extra: all
+Requires-Dist: nodus-observability[logging,metrics,otel]; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: python-json-logger>=2.0.0; extra == "dev"
+Dynamic: license-file
+
+# nodus-observability
+
+OpenTelemetry bootstrap, Prometheus registry, structured JSON logging, and async-safe trace ContextVars. Zero required dependencies beyond `python-json-logger` — OTel and Prometheus are optional extras.
+
+## Install
+
+```bash
+pip install nodus-observability                    # core only
+pip install "nodus-observability[metrics]"         # + prometheus-client
+pip install "nodus-observability[otel]"            # + opentelemetry stack
+pip install "nodus-observability[all]"             # everything
+```
+
+## Trace context
+
+```python
+from nodus_observability import set_trace_id, get_trace_id, reset_trace_id, ensure_trace_id
+
+tok = set_trace_id("req-abc-123")
+print(get_trace_id())    # "req-abc-123"
+reset_trace_id(tok)
+```
+
+## Structured logging
+
+```python
+from nodus_observability import configure_logging, get_trace_id
+
+configure_logging(
+    env="production",
+    log_level="INFO",
+    get_trace_id_fn=get_trace_id,   # inject trace_id from ContextVar
+)
+```
+
+## OTel tracing
+
+```python
+from nodus_observability import init_otel, get_tracer
+
+init_otel(service_name="my-service")   # reads OTEL_EXPORTER_OTLP_ENDPOINT
+tracer = get_tracer("my-module")
+
+with tracer.start_as_current_span("my-operation") as span:
+    span.set_status("ok")
+```
+
+## Prometheus metrics
+
+```python
+from nodus_observability import create_registry, Counter
+
+REGISTRY = create_registry()   # never use the default global registry
+
+requests_total = Counter(
+    "myapp_requests_total",
+    "Total requests",
+    ["method", "status"],
+    registry=REGISTRY,
+)
+requests_total.labels(method="GET", status="200").inc()
+```
+
+## Extracted from
+
+`AINDY/platform_layer/trace_context.py`, `otel.py`, `metrics.py`, and `log_config.py` in the A.I.N.D.Y. runtime.

nodus_observability-0.1.0/nodus_observability.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+nodus_observability/__init__.py
+nodus_observability/context.py
+nodus_observability/logging.py
+nodus_observability/metrics.py
+nodus_observability/otel.py
+nodus_observability.egg-info/PKG-INFO
+nodus_observability.egg-info/SOURCES.txt
+nodus_observability.egg-info/dependency_links.txt
+nodus_observability.egg-info/requires.txt
+nodus_observability.egg-info/top_level.txt
+tests/test_context.py
+tests/test_logging.py
+tests/test_otel.py

nodus_observability-0.1.0/nodus_observability.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

nodus_observability-0.1.0/nodus_observability.egg-info/requires.txt

@@ -0,0 +1,19 @@
+
+[all]
+nodus-observability[logging,metrics,otel]
+
+[dev]
+pytest>=8.0
+python-json-logger>=2.0.0
+
+[logging]
+python-json-logger>=2.0.0
+
+[metrics]
+prometheus-client>=0.10.0
+
+[otel]
+opentelemetry-api>=1.0.0
+opentelemetry-sdk>=1.0.0
+opentelemetry-exporter-otlp-proto-grpc>=1.0.0
+opentelemetry-instrumentation-fastapi>=0.60b0

nodus_observability-0.1.0/nodus_observability.egg-info/top_level.txt

@@ -0,0 +1 @@
+nodus_observability

nodus_observability-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=80", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nodus-observability"
+version = "0.1.0"
+description = "OTel tracing, Prometheus metrics, structured JSON logging, and trace ContextVars"
+authors = [{ name = "Shawn Knight" }]
+license = { text = "MIT" }
+readme = "README.md"
+requires-python = ">=3.11"
+keywords = ["observability", "opentelemetry", "prometheus", "logging", "tracing", "nodus"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+]
+dependencies = []
+
+[project.optional-dependencies]
+logging  = ["python-json-logger>=2.0.0"]
+otel     = ["opentelemetry-api>=1.0.0", "opentelemetry-sdk>=1.0.0",
+             "opentelemetry-exporter-otlp-proto-grpc>=1.0.0",
+             "opentelemetry-instrumentation-fastapi>=0.60b0"]
+metrics  = ["prometheus-client>=0.10.0"]
+all      = ["nodus-observability[logging,otel,metrics]"]
+dev      = ["pytest>=8.0", "python-json-logger>=2.0.0"]
+
+[project.urls]
+Homepage = "https://github.com/Masterplanner25/nodus-observability"
+Repository = "https://github.com/Masterplanner25/nodus-observability"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["nodus_observability*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

nodus_observability-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

nodus_observability-0.1.0/tests/test_context.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+import uuid
+
+from nodus_observability import (
+    ensure_trace_id,
+    get_parent_event_id,
+    get_trace_id,
+    is_pipeline_active,
+    reset_parent_event_id,
+    reset_pipeline_active,
+    reset_trace_id,
+    set_parent_event_id,
+    set_pipeline_active,
+    set_trace_id,
+)
+from nodus_observability.context import (
+    get_current_execution_context,
+    get_current_request,
+    reset_current_execution_context,
+    reset_current_request,
+    set_current_execution_context,
+    set_current_request,
+)
+
+
+# ── Trace ID ──────────────────────────────────────────────────────────────────
+
+def test_get_trace_id_default_is_none():
+    # Reset to default state via a fresh set/reset cycle
+    tok = set_trace_id("-")
+    assert get_trace_id() is None
+    reset_trace_id(tok)
+
+
+def test_set_and_get_trace_id():
+    tok = set_trace_id("trace-abc")
+    assert get_trace_id() == "trace-abc"
+    reset_trace_id(tok)
+
+
+def test_reset_trace_id_restores_previous():
+    tok1 = set_trace_id("first")
+    tok2 = set_trace_id("second")
+    assert get_trace_id() == "second"
+    reset_trace_id(tok2)
+    assert get_trace_id() == "first"
+    reset_trace_id(tok1)
+
+
+def test_ensure_trace_id_generates_uuid_when_empty():
+    tok = set_trace_id("-")
+    result = ensure_trace_id()
+    assert result  # non-empty
+    uuid.UUID(result)  # valid UUID
+    reset_trace_id(tok)
+
+
+def test_ensure_trace_id_returns_existing():
+    tok = set_trace_id("existing-id")
+    result = ensure_trace_id()
+    assert result == "existing-id"
+    reset_trace_id(tok)
+
+
+def test_get_trace_id_with_default():
+    tok = set_trace_id("-")
+    assert get_trace_id(default="fallback") == "fallback"
+    reset_trace_id(tok)
+
+
+# ── Parent event ID ───────────────────────────────────────────────────────────
+
+def test_get_parent_event_id_default_is_none():
+    tok = set_parent_event_id(None)
+    assert get_parent_event_id() is None
+    reset_parent_event_id(tok)
+
+
+def test_set_and_get_parent_event_id():
+    tok = set_parent_event_id("event-123")
+    assert get_parent_event_id() == "event-123"
+    reset_parent_event_id(tok)
+
+
+def test_set_parent_event_id_none_clears():
+    tok1 = set_parent_event_id("event-abc")
+    tok2 = set_parent_event_id(None)
+    assert get_parent_event_id() is None
+    reset_parent_event_id(tok2)
+    reset_parent_event_id(tok1)
+
+
+# ── Pipeline active flag ──────────────────────────────────────────────────────
+
+def test_pipeline_active_default_false():
+    assert is_pipeline_active() is False
+
+
+def test_set_pipeline_active():
+    tok = set_pipeline_active(True)
+    assert is_pipeline_active() is True
+    reset_pipeline_active(tok)
+    assert is_pipeline_active() is False
+
+
+# ── Current request ───────────────────────────────────────────────────────────
+
+def test_get_current_request_default_none():
+    assert get_current_request() is None
+
+
+def test_set_and_get_current_request():
+    request = object()
+    tok = set_current_request(request)
+    assert get_current_request() is request
+    reset_current_request(tok)
+
+
+# ── Execution context ─────────────────────────────────────────────────────────
+
+def test_get_execution_context_default_none():
+    assert get_current_execution_context() is None
+
+
+def test_set_and_get_execution_context():
+    ctx = {"user_id": "u1", "run_id": "r1"}
+    tok = set_current_execution_context(ctx)
+    assert get_current_execution_context() is ctx
+    reset_current_execution_context(tok)

nodus_observability-0.1.0/tests/test_logging.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import logging
+
+from nodus_observability import configure_logging, get_trace_id, set_trace_id, reset_trace_id
+
+
+def test_configure_logging_runs_without_error():
+    configure_logging(env="development", force=True)
+
+
+def test_configure_logging_sets_log_level():
+    configure_logging(env="development", log_level="DEBUG", force=True)
+    assert logging.getLogger().level == logging.DEBUG
+    configure_logging(env="development", log_level="INFO", force=True)
+
+
+def test_configure_logging_with_trace_id_fn():
+    tok = set_trace_id("test-trace-123")
+    configure_logging(
+        env="development",
+        force=True,
+        get_trace_id_fn=get_trace_id,
+    )
+    logger = logging.getLogger("test_logging")
+    # Verify the filter injects trace_id — exercise the filter manually
+    root = logging.getLogger()
+    handler = next(
+        (h for h in root.handlers if hasattr(h, "_nodus_structured_logging_handler")),
+        None,
+    )
+    if handler:
+        record = logging.LogRecord(
+            name="test", level=logging.INFO, pathname="", lineno=0,
+            msg="test", args=(), exc_info=None,
+        )
+        for f in handler.filters:
+            f.filter(record)
+        assert record.trace_id == "test-trace-123"
+    reset_trace_id(tok)
+
+
+def test_configure_logging_no_callbacks_does_not_raise():
+    configure_logging(env="development", force=True)
+    root = logging.getLogger()
+    handler = next(
+        (h for h in root.handlers if hasattr(h, "_nodus_structured_logging_handler")),
+        None,
+    )
+    if handler:
+        record = logging.LogRecord(
+            name="test", level=logging.INFO, pathname="", lineno=0,
+            msg="test", args=(), exc_info=None,
+        )
+        for f in handler.filters:
+            f.filter(record)
+        assert record.trace_id == ""
+        assert record.user_id == ""
+
+
+def test_configure_logging_idempotent():
+    configure_logging(env="development", force=True)
+    configure_logging(env="development")  # should not add duplicate handlers
+    root = logging.getLogger()
+    nodus_handlers = [
+        h for h in root.handlers if hasattr(h, "_nodus_structured_logging_handler")
+    ]
+    assert len(nodus_handlers) == 1

nodus_observability-0.1.0/tests/test_otel.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from nodus_observability import get_tracer, init_otel, span_context_from_trace_id
+from nodus_observability.otel import _NoopTracer, _initialized
+
+
+def test_init_otel_is_idempotent():
+    # May already be initialized from a previous test run in the process
+    init_otel(service_name="test")
+    init_otel(service_name="test")  # second call must not raise
+
+
+def test_get_tracer_returns_something():
+    tracer = get_tracer("test-tracer")
+    assert tracer is not None
+
+
+def test_noop_tracer_context_manager():
+    tracer = _NoopTracer()
+    with tracer.start_as_current_span("test-span") as span:
+        span.set_status("ok")
+        span.record_exception(ValueError("test"))
+
+
+def test_span_context_from_trace_id_valid_hex():
+    hex_id = "a" * 32
+    # Returns a SpanContext when OTEL is available, None otherwise — both are valid
+    result = span_context_from_trace_id(hex_id)
+    # Just verify it doesn't raise
+
+
+def test_span_context_from_trace_id_none():
+    result = span_context_from_trace_id(None)
+    assert result is None
+
+
+def test_span_context_from_trace_id_empty():
+    result = span_context_from_trace_id("")
+    assert result is None
+
+
+def test_span_context_from_uuid_style():
+    import uuid
+    uid = str(uuid.uuid4())
+    result = span_context_from_trace_id(uid)
+    # Should not raise regardless of OTEL availability