elinaobs 0.1.0__tar.gz

elinaobs-0.1.0/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2026 ElinaObs Contributors
+
+Third-party files retain their original copyright notices and licenses.
+
+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.

elinaobs-0.1.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: elinaobs
+Version: 0.1.0
+Summary: Framework-agnostic Python LLM tracing using OpenTelemetry
+Author: ElinaObs Contributors
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: opentelemetry-api<2,>=1.36
+Requires-Dist: opentelemetry-sdk<2,>=1.36
+Requires-Dist: opentelemetry-exporter-otlp-proto-http<2,>=1.36
+Requires-Dist: requests<3,>=2
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: opentelemetry-instrumentation-requests<1,>=0.57b0; extra == "dev"
+Dynamic: license-file
+
+# ElinaObs Python SDK
+
+Python tracing SDK for self-hosted Elina. Licensed under MIT.
+
+## Install
+
+Once published on PyPI:
+
+```bash
+python -m pip install elinaobs
+```
+
+For development from this repository:
+
+```bash
+python -m pip install -e '.[dev]'
+pytest -q
+```
+
+## Public API
+
+```python
+from elinaobs import init, trace, flush, shutdown, diagnose, submit_feedback
+
+init(api_key="...", endpoint="http://localhost:3000/v1/traces", service_name="my-agent")
+
+@trace(name="Agent", as_type="agent")
+async def run(question):
+    return await your_code(question)
+
+# The existing OTel-instrumented operations called inside run() are children.
+```
+
+Application feedback is optional. After a trace has finished, an app with a verdict can send it using the same project key. Inside a decorated function, capture the trace ID and keep it with the result:
+
+```python
+from opentelemetry import trace as otel_trace
+trace_id = f"{otel_trace.get_current_span().get_span_context().trace_id:032x}"
+# Later, after the traced function returns:
+submit_feedback(trace_id, "bad", note="Wrong answer")  # trace_id is 32 lowercase hex characters
+```
+
+Apps without a feedback signal do not call this function. Feedback is stored separately from the dashboard's human review. Keep the project key in server-side code, not in a browser.
+
+To send a demo trace to the local Elina server, create a project in the dashboard and copy its one-time ingestion key. Then, from this directory in PowerShell:
+
+```powershell
+$env:ELINA_WRITE_KEY = "paste-project-ingestion-key"
+$env:ELINA_BASE_URL = "http://127.0.0.1:3000"
+python examples/agent.py
+```
+
+The script prints the trace ID and reports whether export succeeded. Open the project’s Traces page and select that ID to inspect the three spans and their captured input/output.
+
+Only operations that are explicitly decorated or already instrumented by a compatible OpenTelemetry instrumentation package create spans. **No framework integrations are installed, imported, or configured by ElinaObs.**
+
+The Elina receiver lives in the sibling `elina-server` directory. Start it before running `examples/agent.py`. The default tests use in-memory and local HTTP receivers.
+
+To also verify export through a real OpenTelemetry Collector, set `OTELCOL_BINARY` to the Collector executable path and run `python -m pytest -q tests/test_collector.py`. This optional test starts a local Collector with a file exporter and checks the received spans.
+
+## What it does
+
+- Sync + async function decorator with native OTel parent context.
+- 10 span display classifications using `elinaobs.observation.type`.
+- Selective export: only spans starting inside a `@trace()` scope.
+- OTLP/HTTP protobuf, bearer-token auth, background batching.
+- Optional bounded input/output capture, disabled by default.
+- An optional `redact` callback can remove secrets from captured free text before export.
+- `attribute_allowlist` and `attribute_denylist` filter span, event, and link attributes in ElinaObs exports; the denylist wins when both contain a key.
+- Exceptions automatically record OTel error status/events.
+- Shares an existing OpenTelemetry SDK TracerProvider when present.
+- `flush()` reports failed export batches or dropped spans. `diagnose()` returns `failed_batches`, `dropped_spans`, and `retry_attempts` without exposing credentials. Drop counts are updated after a successful processor flush; retry attempts count extra HTTP requests made for a batch.
+
+## Non-goals for v0.1
+
+- Framework adapters or `integrations=[...]`.
+- Raw threads, multiprocessing, distributed orchestration, or generator tracing.
+- Automatic patching of uninstrumented Python libraries.
+- Prompt management, evaluations, or server/UI implementation.
+
+## Known limitations before production
+
+- SDK processor cannot modify existing OTel provider sampling or resources.
+- Capture filtering uses a ContextVar marker; parent spans begun before a
+  decorator scope are not exported to ElinaObs unless also eligible.
+- `as_type="event"` is a timed span category, not an OTel instant event.
+- Incoming external spans from `opentelemetry-instrument` share global provider
+  and may require controlling initialization order.
+- Bounded batches can drop data on overload. `dropped_spans` is current only
+  after `flush()` or `shutdown()`. `retry_attempts` is `None` when an OpenTelemetry
+  credential-provider session is configured. Export failures remain counted
+  even if later batches succeed.
+- Input/output redaction is best-effort only. Explicitly inspect anything you
+  opt in to collect.
+- Attribute lists do not change an application's other OpenTelemetry exporters
+  or resource metadata. Keys are matched exactly.
+- `shutdown()` ends only ElinaObs's processor. Do not reinitialize the SDK in
+  the same interpreter after shutdown.
+
+See [docs/LLD.md](docs/LLD.md) for the finalized architecture and build checklist.

elinaobs-0.1.0/README.md

@@ -0,0 +1,100 @@
+# ElinaObs Python SDK
+
+Python tracing SDK for self-hosted Elina. Licensed under MIT.
+
+## Install
+
+Once published on PyPI:
+
+```bash
+python -m pip install elinaobs
+```
+
+For development from this repository:
+
+```bash
+python -m pip install -e '.[dev]'
+pytest -q
+```
+
+## Public API
+
+```python
+from elinaobs import init, trace, flush, shutdown, diagnose, submit_feedback
+
+init(api_key="...", endpoint="http://localhost:3000/v1/traces", service_name="my-agent")
+
+@trace(name="Agent", as_type="agent")
+async def run(question):
+    return await your_code(question)
+
+# The existing OTel-instrumented operations called inside run() are children.
+```
+
+Application feedback is optional. After a trace has finished, an app with a verdict can send it using the same project key. Inside a decorated function, capture the trace ID and keep it with the result:
+
+```python
+from opentelemetry import trace as otel_trace
+trace_id = f"{otel_trace.get_current_span().get_span_context().trace_id:032x}"
+# Later, after the traced function returns:
+submit_feedback(trace_id, "bad", note="Wrong answer")  # trace_id is 32 lowercase hex characters
+```
+
+Apps without a feedback signal do not call this function. Feedback is stored separately from the dashboard's human review. Keep the project key in server-side code, not in a browser.
+
+To send a demo trace to the local Elina server, create a project in the dashboard and copy its one-time ingestion key. Then, from this directory in PowerShell:
+
+```powershell
+$env:ELINA_WRITE_KEY = "paste-project-ingestion-key"
+$env:ELINA_BASE_URL = "http://127.0.0.1:3000"
+python examples/agent.py
+```
+
+The script prints the trace ID and reports whether export succeeded. Open the project’s Traces page and select that ID to inspect the three spans and their captured input/output.
+
+Only operations that are explicitly decorated or already instrumented by a compatible OpenTelemetry instrumentation package create spans. **No framework integrations are installed, imported, or configured by ElinaObs.**
+
+The Elina receiver lives in the sibling `elina-server` directory. Start it before running `examples/agent.py`. The default tests use in-memory and local HTTP receivers.
+
+To also verify export through a real OpenTelemetry Collector, set `OTELCOL_BINARY` to the Collector executable path and run `python -m pytest -q tests/test_collector.py`. This optional test starts a local Collector with a file exporter and checks the received spans.
+
+## What it does
+
+- Sync + async function decorator with native OTel parent context.
+- 10 span display classifications using `elinaobs.observation.type`.
+- Selective export: only spans starting inside a `@trace()` scope.
+- OTLP/HTTP protobuf, bearer-token auth, background batching.
+- Optional bounded input/output capture, disabled by default.
+- An optional `redact` callback can remove secrets from captured free text before export.
+- `attribute_allowlist` and `attribute_denylist` filter span, event, and link attributes in ElinaObs exports; the denylist wins when both contain a key.
+- Exceptions automatically record OTel error status/events.
+- Shares an existing OpenTelemetry SDK TracerProvider when present.
+- `flush()` reports failed export batches or dropped spans. `diagnose()` returns `failed_batches`, `dropped_spans`, and `retry_attempts` without exposing credentials. Drop counts are updated after a successful processor flush; retry attempts count extra HTTP requests made for a batch.
+
+## Non-goals for v0.1
+
+- Framework adapters or `integrations=[...]`.
+- Raw threads, multiprocessing, distributed orchestration, or generator tracing.
+- Automatic patching of uninstrumented Python libraries.
+- Prompt management, evaluations, or server/UI implementation.
+
+## Known limitations before production
+
+- SDK processor cannot modify existing OTel provider sampling or resources.
+- Capture filtering uses a ContextVar marker; parent spans begun before a
+  decorator scope are not exported to ElinaObs unless also eligible.
+- `as_type="event"` is a timed span category, not an OTel instant event.
+- Incoming external spans from `opentelemetry-instrument` share global provider
+  and may require controlling initialization order.
+- Bounded batches can drop data on overload. `dropped_spans` is current only
+  after `flush()` or `shutdown()`. `retry_attempts` is `None` when an OpenTelemetry
+  credential-provider session is configured. Export failures remain counted
+  even if later batches succeed.
+- Input/output redaction is best-effort only. Explicitly inspect anything you
+  opt in to collect.
+- Attribute lists do not change an application's other OpenTelemetry exporters
+  or resource metadata. Keys are matched exactly.
+- `shutdown()` ends only ElinaObs's processor. Do not reinitialize the SDK in
+  the same interpreter after shutdown.
+
+See [docs/LLD.md](docs/LLD.md) for the finalized architecture and build checklist.

elinaobs-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "elinaobs"
+license = "MIT"
+version = "0.1.0"
+description = "Framework-agnostic Python LLM tracing using OpenTelemetry"
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [{name = "ElinaObs Contributors"}]
+dependencies = [
+    "opentelemetry-api>=1.36,<2",
+    "opentelemetry-sdk>=1.36,<2",
+    "opentelemetry-exporter-otlp-proto-http>=1.36,<2",
+    "requests>=2,<3",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=0.24", "mypy>=1.10", "opentelemetry-instrumentation-requests>=0.57b0,<1"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

elinaobs-0.1.0/setup.cfg

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

elinaobs-0.1.0/src/elinaobs/__init__.py

@@ -0,0 +1,7 @@
+"""ElinaObs Python SDK: decorator first, framework agnostic, OTLP native."""
+from .decorators import trace
+from .runtime import diagnose, flush, init, shutdown, submit_feedback
+from .types import ObservationType
+
+__all__ = ["init", "trace", "flush", "shutdown", "diagnose", "submit_feedback", "ObservationType"]
+__version__ = "0.1.0"

elinaobs-0.1.0/src/elinaobs/context.py

@@ -0,0 +1,6 @@
+"""ElinaObs capture selection, NOT a replacement for OTel parent context."""
+from contextvars import ContextVar
+
+# Inherited by normal sync nesting and asyncio tasks.
+# The OTel context still owns trace and parent/span IDs.
+capture_active: ContextVar[bool] = ContextVar("elinaobs_capture_active", default=False)

elinaobs-0.1.0/src/elinaobs/decorators.py

@@ -0,0 +1,106 @@
+"""Framework-agnostic decorator for ordinary sync and async Python functions."""
+from __future__ import annotations
+
+import functools
+import inspect
+from collections.abc import Callable
+from typing import Any, TypeVar, cast, overload
+
+from opentelemetry import trace as otel_trace
+
+from .context import capture_active
+from .runtime import get_config
+from .serialization import serialize
+from .types import OBSERVATION_TYPES, ObservationType
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+@overload
+def trace(func: F, /) -> F: ...
+
+
+@overload
+def trace(*, name: str | None = None, as_type: ObservationType = "span") -> Callable[[F], F]: ...
+
+
+def trace(
+    func: F | None = None,
+    /,
+    *,
+    name: str | None = None,
+    as_type: ObservationType = "span",
+) -> F | Callable[[F], F]:
+    """Time a Python function and attach any OTel-instrumented children.
+
+    This v0.1 deliberately rejects generator functions. Their lifetime is
+    iteration, not function invocation, so naïve wrappers would lie.
+    """
+    if as_type not in OBSERVATION_TYPES:
+        raise ValueError(f"Unknown observation type: {as_type!r}")
+    if name is not None and not name.strip():
+        raise ValueError("name must be nonempty")
+
+    def decorate(fn: F) -> F:
+        if inspect.isgeneratorfunction(fn) or inspect.isasyncgenfunction(fn):
+            raise TypeError("@trace does not support generator functions in v0.1")
+        label = name or fn.__qualname__
+
+        def attach_input(span, args, kwargs, settings):
+            if not settings.capture_input or not span.is_recording():
+                return
+            try:
+                bound = inspect.signature(fn).bind_partial(*args, **kwargs)
+                value = dict(bound.arguments)
+                value.pop("self", None)
+                value.pop("cls", None)
+                span.set_attribute("elinaobs.input", serialize(value, max_chars=settings.max_content_chars, redact=settings.redact))
+            except Exception:  # instrumentation must not break the application
+                pass
+
+        def attach_output(span, value, settings):
+            if not settings.capture_output or not span.is_recording():
+                return
+            try:
+                span.set_attribute("elinaobs.output", serialize(value, max_chars=settings.max_content_chars, redact=settings.redact))
+            except Exception:
+                pass
+
+        if inspect.iscoroutinefunction(fn):
+            @functools.wraps(fn)
+            async def async_wrapper(*args, **kwargs):
+                settings = get_config()
+                token = capture_active.set(True)
+                try:
+                    tracer = otel_trace.get_tracer("elinaobs.sdk", "0.1.0")
+                    with tracer.start_as_current_span(
+                        label, attributes={"elinaobs.observation.type": as_type}
+                    ) as span:
+                        attach_input(span, args, kwargs, settings)
+                        output = await fn(*args, **kwargs)
+                        attach_output(span, output, settings)
+                        return output
+                finally:
+                    capture_active.reset(token)
+            return cast(F, async_wrapper)
+
+        @functools.wraps(fn)
+        def sync_wrapper(*args, **kwargs):
+            settings = get_config()
+            token = capture_active.set(True)
+            try:
+                tracer = otel_trace.get_tracer("elinaobs.sdk", "0.1.0")
+                with tracer.start_as_current_span(
+                    label, attributes={"elinaobs.observation.type": as_type}
+                ) as span:
+                    attach_input(span, args, kwargs, settings)
+                    output = fn(*args, **kwargs)
+                    attach_output(span, output, settings)
+                    return output
+            finally:
+                capture_active.reset(token)
+        return cast(F, sync_wrapper)
+
+    if func is not None:
+        return decorate(func)
+    return decorate

elinaobs-0.1.0/src/elinaobs/processing.py

@@ -0,0 +1,57 @@
+"""Selectively forward spans created inside @trace scope to an OTel processor."""
+from __future__ import annotations
+
+from threading import Lock
+
+from opentelemetry.sdk.trace import SpanProcessor
+
+from .context import capture_active
+
+
+class ScopedSpanProcessor(SpanProcessor):
+    """Keep our exporter from sending unrelated global OTel spans.
+
+    on_start runs synchronously while the calling ContextVar is available.
+    on_end may run after the capture scope has exited, so eligibility is
+    remembered by the pair (trace_id, span_id), not re-checked on end.
+    """
+
+    def __init__(self, downstream: SpanProcessor) -> None:
+        self._downstream = downstream
+        self._eligible: set[tuple[int, int]] = set()
+        self._lock = Lock()
+        self.ended_spans = 0
+        self.flushed_spans = 0
+
+    @staticmethod
+    def _key(span) -> tuple[int, int]:
+        ctx = span.get_span_context()
+        return (ctx.trace_id, ctx.span_id)
+
+    def on_start(self, span, parent_context=None) -> None:
+        if not capture_active.get():
+            return
+        key = self._key(span)
+        with self._lock:
+            self._eligible.add(key)
+        self._downstream.on_start(span, parent_context=parent_context)
+
+    def on_end(self, span) -> None:
+        key = self._key(span)
+        with self._lock:
+            if key not in self._eligible:
+                return
+            self._eligible.remove(key)
+            if span.context.trace_flags.sampled:
+                self.ended_spans += 1
+            self._downstream.on_end(span)
+
+    def force_flush(self, timeout_millis: int = 30000) -> bool:
+        with self._lock:
+            result = self._downstream.force_flush(timeout_millis=timeout_millis)
+            if result:
+                self.flushed_spans = self.ended_spans
+            return result
+
+    def shutdown(self) -> None:
+        self._downstream.shutdown()