Add OTLP trace ingestion MVP

Author: abidlabs

.changeset/thick-boats-win.md

@@ -0,0 +1,5 @@
+---
+"trackio": minor
+---
+
+feat:Add OTLP trace ingestion MVP

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,93 @@
+# 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.
+
+Runnable examples are available in `examples/otel-basic-mvp.py` and
+`examples/otel-smolagents-integration.py`.

examples/otel-basic-mvp.py

@@ -0,0 +1,61 @@
+"""Minimal OpenTelemetry -> Trackio example.
+
+Run a writable Trackio dashboard first:
+
+    trackio show
+
+Then set the write token printed by Trackio and run this example:
+
+    export TRACKIO_WRITE_TOKEN=<write-token>
+    python examples/otel-basic-mvp.py
+
+The span appears in the Trackio dashboard's Traces tab.
+"""
+
+import os
+
+from opentelemetry import trace
+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
+
+
+def main() -> None:
+    endpoint = os.getenv(
+        "TRACKIO_OTEL_ENDPOINT",
+        "http://localhost:7860/otel/v1/traces",
+    )
+    write_token = os.getenv("TRACKIO_WRITE_TOKEN")
+    headers = {"x-trackio-write-token": write_token} if write_token else {}
+
+    provider = TracerProvider(
+        resource=Resource(
+            {
+                "trackio.project": os.getenv("TRACKIO_PROJECT", "otel-basic-mvp"),
+                "trackio.run": os.getenv("TRACKIO_RUN", "manual-span"),
+                "service.name": "trackio-otel-basic-example",
+            }
+        )
+    )
+    provider.add_span_processor(
+        BatchSpanProcessor(OTLPSpanExporter(endpoint=endpoint, headers=headers))
+    )
+    trace.set_tracer_provider(provider)
+
+    tracer = trace.get_tracer("trackio.examples.otel-basic-mvp")
+    with tracer.start_as_current_span("manual llm call") as span:
+        span.set_attribute("openinference.span.kind", "llm")
+        span.set_attribute("input.value", "Say hello to Trackio.")
+        span.set_attribute("output.value", "Hello from OpenTelemetry.")
+        span.set_attribute("llm.model_name", "example-model")
+        span.set_attribute("llm.token_count.prompt", 5)
+        span.set_attribute("llm.token_count.completion", 4)
+
+    provider.force_flush()
+    provider.shutdown()
+    print(f"Sent one OTLP span to {endpoint}")
+
+
+if __name__ == "__main__":
+    main()

examples/otel-smolagents-integration.py

@@ -0,0 +1,80 @@
+"""smolagents + OpenInference + OpenTelemetry -> Trackio example.
+
+Run a writable Trackio dashboard first:
+
+    trackio show
+
+Then set the write token printed by Trackio and run this example:
+
+    pip install smolagents openinference-instrumentation-smolagents \
+        opentelemetry-sdk opentelemetry-exporter-otlp-proto-http
+    export TRACKIO_WRITE_TOKEN=<write-token>
+    python examples/otel-smolagents-integration.py
+
+This example uses a local dummy smolagents model, so it does not require an LLM
+API key. The agent run appears in the Trackio dashboard's Traces tab.
+
+Note: smolagents currently declares a narrower huggingface-hub dependency than
+Trackio. If installing smolagents downgrades huggingface-hub in a Trackio dev
+environment, reinstall Trackio's supported range with:
+
+    pip install "huggingface-hub>=1.10.0,<2"
+"""
+
+import os
+
+from openinference.instrumentation.smolagents import SmolagentsInstrumentor
+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 smolagents import CodeAgent, Model
+from smolagents.models import ChatMessage, MessageRole
+
+
+class DemoModel(Model):
+    def generate(self, messages, **kwargs):
+        return ChatMessage(
+            role=MessageRole.ASSISTANT,
+            content="```python\nfinal_answer('Trackio received this smolagents trace')\n```",
+        )
+
+
+def main() -> None:
+    endpoint = os.getenv(
+        "TRACKIO_OTEL_ENDPOINT",
+        "http://localhost:7860/otel/v1/traces",
+    )
+    write_token = os.getenv("TRACKIO_WRITE_TOKEN")
+    headers = {"x-trackio-write-token": write_token} if write_token else {}
+
+    provider = TracerProvider(
+        resource=Resource(
+            {
+                "trackio.project": os.getenv("TRACKIO_PROJECT", "otel-smolagents"),
+                "trackio.run": os.getenv("TRACKIO_RUN", "dummy-agent"),
+                "service.name": "smolagents",
+            }
+        )
+    )
+    provider.add_span_processor(
+        BatchSpanProcessor(OTLPSpanExporter(endpoint=endpoint, headers=headers))
+    )
+
+    SmolagentsInstrumentor().instrument(tracer_provider=provider)
+
+    agent = CodeAgent(
+        tools=[],
+        model=DemoModel(model_id="trackio-demo-model"),
+        max_steps=1,
+    )
+    result = agent.run("Return a short confirmation that Trackio tracing works.")
+
+    provider.force_flush()
+    provider.shutdown()
+    print(f"Agent result: {result}")
+    print(f"Sent smolagents OpenInference spans to {endpoint}")
+
+
+if __name__ == "__main__":
+    main()

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
+    )