From e34a8926cf8dc35495532617641dd13a47f7f9eb Mon Sep 17 00:00:00 2001 From: Pablo Pardo Garcia Date: Tue, 17 Nov 2026 12:17:04 +0100 Subject: [PATCH 1/2] fix: retriever spans use OpenTelemetry span kind INTERNAL Re-pin the vendored rius-semconv constants to v1.13.1, which maps the RETRIEVER taxonomy kind to the INTERNAL span kind instead of CLIENT, matching the GenAI conventions' internal retrieval span. The SDK reads the kind from the generated table, so every RETRIEVER span (@observe, start_span, start_as_current_span) follows; the tests that asserted CLIENT now assert INTERNAL. --- src/rius/_semconv_generated.py | 16 +++++++++------- tests/test_observe.py | 4 ++-- tests/test_semconv.py | 7 ++++--- tests/test_spans.py | 2 +- 4 files changed, 16 insertions(+), 13 deletions(-) diff --git a/src/rius/_semconv_generated.py b/src/rius/_semconv_generated.py index 0db58a3..814fe8f 100644 --- a/src/rius/_semconv_generated.py +++ b/src/rius/_semconv_generated.py @@ -1,4 +1,4 @@ -# Vendored from rius-semconv v1.13.0 out/python/_semconv_generated.py by +# Vendored from rius-semconv v1.13.1 out/python/_semconv_generated.py by # scripts/sync-semconv.sh. Do not edit: change the registry in rius-semconv. """Rius semantic conventions: the constants and tables, generated. @@ -1604,11 +1604,13 @@ class SpanKind(str, Enum): # SpanKind (our taxonomy ATTRIBUTE) -> the OpenTelemetry SpanKind FIELD, set # centrally at span creation. The GenAI conventions decide the field per -# operation: inference, embeddings and retrieval call out of the process -# (CLIENT); execute_tool is INTERNAL; invoke_agent is CLIENT only for a hosted -# agent. Hence: -# - LLM / EMBEDDING / RETRIEVER / RERANKER -> CLIENT: a remote model or -# index is called. +# operation: inference and embeddings call out of the process (CLIENT); +# retrieval and execute_tool are INTERNAL; invoke_agent is CLIENT only for a +# hosted agent. Hence: +# - LLM / EMBEDDING / RERANKER -> CLIENT: a remote model is called. +# - RETRIEVER -> INTERNAL: the conventions deprecated their client retrieval +# span for an internal one, since a retriever wraps embedding, database, +# HTTP or rerank calls that have CLIENT spans of their own. # - TOOL -> INTERNAL: a bare TOOL span is an in-process function, and the # execute-tool convention says INTERNAL. The MCP wrapper overrides this to # CLIENT at its own call site because a tools/call crosses a process @@ -1625,7 +1627,7 @@ class SpanKind(str, Enum): _OTEL_KIND_BY_KIND: dict[SpanKind, str] = { SpanKind.LLM: "CLIENT", SpanKind.EMBEDDING: "CLIENT", - SpanKind.RETRIEVER: "CLIENT", + SpanKind.RETRIEVER: "INTERNAL", SpanKind.RERANKER: "CLIENT", SpanKind.TOOL: "INTERNAL", SpanKind.AGENT: "INTERNAL", diff --git a/tests/test_observe.py b/tests/test_observe.py index f0cdca4..e65f9fa 100644 --- a/tests/test_observe.py +++ b/tests/test_observe.py @@ -439,7 +439,7 @@ def test_non_tool_kind_has_no_gen_ai_tool_name(exported_spans: InMemorySpanExpor [ (SpanKind.LLM, OtelSpanKind.CLIENT), (SpanKind.EMBEDDING, OtelSpanKind.CLIENT), - (SpanKind.RETRIEVER, OtelSpanKind.CLIENT), + (SpanKind.RETRIEVER, OtelSpanKind.INTERNAL), (SpanKind.TOOL, OtelSpanKind.INTERNAL), (SpanKind.AGENT, OtelSpanKind.INTERNAL), (SpanKind.CHAIN, OtelSpanKind.INTERNAL), @@ -466,7 +466,7 @@ async def search() -> None: pass asyncio.run(search()) - assert exported_spans.get_finished_spans()[0].kind is OtelSpanKind.CLIENT + assert exported_spans.get_finished_spans()[0].kind is OtelSpanKind.INTERNAL def test_otel_kind_field_follows_taxonomy_on_generator_paths( diff --git a/tests/test_semconv.py b/tests/test_semconv.py index 1f9773a..fca7644 100644 --- a/tests/test_semconv.py +++ b/tests/test_semconv.py @@ -44,7 +44,7 @@ def test_set_span_kind_without_operation(exported_spans: InMemorySpanExporter) - [ (SpanKind.LLM, OtelSpanKind.CLIENT), (SpanKind.EMBEDDING, OtelSpanKind.CLIENT), - (SpanKind.RETRIEVER, OtelSpanKind.CLIENT), + (SpanKind.RETRIEVER, OtelSpanKind.INTERNAL), (SpanKind.RERANKER, OtelSpanKind.CLIENT), (SpanKind.TOOL, OtelSpanKind.INTERNAL), (SpanKind.AGENT, OtelSpanKind.INTERNAL), @@ -54,8 +54,9 @@ def test_set_span_kind_without_operation(exported_spans: InMemorySpanExporter) - def test_otel_span_kind_follows_the_genai_conventions( kind: SpanKind, expected: OtelSpanKind ) -> None: - """Inference, embeddings and retrieval cross a process boundary (CLIENT); - an in-process tool, agent or step does not (INTERNAL).""" + """Inference and embeddings cross a process boundary (CLIENT); retrieval, + an in-process tool, agent or step does not (INTERNAL). A retriever wraps + the embedding, database or HTTP calls that carry CLIENT spans of their own.""" assert otel_span_kind(kind) is expected diff --git a/tests/test_spans.py b/tests/test_spans.py index 4b3fdb2..8e266fb 100644 --- a/tests/test_spans.py +++ b/tests/test_spans.py @@ -280,7 +280,7 @@ def test_retrieved_documents_are_recorded_as_json(exported_spans: InMemorySpanEx [ (SpanKind.LLM, OtelSpanKind.CLIENT), (SpanKind.EMBEDDING, OtelSpanKind.CLIENT), - (SpanKind.RETRIEVER, OtelSpanKind.CLIENT), + (SpanKind.RETRIEVER, OtelSpanKind.INTERNAL), (SpanKind.TOOL, OtelSpanKind.INTERNAL), (SpanKind.AGENT, OtelSpanKind.INTERNAL), (SpanKind.CHAIN, OtelSpanKind.INTERNAL), From 18007104e5b02712697f706f86f5ff3eabb4f291 Mon Sep 17 00:00:00 2001 From: Pablo Pardo Garcia Date: Tue, 17 Nov 2026 12:22:22 +0100 Subject: [PATCH 2/2] test: check the async span-kind path with a CLIENT kind --- tests/test_observe.py | 10 ++++++---- tests/test_semconv.py | 4 ++-- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/tests/test_observe.py b/tests/test_observe.py index e65f9fa..fe3cd92 100644 --- a/tests/test_observe.py +++ b/tests/test_observe.py @@ -461,12 +461,14 @@ def step() -> None: def test_otel_kind_field_follows_taxonomy_on_async_path( exported_spans: InMemorySpanExporter, ) -> None: - @observe(kind=SpanKind.RETRIEVER) - async def search() -> None: + # A CLIENT kind, because INTERNAL is OTel's default and would pass even if + # the async path ignored the taxonomy. + @observe(kind=SpanKind.EMBEDDING) + async def embed() -> None: pass - asyncio.run(search()) - assert exported_spans.get_finished_spans()[0].kind is OtelSpanKind.INTERNAL + asyncio.run(embed()) + assert exported_spans.get_finished_spans()[0].kind is OtelSpanKind.CLIENT def test_otel_kind_field_follows_taxonomy_on_generator_paths( diff --git a/tests/test_semconv.py b/tests/test_semconv.py index fca7644..e0f9103 100644 --- a/tests/test_semconv.py +++ b/tests/test_semconv.py @@ -54,8 +54,8 @@ def test_set_span_kind_without_operation(exported_spans: InMemorySpanExporter) - def test_otel_span_kind_follows_the_genai_conventions( kind: SpanKind, expected: OtelSpanKind ) -> None: - """Inference and embeddings cross a process boundary (CLIENT); retrieval, - an in-process tool, agent or step does not (INTERNAL). A retriever wraps + """Inference and embeddings cross a process boundary (CLIENT); retrieval + and an in-process tool, agent or step do not (INTERNAL). A retriever wraps the embedding, database or HTTP calls that carry CLIENT spans of their own.""" assert otel_span_kind(kind) is expected