Add OTLP trace ingestion MVP

Author: abidlabs

docs/source/_toctree.yml

@@ -29,6 +29,8 @@
     title: API and MCP Server
   - local: alerts
     title: Alerts
+  - local: otel_tracing
+    title: OpenTelemetry Traces
   - local: ml_agents
     title: ML Agents
   - local: environment_variables

docs/source/otel_tracing.md

@@ -0,0 +1,90 @@
+# OpenTelemetry Traces
+
+Trackio can receive OpenTelemetry trace data over OTLP/HTTP and show it in the
+dashboard's **Traces** tab. This is useful for agent and LLM frameworks that
+already emit OpenTelemetry or OpenInference spans, such as smolagents through
+`openinference-instrumentation-smolagents`.
+
+This is a minimal v1 receiver:
+
+- supported endpoint: `POST /otel/v1/traces`
+- supported encoding: OTLP protobuf (`application/x-protobuf`)
+- supported signal: traces
+- storage: each incoming span is converted to a `trackio.Trace` log entry
+
+## Start Trackio
+
+Launch a writable Trackio dashboard:
+
+```bash
+trackio show
+```
+
+Use the write-access URL or token printed by the server. For a local server,
+OTLP requests must include the same write token as normal remote logging.
+
+## Configure an OTLP Exporter
+
+Point your OpenTelemetry exporter at Trackio:
+
+```bash
+export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="http://localhost:7860/otel/v1/traces"
+export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL="http/protobuf"
+export OTEL_EXPORTER_OTLP_TRACES_HEADERS="x-trackio-write-token=<write-token>"
+```
+
+Set the Trackio project and run using OpenTelemetry resource attributes:
+
+```python
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+
+provider = TracerProvider(
+    resource=Resource(
+        {
+            "trackio.project": "my-project",
+            "trackio.run": "agent-run",
+            "service.name": "smolagents",
+        }
+    )
+)
+```
+
+If `trackio.project` is not set, Trackio uses the `project` query parameter if
+present, then falls back to `otel-traces`. If `trackio.run` is not set, Trackio
+uses `service.name`, then falls back to `otel`.
+
+## Example: smolagents with OpenInference
+
+```bash
+pip install smolagents opentelemetry-sdk opentelemetry-exporter-otlp-proto-http openinference-instrumentation-smolagents
+```
+
+```python
+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 openinference.instrumentation.smolagents import SmolagentsInstrumentor
+
+provider = TracerProvider(
+    resource=Resource(
+        {
+            "trackio.project": "agent-debugging",
+            "trackio.run": "smolagents",
+            "service.name": "smolagents",
+        }
+    )
+)
+provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
+SmolagentsInstrumentor().instrument(tracer_provider=provider)
+
+# Run your smolagents application normally. Spans will appear in Trackio.
+```
+
+## Notes
+
+Trackio preserves the raw span attributes in trace metadata and maps common
+OpenInference fields such as `input.value`, `output.value`, and indexed
+`llm.input_messages.*` / `llm.output_messages.*` attributes into conversational
+messages for the Traces tab.

pyproject.toml

@@ -21,6 +21,7 @@ dependencies = [
     "numpy<3.0.0",
     "pillow<13.0.0",
     "orjson>=3.0,<4.0.0",
+    "opentelemetry-proto>=1.25.0,<2.0.0",
     "tomli>=2.0.0; python_version < '3.11'",
 ]
 classifiers = [

tests/unit/test_otel_ingest.py

@@ -0,0 +1,92 @@
+from opentelemetry.proto.collector.trace.v1.trace_service_pb2 import (
+    ExportTraceServiceRequest,
+)
+from opentelemetry.proto.common.v1.common_pb2 import AnyValue, KeyValue
+from opentelemetry.proto.resource.v1.resource_pb2 import Resource
+from opentelemetry.proto.trace.v1.trace_pb2 import ResourceSpans, ScopeSpans, Span
+from starlette.testclient import TestClient
+
+from trackio.otel import ingest_otlp_trace_bytes
+from trackio.server import build_starlette_app_only
+from trackio.sqlite_storage import SQLiteStorage
+
+
+def _kv(key, value):
+    any_value = AnyValue()
+    if isinstance(value, bool):
+        any_value.bool_value = value
+    elif isinstance(value, int):
+        any_value.int_value = value
+    elif isinstance(value, float):
+        any_value.double_value = value
+    else:
+        any_value.string_value = value
+    return KeyValue(key=key, value=any_value)
+
+
+def _request_bytes():
+    span = Span(
+        trace_id=bytes.fromhex("0" * 31 + "1"),
+        span_id=bytes.fromhex("0" * 15 + "2"),
+        name="agent run",
+        kind=Span.SPAN_KIND_INTERNAL,
+        start_time_unix_nano=1_700_000_000_000_000_000,
+        end_time_unix_nano=1_700_000_001_000_000_000,
+        attributes=[
+            _kv("input.value", "hello"),
+            _kv("output.value", "world"),
+            _kv("openinference.span.kind", "agent"),
+        ],
+    )
+    resource_spans = ResourceSpans(
+        resource=Resource(
+            attributes=[
+                _kv("trackio.project", "otel-project"),
+                _kv("service.name", "smolagents"),
+                _kv("service.instance.id", "service-1"),
+            ]
+        ),
+        scope_spans=[ScopeSpans(spans=[span])],
+    )
+    return ExportTraceServiceRequest(resource_spans=[resource_spans]).SerializeToString()
+
+
+def test_ingest_otlp_trace_bytes_logs_trackio_trace(temp_dir):
+    result = ingest_otlp_trace_bytes(_request_bytes())
+
+    assert result["accepted_spans"] == 1
+    traces = SQLiteStorage.get_traces(
+        "otel-project", run="smolagents", run_id="service-1"
+    )
+    assert len(traces) == 1
+    assert traces[0]["run"] == "smolagents"
+    assert traces[0]["messages"] == [
+        {"role": "user", "content": "hello"},
+        {"role": "assistant", "content": "world"},
+    ]
+    assert traces[0]["metadata"]["source"] == "opentelemetry"
+    assert traces[0]["metadata"]["attributes"]["openinference.span.kind"] == "agent"
+
+
+def test_otel_route_requires_write_token_and_accepts_protobuf(temp_dir):
+    app, write_token = build_starlette_app_only()
+    client = TestClient(app)
+
+    unauthorized = client.post("/otel/v1/traces", content=_request_bytes())
+    assert unauthorized.status_code == 400
+
+    response = client.post(
+        "/otel/v1/traces",
+        content=_request_bytes(),
+        headers={
+            "content-type": "application/x-protobuf",
+            "x-trackio-write-token": write_token,
+        },
+    )
+
+    assert response.status_code == 200
+    assert response.headers["content-type"].startswith("application/x-protobuf")
+    assert (
+        len(SQLiteStorage.get_traces("otel-project", run="smolagents", run_id="service-1"))
+        == 1
+    )