SigNoz is an open-source, OpenTelemetry-native observability platform for your team and their AI agents. Get logs, metrics, and traces in one tool with features like APM, distributed tracing, log management, infra monitoring, etc. Combined with SigNoz MCP and a native AI teammate (in SigNoz Cloud) it helps you build more resilient apps.
TypeScript apmapplication-monitoringdistributed-tracinggogood-first-issuejaegerloglogsmetricsmonitoringnextjsobservabilityopen-sourceopentelemetryprometheusreactreactjsself-hostedtracingtypescript
feat: update ai attribute mapping (#13120)
Nityananda Gohainef67a47cf36a
diff --git a/docs/contributing/go/readme.md b/docs/contributing/go/readme.mdindex f926d5dd23..f142748076 100644--- a/docs/contributing/go/readme.md+++ b/docs/contributing/go/readme.md@@ -20,6 +20,7 @@ We **recommend** (almost enforce) reviewing these guides before contributing to- [Provider](provider.md) - Dependency injection and provider patterns- [Packages](packages.md) - Naming, layout, and conventions for `pkg/` packages- [Service](service.md) - Managed service lifecycle with `factory.Service`+- [Span Mapper](spanmapper.md) - Provenance of the shipped span mapper definitions and what is left unmapped- [SQL](sql.md) - Database and SQL patterns- [DSL Filtering to SQL](dslfilteringtosql.md) - Compiling the list filter DSL to relational-store WHERE clauses- [Types](types.md) - Domain types, request/response bodies, and storage rows in `pkg/types/`diff --git a/docs/contributing/go/spanmapper.md b/docs/contributing/go/spanmapper.mdnew file mode 100644index 0000000000..ec37b69392--- /dev/null+++ b/docs/contributing/go/spanmapper.md@@ -0,0 +1,62 @@+# Span Mapper++Where each source key in the shipped definitions under `pkg/modules/spanmapper/implspanmapper/fs/definitions/` comes from. A group runs on spans with an attribute key containing one of its condition substrings; sources are tried by priority and the first present wins; an existing target is never overwritten. Bump `version` on every change.++## gen_ai.llm++Condition: `model`, `llm.input_messages` (OpenInference sets `llm.model_name` from the response, so a failed call has no model key).++| Source | Emitted by |+|---|---|+| `llm.model_name`, `llm.provider`, `llm.system`, `llm.token_count.prompt`, `llm.token_count.completion`, `llm.token_count.prompt_details.cache_read`, `llm.token_count.prompt_details.cache_write`, `llm.token_count.completion_details.reasoning`, `llm.finish_reason`, `input.value`, `output.value`, `embedding.model_name`, `reranker.model_name`, `openinference.span.kind` | OpenInference |+| `llm.request.model`, `llm.response.model`, `llm.vendor`, `llm.usage.prompt_tokens`, `llm.usage.completion_tokens`, `llm.response.finish_reason`, `llm.response.stop_reason` | OpenLLMetry before the `gen_ai` rename |+| `gen_ai.system`, `gen_ai.usage.prompt_tokens`, `gen_ai.usage.completion_tokens`, `gen_ai.usage.cache_read_input_tokens`, `gen_ai.usage.cache_creation_input_tokens`, `gen_ai.usage.reasoning_tokens`, `gen_ai.prompt`, `gen_ai.completion`, `llm.request.type`, `traceloop.span.kind` | OpenLLMetry, LiteLLM, CrewAI, Mistral, LangSmith, OpenRouter gateway |+| `gen_ai.usage.cache_write.input_tokens` | OTel semconv draft spelling, Codex |+| `gen_ai.response.finish_reason`, `gen_ai.usage.prompt_token_details.cached_read_tokens`, `gen_ai.usage.completion_token_details.reasoning_tokens` | Bifrost gateway |+| `gen_ai.usage.input_tokens.cached` | OpenRouter gateway |+| `gen_ai.response.model`, last source for the request model | vLLM, which writes only the response model |+| `ai.model.id`, `ai.model.provider`, `ai.response.model`, `ai.response.finishReason`, `ai.prompt.messages`, `ai.response.text`, `ai.response.toolCalls`, `ai.usage.promptTokens`, `ai.usage.completionTokens` | Vercel AI SDK v4, Mastra |+| `ai.usage.inputTokens`, `ai.usage.outputTokens`, `ai.usage.cachedInputTokens`, `ai.usage.reasoningTokens` | Vercel AI SDK v5 |+| `langfuse.observation.model.name`, `langfuse.session.id` | Langfuse SDK v3 |+| `session.id` | OpenInference, Langfuse, Claude Code |+| `gen_ai.client.session_id` | opentelemetry-hooks runner (Cursor, Copilot, Claude Code hooks) |+| `model`, `input_tokens`, `output_tokens`, `cache_read_tokens`, `cache_creation_tokens` | Claude Code `claude_code.llm_request` spans ([docs](https://code.claude.com/docs/en/monitoring-usage#span-attributes)) |++## gen_ai.tool++Condition: `tool.name` (OpenInference), `ai.toolCall.` (Vercel, Mastra), `tool_call_args`, `tool_response` (Google ADK), `tool_use_id` (Claude Code, opentelemetry-hooks). Not `tool_name`: Codex records it on the model call span.++| Source | Emitted by |+|---|---|+| `tool.name`, `tool.id`, `tool.description`, `input.value`, `output.value`, `openinference.span.kind` | OpenInference |+| `ai.toolCall.name`, `ai.toolCall.id`, `ai.toolCall.args`, `ai.toolCall.result` | Vercel AI SDK, Mastra |+| `traceloop.entity.input`, `traceloop.entity.output`, `traceloop.span.kind`, `llm.request.type` | OpenLLMetry |+| `gcp.vertex.agent.tool_call_args`, `gcp.vertex.agent.tool_response` | Google ADK |+| `tool_name` | Claude Code `claude_code.tool` spans |+| `gen_ai.client.tool_name`, `gen_ai.client.tool_use_id` | opentelemetry-hooks runner (Cursor, Copilot, Claude Code hooks) |++## gen_ai.agent++Condition: `agent`.++| Source | Emitted by |+|---|---|+| `agent.name`, `agent.id`, `agent.description`, `openinference.span.kind` | OpenInference; `agent.id` and `agent.description` seen in no capture |+| `agent_name`, `final_result` | Pydantic AI |+| `crewai.agent.role`, `crewai.agent.id` | CrewAI |+| `traceloop.span.kind`, `llm.request.type` | OpenLLMetry |+| `agent_id` | Claude Code |++## Coverage of documented integrations++Every integration under [signoz.io/docs/llm-observability](https://signoz.io/docs/llm-observability/) was checked by looking at the instrumentation its page installs and the keys that instrumentation writes.++- Most pages install OpenInference or OpenLLMetry, or an SDK that writes OTel GenAI semconv itself (OpenAI, OpenAI Agents, Pydantic AI, AutoGen, Microsoft Agent Framework, Semantic Kernel, Copilot Chat, LiteLLM, OpenRouter). Their keys are the rows above.+- Three write their own keys and have their own rows: Claude Code and Claude Agent SDK, Cursor through opentelemetry-hooks, vLLM (response model only).+- Codex cannot be priced by renaming: `model` sits on the sampling function spans, `gen_ai.usage.*` on the child `handle_responses` span, `conversation.id` on the `codex.sampling` phase span, never together on one span.++To check a new integration, capture a trace and look for a model, usage, tool or messages key that no row above lists.++## Left unmapped on purpose++LiteLLM `llm.openai.messages` and `llm.openai.choices` (debug echo of the parent span's messages, Python repr). Total tokens and vendor cost keys (no target; the pricing processor owns cost). `ai.response.msToFirstChunk` and `gen_ai.latency.time_to_first_token` (milliseconds and seconds under one target).diff --git a/pkg/modules/spanmapper/implspanmapper/definitions.go b/pkg/modules/spanmapper/implspanmapper/definitions.goindex 7cb9556786..4c584866bd 100644--- a/pkg/modules/spanmapper/implspanmapper/definitions.go+++ b/pkg/modules/spanmapper/implspanmapper/definitions.go@@ -16,7 +16,8 @@ var definitionFiles embed.FS// NewSystemGroupRegistry parses every embedded definition. Definitions are// build-time assets validated by a test, so a failure here means the binary-// shipped broken JSON.+// shipped broken JSON. docs/contributing/go/spanmapper.md records where each+// source key comes from.func NewSystemGroupRegistry() (spantypes.SpanMapperGroupRegistry, error) {entries, err := fs.ReadDir(definitionFiles, definitionsRoot)if err != nil {diff --git a/pkg/modules/spanmapper/implspanmapper/fs/definitions/gen_ai.agent.json b/pkg/modules/spanmapper/implspanmapper/fs/definitions/gen_ai.agent.jsonindex 89b6095dc6..49b2a19669 100644--- a/pkg/modules/spanmapper/implspanmapper/fs/definitions/gen_ai.agent.json+++ b/pkg/modules/spanmapper/implspanmapper/fs/definitions/gen_ai.agent.json@@ -1,5 +1,5 @@{- "version": 2,+ "version": 3,"definition": {"name": "gen_ai.agent","condition": {@@ -17,6 +17,12 @@"fieldContext": "attribute","config": {"sources": [+ {+ "key": "crewai.agent.role",+ "context": "attribute",+ "operation": "copy",+ "priority": 30+ },{"key": "agent.name","context": "attribute",@@ -37,6 +43,18 @@"fieldContext": "attribute","config": {"sources": [+ {+ "key": "agent_id",+ "context": "attribute",+ "operation": "copy",+ "priority": 30+ },+ {+ "key": "crewai.agent.id",+ "context": "attribute",+ "operation": "copy",+ "priority": 20+ },{"key": "agent.id","context": "attribute",@@ -73,6 +91,32 @@}]}+ },+ {+ "name": "gen_ai.operation.name",+ "fieldContext": "attribute",+ "config": {+ "sources": [+ {+ "key": "openinference.span.kind",+ "context": "attribute",+ "operation": "copy",+ "priority": 30+ },+ {+ "key": "llm.request.type",+ "context": "attribute",+ "operation": "copy",+ "priority": 20+ },+ {+ "key": "traceloop.span.kind",+ "context": "attribute",+ "operation": "copy",+ "priority": 10+ }+ ]+ }}]}diff --git a/pkg/modules/spanmapper/implspanmapper/fs/definitions/gen_ai.llm.json b/pkg/modules/spanmapper/implspanmapper/fs/definitions/gen_ai.llm.jsonindex a8688d572a..3e5f46b117 100644--- a/pkg/modules/spanmapper/implspanmapper/fs/definitions/gen_ai.llm.json+++ b/pkg/modules/spanmapper/implspanmapper/fs/definitions/gen_ai.llm.json@@ -1,11 +1,14 @@{- "version": 3,+ "version": 4,"definition": {"name": "gen_ai.llm","condition": {"attributes": [{"value": "model"+ },+ {+ "value": "llm.input_messages"}],"resource": []@@ -17,6 +20,12 @@"fieldContext": "attribute","config": {"sources": [+ {+ "key": "reranker.model_name",+ "context": "attribute",+ "operation": "copy",+ "priority": 70+ },{"key": "llm.model_name","context": "attribute",@@ -52,6 +61,12 @@"context": "attribute","operation": "copy","priority": 10+ },+ {+ "key": "gen_ai.response.model",+ "context": "attribute",+ "operation": "copy",+ "priority": 5}]}@@ -114,11 +129,43 @@]}},+ {+ "name": "gen_ai.operation.name",+ "fieldContext": "attribute",+ "config": {+ "sources": [+ {+ "key": "openinference.span.kind",+ "context": "attribute",+ "operation": "copy",+ "priority": 30+ },+ {+ "key": "llm.request.type",+ "context": "attribute",+ "operation": "copy",+ "priority": 20+ },+ {+ "key": "traceloop.span.kind",+ "context": "attribute",+ "operation": "copy",+ "priority": 10+ }+ ]+ }+ },{"name": "gen_ai.usage.input_tokens","fieldContext": "attribute","config": {"sources": [+ {+ "key": "input_tokens",+ "context": "attribute",+ "operation": "copy",+ "priority": 60+ },{"key": "gen_ai.usage.prompt_tokens","context": "attribute",@@ -157,6 +204,12 @@"fieldContext": "attribute","config": {"sources": [+ {+ "key": "output_tokens",+ "context": "attribute",+ "operation": "copy",+ "priority": 60+ },{"key": "gen_ai.usage.completion_tokens","context": "attribute",@@ -195,6 +248,24 @@"fieldContext": "attribute","config": {"sources": [+ {+ "key": "cache_read_tokens",+ "context": "attribute",+ "operation": "copy",+ "priority": 60+ },+ {+ "key": "gen_ai.usage.input_tokens.cached",+ "context": "attribute",+ "operation": "copy",+ "priority": 50+ },+ {+ "key": "gen_ai.usage.prompt_token_details.cached_read_tokens",+ "context": "attribute",+ "operation": "copy",+ "priority": 40+ },{"key": "gen_ai.usage.cache_read_input_tokens","context": "attribute",@@ -221,6 +292,12 @@"fieldContext": "attribute","config": {"sources": [+ {+ "key": "cache_creation_tokens",+ "context": "attribute",+ "operation": "copy",+ "priority": 40+ },{"key": "gen_ai.usage.cache_write.input_tokens","context": "attribute",@@ -242,6 +319,38 @@]}},+ {+ "name": "gen_ai.usage.reasoning.output_tokens",+ "fieldContext": "attribute",+ "config": {+ "sources": [+ {+ "key": "gen_ai.usage.reasoning_tokens",+ "context": "attribute",+ "operation": "copy",+ "priority": 40+ },+ {+ "key": "gen_ai.usage.completion_token_details.reasoning_tokens",+ "context": "attribute",+ "operation": "copy",+ "priority": 30+ },+ {+ "key": "llm.token_count.completion_details.reasoning",+ "context": "attribute",+ "operation": "copy",+ "priority": 20+ },+ {+ "key": "ai.usage.reasoningTokens",+ "context": "attribute",+ "operation": "copy",+ "priority": 10+ }+ ]+ }+ },{"name": "gen_ai.input.messages","fieldContext": "attribute",@@ -305,6 +414,12 @@"fieldContext": "attribute","config": {"sources": [+ {+ "key": "gen_ai.client.session_id",+ "context": "attribute",+ "operation": "copy",+ "priority": 30+ },{"key": "session.id","context": "attribute",@@ -325,6 +440,30 @@"fieldContext": "attribute","config": {"sources": [+ {+ "key": "llm.finish_reason",+ "context": "attribute",+ "operation": "copy",+ "priority": 50+ },+ {+ "key": "llm.response.stop_reason",+ "context": "attribute",+ "operation": "copy",+ "priority": 40+ },+ {+ "key": "llm.response.finish_reason",+ "context": "attribute",+ "operation": "copy",+ "priority": 30+ },+ {+ "key": "gen_ai.response.finish_reason",+ "context": "attribute",+ "operation": "copy",+ "priority": 20+ },{"key": "ai.response.finishReason","context": "attribute",diff --git a/pkg/modules/spanmapper/implspanmapper/fs/definitions/gen_ai.tool.json b/pkg/modules/spanmapper/implspanmapper/fs/definitions/gen_ai.tool.jsonindex 3318f5a053..87841bdab3 100644--- a/pkg/modules/spanmapper/implspanmapper/fs/definitions/gen_ai.tool.json+++ b/pkg/modules/spanmapper/implspanmapper/fs/definitions/gen_ai.tool.json@@ -1,5 +1,5 @@{- "version": 2,+ "version": 3,"definition": {"name": "gen_ai.tool","condition": {@@ -15,6 +15,9 @@},{"value": "tool_response"+ },+ {+ "value": "tool_use_id"}],"resource": []@@ -26,6 +29,18 @@"fieldContext": "attribute","config": {"sources": [+ {+ "key": "gen_ai.client.tool_name",+ "context": "attribute",+ "operation": "copy",+ "priority": 40+ },+ {+ "key": "tool_name",+ "context": "attribute",+ "operation": "copy",+ "priority": 30+ },{"key": "tool.name","context": "attribute",@@ -46,6 +61,12 @@"fieldContext": "attribute","config": {"sources": [+ {+ "key": "gen_ai.client.tool_use_id",+ "context": "attribute",+ "operation": "copy",+ "priority": 30+ },{"key": "tool.id","context": "attribute",@@ -138,6 +159,32 @@}]}+ },+ {+ "name": "gen_ai.operation.name",+ "fieldContext": "attribute",+ "config": {+ "sources": [+ {+ "key": "openinference.span.kind",+ "context": "attribute",+ "operation": "copy",+ "priority": 30+ },+ {+ "key": "llm.request.type",+ "context": "attribute",+ "operation": "copy",+ "priority": 20+ },+ {+ "key": "traceloop.span.kind",+ "context": "attribute",+ "operation": "copy",+ "priority": 10+ }+ ]+ }}]}diff --git a/tests/integration/tests/spanmapper/02_default_groups.py b/tests/integration/tests/spanmapper/02_default_groups.pyindex 28fd158b31..7a443f0198 100644--- a/tests/integration/tests/spanmapper/02_default_groups.py+++ b/tests/integration/tests/spanmapper/02_default_groups.py@@ -41,7 +41,7 @@ def test_default_groups_are_seeded_and_shipped_items_are_toggle_only(assert groups[name]["version"] >= 1assert groups[name]["createdBy"] == "signoz"llm = groups["gen_ai.llm"]- assert llm["condition"]["attributes"] == [{"value": "model", "enabled": True, "origin": "system"}]+ assert llm["condition"]["attributes"] == [{"value": "model", "enabled": True, "origin": "system"}, {"value": "llm.input_messages", "enabled": True, "origin": "system"}]list_mappers = requests.get(signoz.self.host_configs["8080"].get(f"{GROUPS_PATH}/{llm['id']}/span_mappers"), timeout=10, headers=headers)assert list_mappers.status_code == HTTPStatus.OK@@ -130,6 +130,7 @@ def test_default_groups_are_seeded_and_shipped_items_are_toggle_only(llm_after = {g["name"]: g for g in list_groups.json()["data"]["items"]}["gen_ai.llm"]assert llm_after["condition"]["attributes"] == [{"value": "model", "enabled": False, "origin": "system"},+ {"value": "llm.input_messages", "enabled": True, "origin": "system"},{"value": "gen_ai.request.model", "enabled": True, "origin": "user"},]assert llm_after["origin"] == "system"