From c5f716bf57130bfe63200205876e694d6e8f5836 Mon Sep 17 00:00:00 2001 From: "fengduzhen.666" Date: Mon, 2 Nov 2026 14:56:28 +0800 Subject: [PATCH 1/2] feat(tracing): mark invocation spans as ERA roots --- docs/content/docs/framework/span-attributes.en.mdx | 2 ++ docs/content/docs/framework/span-attributes.mdx | 2 ++ tests/test_tracing.py | 3 +++ veadk/tracing/telemetry/exporters/inmemory_exporter.py | 1 + 4 files changed, 8 insertions(+) diff --git a/docs/content/docs/framework/span-attributes.en.mdx b/docs/content/docs/framework/span-attributes.en.mdx index 5c78db81f..525512b51 100644 --- a/docs/content/docs/framework/span-attributes.en.mdx +++ b/docs/content/docs/framework/span-attributes.en.mdx @@ -11,6 +11,8 @@ To align with the Google ADK instrumentation conventions, the instrumentation ti - [When calling the model](https://github.com/google/adk-python/blob/v1.17.0/src/google/adk/flows/llm_flows/base_llm_flow.py): Instrumented in BaseLlmFlow's `_call_llm_with_tracing` function, with the span named `call_llm` - [When calling a tool](https://github.com/google/adk-python/blob/v1.17.0/src/google/adk/flows/llm_flows/functions.py): Instrumented in BaseLlmFlow's `_execute_single_function_call_async` function, with the span named `execute_tool {tool.name}` +When VeADK OpenTelemetry tracing is enabled, the `invocation` span receives `era.span_type="root"` when it starts, identifying the VeADK invocation entrypoint. This marker is retained even when the span has an upstream parent and does not depend on a model response or input/output content collection. + At each point, a span with the corresponding name is created to record the details of that point. When a stage ends, the corresponding instrumentation function is called to record the information of that stage into the span: - Google ADK [instrumentation file](https://github.com/google/adk-python/blob/v1.17.0/src/google/adk/telemetry/tracing.py) diff --git a/docs/content/docs/framework/span-attributes.mdx b/docs/content/docs/framework/span-attributes.mdx index 4e840dbdb..14271b8e6 100644 --- a/docs/content/docs/framework/span-attributes.mdx +++ b/docs/content/docs/framework/span-attributes.mdx @@ -11,6 +11,8 @@ title: "埋点字段说明" - [调用模型时](https://github.com/google/adk-python/blob/v1.17.0/src/google/adk/flows/llm_flows/base_llm_flow.py)：在 BaseLlmFlow 的 `_call_llm_with_tracing` 函数中埋点，Span 名称为 `call_llm` - [调用工具时](https://github.com/google/adk-python/blob/v1.17.0/src/google/adk/flows/llm_flows/functions.py)：在 BaseLlmFlow 的 `_execute_single_function_call_async` 函数中埋点，Span 名称为 `execute_tool {tool.name}` +启用 VeADK OpenTelemetry Tracing 时，`invocation` Span 在创建时写入 `era.span_type="root"`，用于标识 VeADK 调用入口。即使存在上游父 Span，也会保留该标识；写入不依赖模型响应或输入输出内容采集。 + 在每个时机时，都会创建对应名字的 Span，用于记录该时机的详细信息。当某阶段结束时，会调用对应的打点函数，将该阶段的信息记录到 Span 中： - Google ADK [打点文件](https://github.com/google/adk-python/blob/v1.17.0/src/google/adk/telemetry/tracing.py) diff --git a/tests/test_tracing.py b/tests/test_tracing.py index 4ec0b2145..8daad0645 100644 --- a/tests/test_tracing.py +++ b/tests/test_tracing.py @@ -101,6 +101,7 @@ def test_local_cache_limits_preserve_cloud_spans_annotations_and_dumps( token = context_api.attach(context_api.Context()) try: with otel_tracer.start_as_current_span("invocation") as invocation: + assert invocation.attributes["era.span_type"] == "root" assert ( context_api.get_value("suppress_language_model_instrumentation") is True ) @@ -119,6 +120,8 @@ def test_local_cache_limits_preserve_cloud_spans_annotations_and_dumps( assert spans[2].attributes["gen_ai.output"] == payload assert spans[3].attributes["gen_ai.span.kind"] == "agent" assert spans[4].attributes["gen_ai.span.kind"] == "workflow" + assert spans[4].attributes["era.span_type"] == "root" + assert all("era.span_type" not in span.attributes for span in spans[:4]) assert spans[4].attributes["gen_ai.usage.total_tokens"] == 0 assert tracer.trace_id == format(invocation.context.trace_id, "032x") cache = tracer._inmemory_exporter._exporter diff --git a/veadk/tracing/telemetry/exporters/inmemory_exporter.py b/veadk/tracing/telemetry/exporters/inmemory_exporter.py index c787cfd83..c1262f000 100644 --- a/veadk/tracing/telemetry/exporters/inmemory_exporter.py +++ b/veadk/tracing/telemetry/exporters/inmemory_exporter.py @@ -199,6 +199,7 @@ def on_start(self, span, parent_context) -> None: """ annotate_request_start(span) if span.name.startswith("invocation"): + span.set_attribute("era.span_type", "root") span.set_attribute("gen_ai.operation.name", "chain") span.set_attribute("gen_ai.span.kind", "workflow") span.set_attribute("gen_ai.usage.total_tokens", 0) From 9d4d31bbcc68b43d9976b02828eae069572536a1 Mon Sep 17 00:00:00 2001 From: "fengduzhen.666" Date: Mon, 2 Nov 2026 15:18:50 +0800 Subject: [PATCH 2/2] docs: remove invocation root marker paragraphs --- docs/content/docs/framework/span-attributes.en.mdx | 2 -- docs/content/docs/framework/span-attributes.mdx | 2 -- 2 files changed, 4 deletions(-) diff --git a/docs/content/docs/framework/span-attributes.en.mdx b/docs/content/docs/framework/span-attributes.en.mdx index 525512b51..5c78db81f 100644 --- a/docs/content/docs/framework/span-attributes.en.mdx +++ b/docs/content/docs/framework/span-attributes.en.mdx @@ -11,8 +11,6 @@ To align with the Google ADK instrumentation conventions, the instrumentation ti - [When calling the model](https://github.com/google/adk-python/blob/v1.17.0/src/google/adk/flows/llm_flows/base_llm_flow.py): Instrumented in BaseLlmFlow's `_call_llm_with_tracing` function, with the span named `call_llm` - [When calling a tool](https://github.com/google/adk-python/blob/v1.17.0/src/google/adk/flows/llm_flows/functions.py): Instrumented in BaseLlmFlow's `_execute_single_function_call_async` function, with the span named `execute_tool {tool.name}` -When VeADK OpenTelemetry tracing is enabled, the `invocation` span receives `era.span_type="root"` when it starts, identifying the VeADK invocation entrypoint. This marker is retained even when the span has an upstream parent and does not depend on a model response or input/output content collection. - At each point, a span with the corresponding name is created to record the details of that point. When a stage ends, the corresponding instrumentation function is called to record the information of that stage into the span: - Google ADK [instrumentation file](https://github.com/google/adk-python/blob/v1.17.0/src/google/adk/telemetry/tracing.py) diff --git a/docs/content/docs/framework/span-attributes.mdx b/docs/content/docs/framework/span-attributes.mdx index 14271b8e6..4e840dbdb 100644 --- a/docs/content/docs/framework/span-attributes.mdx +++ b/docs/content/docs/framework/span-attributes.mdx @@ -11,8 +11,6 @@ title: "埋点字段说明" - [调用模型时](https://github.com/google/adk-python/blob/v1.17.0/src/google/adk/flows/llm_flows/base_llm_flow.py)：在 BaseLlmFlow 的 `_call_llm_with_tracing` 函数中埋点，Span 名称为 `call_llm` - [调用工具时](https://github.com/google/adk-python/blob/v1.17.0/src/google/adk/flows/llm_flows/functions.py)：在 BaseLlmFlow 的 `_execute_single_function_call_async` 函数中埋点，Span 名称为 `execute_tool {tool.name}` -启用 VeADK OpenTelemetry Tracing 时，`invocation` Span 在创建时写入 `era.span_type="root"`，用于标识 VeADK 调用入口。即使存在上游父 Span，也会保留该标识；写入不依赖模型响应或输入输出内容采集。 - 在每个时机时，都会创建对应名字的 Span，用于记录该时机的详细信息。当某阶段结束时，会调用对应的打点函数，将该阶段的信息记录到 Span 中： - Google ADK [打点文件](https://github.com/google/adk-python/blob/v1.17.0/src/google/adk/telemetry/tracing.py)