netra-observe 0.1.0__tar.gz

netra_observe-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+dist/
+__pycache__/
+*.egg-info/
+.pytest_cache/

netra_observe-0.1.0/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: netra-observe
+Version: 0.1.0
+Summary: One-line LangChain observability for Netra Runtime: traces into your Usage tab.
+License-Expression: Apache-2.0
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.23
+Requires-Dist: openinference-instrumentation-langchain>=0.1.67
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.20
+Requires-Dist: opentelemetry-sdk>=1.20
+Provides-Extra: dev
+Requires-Dist: langchain-core>=0.2; extra == 'dev'
+Requires-Dist: langchain-openai>=0.1; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# netra-observe
+
+One-line LangChain observability for [Netra Runtime](https://netraruntime.com):
+your agents, chains, tools, and LLM calls land as traces in the dashboard's
+Usage tab, with cost and token numbers taken from the gateway's billing
+ledger — never from client-side estimates.
+
+## Install
+
+```bash
+pip install netra-observe
+```
+
+## Quickstart
+
+```python
+from netra_observe import instrument
+
+instrument(api_key="sk_live_...", project="support-agent")
+```
+
+Call it once at startup, **before** building your chains. Everything
+LangChain runs after that — agents, chains, tools, retrievers, LLM calls —
+is traced automatically (via OpenInference's LangChain instrumentation) and
+exported to Netra over OTLP.
+
+Point your LLM at the Netra gateway as usual:
+
+```python
+from langchain_openai import ChatOpenAI
+
+llm = ChatOpenAI(
+    model="qwen3.6-35b",
+    base_url="https://api.netraruntime.com/v1",
+    api_key="sk_live_...",  # same Netra key
+)
+```
+
+See `examples/langchain_agent.py` for a runnable tool-calling agent.
+
+## Configuration
+
+| `instrument()` argument | Env fallback | Default |
+| --- | --- | --- |
+| `api_key` | `NETRA_API_KEY` | — (required) |
+| `project` | `NETRA_PROJECT` | `None` |
+| `environment` | `NETRA_ENVIRONMENT` | `None` |
+| `endpoint` | `NETRA_OTEL_ENDPOINT` | `https://api.netraruntime.com/v1/otel` |
+| `tracer_provider` | — | netra-observe creates one |
+
+`instrument()` returns a handle: `handle.flush()` forces an export,
+`handle.shutdown()` (or using the handle as a context manager) flushes and
+detaches everything. Pass your own `tracer_provider` to attach Netra's
+exporter setup to an existing OpenTelemetry deployment instead of letting
+the SDK own one.
+
+## How cost attribution works
+
+The SDK propagates W3C trace context (`traceparent`) on HTTP requests to
+the Netra gateway — **propagation only, it never starts spans of its own**.
+The gateway records the trace/span id on its billing ledger row, so the LLM
+span in your trace is joined server-side to the exact request the gateway
+metered. Tokens and cost shown in the Usage tab come from that ledger;
+client-reported numbers are never billed.
+
+## Failure isolation
+
+netra-observe must never break your app: export failures are logged and
+dropped (spans are batched and sent in the background), header injection
+degrades to "no header" on any error, and `shutdown()` caps its final flush
+at 5 seconds.

netra_observe-0.1.0/README.md

@@ -0,0 +1,71 @@
+# netra-observe
+
+One-line LangChain observability for [Netra Runtime](https://netraruntime.com):
+your agents, chains, tools, and LLM calls land as traces in the dashboard's
+Usage tab, with cost and token numbers taken from the gateway's billing
+ledger — never from client-side estimates.
+
+## Install
+
+```bash
+pip install netra-observe
+```
+
+## Quickstart
+
+```python
+from netra_observe import instrument
+
+instrument(api_key="sk_live_...", project="support-agent")
+```
+
+Call it once at startup, **before** building your chains. Everything
+LangChain runs after that — agents, chains, tools, retrievers, LLM calls —
+is traced automatically (via OpenInference's LangChain instrumentation) and
+exported to Netra over OTLP.
+
+Point your LLM at the Netra gateway as usual:
+
+```python
+from langchain_openai import ChatOpenAI
+
+llm = ChatOpenAI(
+    model="qwen3.6-35b",
+    base_url="https://api.netraruntime.com/v1",
+    api_key="sk_live_...",  # same Netra key
+)
+```
+
+See `examples/langchain_agent.py` for a runnable tool-calling agent.
+
+## Configuration
+
+| `instrument()` argument | Env fallback | Default |
+| --- | --- | --- |
+| `api_key` | `NETRA_API_KEY` | — (required) |
+| `project` | `NETRA_PROJECT` | `None` |
+| `environment` | `NETRA_ENVIRONMENT` | `None` |
+| `endpoint` | `NETRA_OTEL_ENDPOINT` | `https://api.netraruntime.com/v1/otel` |
+| `tracer_provider` | — | netra-observe creates one |
+
+`instrument()` returns a handle: `handle.flush()` forces an export,
+`handle.shutdown()` (or using the handle as a context manager) flushes and
+detaches everything. Pass your own `tracer_provider` to attach Netra's
+exporter setup to an existing OpenTelemetry deployment instead of letting
+the SDK own one.
+
+## How cost attribution works
+
+The SDK propagates W3C trace context (`traceparent`) on HTTP requests to
+the Netra gateway — **propagation only, it never starts spans of its own**.
+The gateway records the trace/span id on its billing ledger row, so the LLM
+span in your trace is joined server-side to the exact request the gateway
+metered. Tokens and cost shown in the Usage tab come from that ledger;
+client-reported numbers are never billed.
+
+## Failure isolation
+
+netra-observe must never break your app: export failures are logged and
+dropped (spans are batched and sent in the background), header injection
+degrades to "no header" on any error, and `shutdown()` caps its final flush
+at 5 seconds.

netra_observe-0.1.0/examples/langchain_agent.py

@@ -0,0 +1,35 @@
+"""Weather agent traced into Netra.
+
+Run:  NETRA_API_KEY=sk_live_... python examples/langchain_agent.py
+The LLM calls go through Netra's gateway; the whole run lands as one
+trace in the dashboard's Usage tab.
+"""
+from __future__ import annotations
+
+import os
+
+from langchain_core.tools import tool
+from langchain_openai import ChatOpenAI
+
+from netra_observe import instrument
+
+handle = instrument(project="weather-agent-example", environment="dev")
+
+
+@tool
+def get_weather(city: str) -> str:
+    """Get the current weather for a city."""
+    return f"22°C and sunny in {city}"
+
+
+llm = ChatOpenAI(
+    model=os.environ.get("NETRA_MODEL", "qwen3.6-35b"),
+    base_url="https://api.netraruntime.com/v1",
+    api_key=os.environ["NETRA_API_KEY"],
+).bind_tools([get_weather])
+
+msg = llm.invoke("What's the weather in Jakarta?")
+for call in msg.tool_calls:
+    print("tool call:", call["name"], call["args"])
+
+handle.shutdown()  # flush before exit

netra_observe-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "netra-observe"
+version = "0.1.0"
+description = "One-line LangChain observability for Netra Runtime: traces into your Usage tab."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "Apache-2.0"
+dependencies = [
+    "opentelemetry-sdk>=1.20",
+    "opentelemetry-exporter-otlp-proto-http>=1.20",
+    "openinference-instrumentation-langchain>=0.1.67",
+    "httpx>=0.23",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "langchain-core>=0.2", "langchain-openai>=0.1"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

netra_observe-0.1.0/src/netra_observe/__init__.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import logging
+import threading
+from typing import Optional
+
+from openinference.instrumentation.langchain import LangChainInstrumentor
+from opentelemetry.sdk.trace import TracerProvider
+
+from ._config import Config, NetraConfigError, resolve
+from ._inject import install, uninstall
+from ._provider import build_provider
+from ._runholder import activate as _activate_runholder
+from ._runholder import deactivate as _deactivate_runholder
+
+__version__ = "0.1.0"
+__all__ = ["instrument", "NetraInstrumentation", "NetraConfigError", "__version__"]
+
+logger = logging.getLogger("netra_observe")
+
+_lock = threading.Lock()
+_active: Optional["NetraInstrumentation"] = None
+
+
+class NetraInstrumentation:
+    """Handle returned by instrument(). Context-manager friendly."""
+
+    def __init__(self, provider: TracerProvider, owns_provider: bool) -> None:
+        self.provider = provider
+        self._owns_provider = owns_provider
+
+    def flush(self, timeout_ms: int = 5000) -> None:
+        try:
+            self.provider.force_flush(timeout_ms)
+        except Exception:
+            logger.debug("flush failed", exc_info=True)
+
+    def shutdown(self) -> None:
+        global _active
+        try:
+            LangChainInstrumentor().uninstrument()
+        except Exception:
+            logger.debug("uninstrument failed", exc_info=True)
+        _deactivate_runholder()
+        uninstall()
+        self.flush()
+        if self._owns_provider:
+            try:
+                self.provider.shutdown()
+            except Exception:
+                logger.debug("provider shutdown failed", exc_info=True)
+        with _lock:
+            _active = None
+
+    def __enter__(self) -> "NetraInstrumentation":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.shutdown()
+
+
+def instrument(
+    api_key: Optional[str] = None,
+    project: Optional[str] = None,
+    environment: Optional[str] = None,
+    endpoint: Optional[str] = None,
+    tracer_provider: Optional[TracerProvider] = None,
+) -> NetraInstrumentation:
+    """Wire LangChain tracing into Netra. Idempotent; never raises after
+    config validation succeeds."""
+    global _active
+    with _lock:
+        if _active is not None:
+            return _active
+        cfg = resolve(api_key, project, environment, endpoint)
+        if tracer_provider is not None:
+            provider, owns = tracer_provider, False
+        else:
+            provider, owns = build_provider(cfg), True
+        LangChainInstrumentor().instrument(tracer_provider=provider)
+        _activate_runholder()
+        install(cfg.gateway_host)
+        _active = NetraInstrumentation(provider, owns)
+        return _active
+
+
+def _reset_for_tests() -> None:
+    """Test hook: tear down whatever instrument() set up."""
+    global _active
+    handle = _active
+    if handle is not None:
+        handle.shutdown()
+    else:
+        try:
+            LangChainInstrumentor().uninstrument()
+        except Exception:
+            pass
+        _deactivate_runholder()
+        uninstall()

netra_observe-0.1.0/src/netra_observe/_config.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Optional
+from urllib.parse import urlparse
+
+DEFAULT_ENDPOINT = "https://api.netraruntime.com/v1/otel"
+
+
+class NetraConfigError(ValueError):
+    """Raised for unusable configuration (e.g. no API key anywhere)."""
+
+
+@dataclass(frozen=True)
+class Config:
+    api_key: str
+    endpoint: str
+    gateway_host: str
+    project: Optional[str]
+    environment: Optional[str]
+
+
+def resolve(
+    api_key: Optional[str] = None,
+    project: Optional[str] = None,
+    environment: Optional[str] = None,
+    endpoint: Optional[str] = None,
+) -> Config:
+    key = api_key or os.environ.get("NETRA_API_KEY")
+    if not key:
+        raise NetraConfigError(
+            "netra-observe needs an API key: pass instrument(api_key=...) "
+            "or set NETRA_API_KEY"
+        )
+    ep = (endpoint or os.environ.get("NETRA_OTEL_ENDPOINT") or DEFAULT_ENDPOINT).rstrip("/")
+    host = urlparse(ep).netloc
+    if not host:
+        raise NetraConfigError(f"invalid OTLP endpoint: {ep!r}")
+    return Config(
+        api_key=key,
+        endpoint=ep,
+        gateway_host=host,
+        project=project or os.environ.get("NETRA_PROJECT"),
+        environment=environment or os.environ.get("NETRA_ENVIRONMENT"),
+    )

netra_observe-0.1.0/src/netra_observe/_inject.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import logging
+from typing import Optional
+
+import httpx
+from opentelemetry import propagate
+from opentelemetry import trace as trace_api
+
+logger = logging.getLogger("netra_observe")
+
+_original_send = None
+_original_async_send = None
+_gateway_host: Optional[str] = None
+
+
+def _current_context():
+    """Injection context, best source first (never raises):
+    1. The OpenInference span for the LLM run recorded by our run-holder
+       callback — exact in both bare-invoke and in-chain shapes.
+    2. OpenInference's get_current_span() — inside a parent runnable this is
+       the surrounding run's span (right trace, coarser node).
+    3. None => propagate.inject falls back to ambient context.
+    OpenInference keeps its spans OUT of ambient context by design, which is
+    why 1 and 2 exist at all."""
+    try:
+        from openinference.instrumentation.langchain import (
+            LangChainInstrumentor,
+            get_current_span,
+        )
+
+        from ._runholder import current_llm_run_id
+
+        run_id = current_llm_run_id()
+        if run_id is not None:
+            span = LangChainInstrumentor().get_span(run_id)
+            if span is not None:
+                return trace_api.set_span_in_context(span)
+        span = get_current_span()
+        if span is not None:
+            return trace_api.set_span_in_context(span)
+    except Exception:  # pragma: no cover - defensive
+        logger.debug("injection context resolution failed", exc_info=True)
+    return None  # None => propagate.inject uses ambient context
+
+
+def _inject(request: httpx.Request) -> None:
+    try:
+        if _gateway_host is None or request.url.netloc.decode() != _gateway_host:
+            return
+        ctx = _current_context()
+        if ctx is None and not trace_api.get_current_span().get_span_context().is_valid:
+            return  # nothing to propagate
+        carrier: dict = {}
+        propagate.inject(carrier, context=ctx)
+        for k, v in carrier.items():
+            request.headers[k] = v
+    except Exception:  # never break the host app
+        logger.debug("traceparent injection failed", exc_info=True)
+
+
+def install(gateway_host: str) -> None:
+    global _original_send, _original_async_send, _gateway_host
+    _gateway_host = gateway_host
+    if _original_send is not None:
+        return  # already installed; just retarget the host above
+
+    _original_send = httpx.Client.send
+    _original_async_send = httpx.AsyncClient.send
+
+    def send(self, request, **kwargs):
+        _inject(request)
+        return _original_send(self, request, **kwargs)
+
+    async def async_send(self, request, **kwargs):
+        _inject(request)
+        return await _original_async_send(self, request, **kwargs)
+
+    httpx.Client.send = send
+    httpx.AsyncClient.send = async_send
+
+
+def uninstall() -> None:
+    global _original_send, _original_async_send, _gateway_host
+    if _original_send is not None:
+        httpx.Client.send = _original_send
+        httpx.AsyncClient.send = _original_async_send
+        _original_send = _original_async_send = None
+    _gateway_host = None

netra_observe-0.1.0/src/netra_observe/_provider.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+from ._config import Config
+
+
+def build_resource(cfg: Config) -> Resource:
+    attrs = {"service.name": cfg.project or "netra-observe"}
+    if cfg.project:
+        attrs["netra.project"] = cfg.project
+    if cfg.environment:
+        attrs["deployment.environment"] = cfg.environment
+    return Resource.create(attrs)
+
+
+def build_exporter(cfg: Config) -> OTLPSpanExporter:
+    return OTLPSpanExporter(
+        endpoint=cfg.endpoint + "/v1/traces",
+        headers={"Authorization": f"Bearer {cfg.api_key}"},
+    )
+
+
+def build_provider(cfg: Config) -> TracerProvider:
+    provider = TracerProvider(resource=build_resource(cfg))
+    provider.add_span_processor(BatchSpanProcessor(build_exporter(cfg)))
+    return provider

netra_observe-0.1.0/src/netra_observe/_runholder.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import logging
+from contextvars import ContextVar
+from typing import Any, Optional
+from uuid import UUID
+
+logger = logging.getLogger("netra_observe")
+
+# The chat-model/LLM run currently in flight in this execution context.
+# get_current_span() (OpenInference) only resolves under a PARENT runnable —
+# a bare llm.invoke() leaves LangChain's config contextvar unset, and inside
+# chains it resolves to the surrounding chain's run, not the LLM's. Recording
+# the run id at on_(chat_model|llm)_start gives the exact LLM run in both
+# shapes; _inject looks the span up in OpenInference's registry at HTTP time.
+_current_llm_run: ContextVar[Optional[UUID]] = ContextVar(
+    "netra_current_llm_run", default=None
+)
+
+# register_configure_hook injects the handler held by this var into EVERY
+# callback configure() — including bare invokes with no callbacks passed.
+_holder_var: ContextVar[Optional[Any]] = ContextVar(
+    "netra_run_holder", default=None
+)
+_hook_registered = False
+_holder_cls: Optional[type] = None
+
+
+def current_llm_run_id() -> Optional[UUID]:
+    return _current_llm_run.get()
+
+
+def _build_holder_cls() -> type:
+    """Define the handler lazily: langchain-core is the USER's dependency —
+    importing netra_observe must never require (or crash without) it."""
+    from langchain_core.callbacks import BaseCallbackHandler
+
+    class _RunHolder(BaseCallbackHandler):
+        """Records the in-flight LLM run id. run_inline keeps async dispatch
+        in the caller's context so the ContextVar write is visible to the
+        HTTP call."""
+
+        run_inline = True
+
+        def on_chat_model_start(self, serialized: Any, messages: Any, *, run_id: UUID, **kw: Any) -> None:
+            _current_llm_run.set(run_id)
+
+        def on_llm_start(self, serialized: Any, prompts: Any, *, run_id: UUID, **kw: Any) -> None:
+            _current_llm_run.set(run_id)
+
+        def on_llm_end(self, response: Any, *, run_id: UUID, **kw: Any) -> None:
+            if _current_llm_run.get() == run_id:
+                _current_llm_run.set(None)
+
+        def on_llm_error(self, error: BaseException, *, run_id: UUID, **kw: Any) -> None:
+            if _current_llm_run.get() == run_id:
+                _current_llm_run.set(None)
+
+    return _RunHolder
+
+
+def activate() -> None:
+    """Register the run-holder into LangChain's global callback configuration.
+    No-op (with a debug log) when langchain-core is not installed."""
+    global _hook_registered, _holder_cls
+    try:
+        if _holder_cls is None:
+            _holder_cls = _build_holder_cls()
+        if not _hook_registered:
+            from langchain_core.tracers.context import register_configure_hook
+
+            register_configure_hook(_holder_var, inheritable=True)
+            _hook_registered = True
+        _holder_var.set(_holder_cls())
+    except Exception:  # langchain-core absent or API drift — degrade quietly
+        logger.debug("run-holder activation failed", exc_info=True)
+
+
+def deactivate() -> None:
+    _holder_var.set(None)
+    _current_llm_run.set(None)

netra_observe-0.1.0/tests/conftest.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import threading
+from http.server import BaseHTTPRequestHandler, HTTPServer
+
+import pytest
+
+
+class _Capture(BaseHTTPRequestHandler):
+    captured: list[dict] = []
+
+    def do_GET(self):  # noqa: N802
+        _Capture.captured.append(dict(self.headers))
+        self.send_response(200)
+        self.end_headers()
+        self.wfile.write(b"ok")
+
+    def do_POST(self):  # noqa: N802 - ChatOpenAI POSTs /v1/chat/completions
+        self.rfile.read(int(self.headers.get("Content-Length") or 0))
+        _Capture.captured.append(dict(self.headers))
+        self.send_response(500)
+        self.end_headers()
+        self.wfile.write(b"{}")
+
+    def log_message(self, *a):  # silence
+        pass
+
+
+@pytest.fixture()
+def capture_server():
+    _Capture.captured = []
+    srv = HTTPServer(("127.0.0.1", 0), _Capture)
+    t = threading.Thread(target=srv.serve_forever, daemon=True)
+    t.start()
+    yield f"127.0.0.1:{srv.server_port}", _Capture.captured
+    srv.shutdown()

netra_observe-0.1.0/tests/test_config.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import pytest
+
+from netra_observe._config import Config, NetraConfigError, resolve
+
+
+def test_resolve_defaults(monkeypatch):
+    monkeypatch.delenv("NETRA_OTEL_ENDPOINT", raising=False)
+    cfg = resolve(api_key="sk_live_k")
+    assert cfg.endpoint == "https://api.netraruntime.com/v1/otel"
+    assert cfg.gateway_host == "api.netraruntime.com"
+    assert cfg.project is None and cfg.environment is None
+
+
+def test_resolve_env_fallbacks(monkeypatch):
+    monkeypatch.setenv("NETRA_API_KEY", "sk_live_env")
+    monkeypatch.setenv("NETRA_OTEL_ENDPOINT", "http://localhost:8080/v1/otel/")
+    monkeypatch.setenv("NETRA_PROJECT", "p1")
+    monkeypatch.setenv("NETRA_ENVIRONMENT", "staging")
+    cfg = resolve()
+    assert cfg.api_key == "sk_live_env"
+    assert cfg.endpoint == "http://localhost:8080/v1/otel"  # trailing slash stripped
+    assert cfg.gateway_host == "localhost:8080"  # port preserved
+    assert cfg.project == "p1" and cfg.environment == "staging"
+
+
+def test_args_beat_env(monkeypatch):
+    monkeypatch.setenv("NETRA_API_KEY", "sk_live_env")
+    assert resolve(api_key="sk_live_arg").api_key == "sk_live_arg"
+
+
+def test_missing_key_raises(monkeypatch):
+    monkeypatch.delenv("NETRA_API_KEY", raising=False)
+    with pytest.raises(NetraConfigError):
+        resolve()

netra_observe-0.1.0/tests/test_inject.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+import httpx
+import pytest
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import SimpleSpanProcessor
+from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
+
+from netra_observe._inject import install, uninstall
+
+
+@pytest.fixture(autouse=True)
+def _clean_patch():
+    yield
+    uninstall()
+
+
+def _tracer():
+    exporter = InMemorySpanExporter()
+    provider = TracerProvider()
+    provider.add_span_processor(SimpleSpanProcessor(exporter))
+    return provider.get_tracer("test"), exporter
+
+
+def test_injects_ambient_span_for_gateway_host(capture_server):
+    host, captured = capture_server
+    install(host)
+    tracer, exporter = _tracer()
+    with tracer.start_as_current_span("llm call"):
+        httpx.get(f"http://{host}/v1/chat/completions")
+    assert len(captured) == 1
+    tp = captured[0].get("traceparent")
+    assert tp is not None
+    span = exporter.get_finished_spans()[0]
+    assert format(span.context.trace_id, "032x") in tp
+    assert format(span.context.span_id, "016x") in tp
+
+
+def test_no_injection_for_other_hosts(capture_server):
+    host, captured = capture_server
+    install("api.netraruntime.com")  # patch active, but scope differs
+    tracer, _ = _tracer()
+    with tracer.start_as_current_span("llm call"):
+        httpx.get(f"http://{host}/anything")
+    assert "traceparent" not in captured[0]
+
+
+def test_no_span_no_header(capture_server):
+    host, captured = capture_server
+    install(host)
+    httpx.get(f"http://{host}/v1/chat/completions")
+    assert "traceparent" not in captured[0]
+
+
+def test_install_idempotent_and_uninstall_restores(capture_server):
+    host, captured = capture_server
+    original = httpx.Client.send
+    install(host)
+    install(host)  # second call must not double-wrap
+    patched = httpx.Client.send
+    uninstall()
+    assert httpx.Client.send is original
+    uninstall()  # second uninstall is a no-op
+    assert httpx.Client.send is original
+    assert patched is not original
+
+
+def test_langchain_run_span_wins_over_ambient(capture_server):
+    """Inside a LangChain run, the OpenInference run span (not ambient
+    context) must be the injected parent — that's the ledger-join contract."""
+    from langchain_core.runnables import RunnableLambda
+    from openinference.instrumentation.langchain import LangChainInstrumentor
+
+    host, captured = capture_server
+    exporter = InMemorySpanExporter()
+    provider = TracerProvider()
+    provider.add_span_processor(SimpleSpanProcessor(exporter))
+    LangChainInstrumentor().instrument(tracer_provider=provider)
+    try:
+        install(host)
+        RunnableLambda(
+            lambda _: httpx.get(f"http://{host}/v1/chat/completions").status_code,
+            name="fake llm",
+        ).invoke("hi")
+    finally:
+        LangChainInstrumentor().uninstrument()
+    tp = captured[0].get("traceparent")
+    assert tp is not None
+    run_span = exporter.get_finished_spans()[0]
+    assert format(run_span.context.trace_id, "032x") in tp
+    assert format(run_span.context.span_id, "016x") in tp
+
+
+def test_bare_chat_model_invoke_tags_the_llm_span(capture_server):
+    """A BARE llm.invoke() (no surrounding chain — LangChain's config
+    contextvar is unset) must still inject a traceparent carrying the
+    OpenInference LLM span's ids. This is the exact prod-e2e failure mode:
+    get_current_span() only works under a parent runnable, so the run-holder
+    callback is the source of truth."""
+    from langchain_openai import ChatOpenAI
+    from openinference.instrumentation.langchain import LangChainInstrumentor
+
+    from netra_observe._runholder import activate, deactivate
+
+    host, captured = capture_server
+    exporter = InMemorySpanExporter()
+    provider = TracerProvider()
+    provider.add_span_processor(SimpleSpanProcessor(exporter))
+    LangChainInstrumentor().instrument(tracer_provider=provider)
+    activate()
+    try:
+        install(host)
+        llm = ChatOpenAI(
+            model="m",
+            base_url=f"http://{host}/v1",
+            api_key="sk_live_x",
+            max_retries=0,
+        )
+        with pytest.raises(Exception):
+            llm.invoke("hi")  # capture server answers GETs only → client errors
+    finally:
+        deactivate()
+        LangChainInstrumentor().uninstrument()
+
+    tp = next(
+        (h.get("traceparent") for h in captured if "traceparent" in h), None
+    )
+    assert tp is not None, "bare invoke sent no traceparent"
+    llm_spans = [s for s in exporter.get_finished_spans() if s.name == "ChatOpenAI"]
+    assert llm_spans, "OpenInference did not produce a ChatOpenAI span"
+    span = llm_spans[0]
+    assert format(span.context.trace_id, "032x") in tp
+    assert format(span.context.span_id, "016x") in tp

netra_observe-0.1.0/tests/test_instrument.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+import httpx
+import pytest
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import SimpleSpanProcessor
+from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
+
+import netra_observe
+from netra_observe import NetraInstrumentation, instrument
+
+
+@pytest.fixture(autouse=True)
+def _teardown():
+    yield
+    netra_observe._reset_for_tests()
+
+
+def test_instrument_traces_a_langchain_run():
+    exporter = InMemorySpanExporter()
+    provider = TracerProvider()
+    provider.add_span_processor(SimpleSpanProcessor(exporter))
+    handle = instrument(api_key="sk_live_k", tracer_provider=provider)
+    assert isinstance(handle, NetraInstrumentation)
+
+    from langchain_core.runnables import RunnableLambda
+
+    RunnableLambda(lambda x: x + 1, name="step").invoke(1)
+    handle.flush()
+    names = [s.name for s in exporter.get_finished_spans()]
+    assert "step" in names  # OpenInference traced the run
+
+
+def test_instrument_is_idempotent():
+    provider = TracerProvider()
+    h1 = instrument(api_key="sk_live_k", tracer_provider=provider)
+    h2 = instrument(api_key="sk_live_k", tracer_provider=provider)
+    assert h1 is h2
+
+
+def test_shutdown_restores_httpx():
+    original = httpx.Client.send
+    handle = instrument(api_key="sk_live_k", tracer_provider=TracerProvider())
+    assert httpx.Client.send is not original
+    handle.shutdown()
+    assert httpx.Client.send is original
+
+
+def test_attach_mode_does_not_own_provider():
+    provider = TracerProvider()
+    handle = instrument(api_key="sk_live_k", tracer_provider=provider)
+    handle.shutdown()
+    # user-owned provider must still be usable after our shutdown
+    provider.get_tracer("t").start_span("still alive").end()

netra_observe-0.1.0/tests/test_provider.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from netra_observe._config import resolve
+from netra_observe._provider import build_exporter, build_provider, build_resource
+
+
+def cfg(**kw):
+    kw.setdefault("api_key", "sk_live_k")
+    return resolve(**kw)
+
+
+def test_resource_attrs():
+    r = build_resource(cfg(project="support-agent", environment="prod"))
+    a = r.attributes
+    assert a["netra.project"] == "support-agent"
+    assert a["deployment.environment"] == "prod"
+    assert a["service.name"] == "support-agent"
+
+
+def test_resource_defaults():
+    a = build_resource(cfg()).attributes
+    assert a["service.name"] == "netra-observe"
+    assert "netra.project" not in a and "deployment.environment" not in a
+
+
+def test_exporter_endpoint_and_auth():
+    e = build_exporter(cfg(endpoint="http://localhost:9999/v1/otel"))
+    assert e._endpoint == "http://localhost:9999/v1/otel/v1/traces"
+    # header key case varies across otlp-exporter versions — compare folded
+    headers = {k.lower(): v for k, v in dict(e._headers).items()}
+    assert headers.get("authorization") == "Bearer sk_live_k"
+
+
+def test_provider_has_batch_processor():
+    p = build_provider(cfg())
+    # TracerProvider stores processors on a composite; presence is enough.
+    assert p._active_span_processor._span_processors  # non-empty
+    p.shutdown()