KG-647. Update OpenTelemetry feature span attributes (#1359)

KG-647. Update OpenTelemetry feature span attributes according to semantic convention.

- Refactor span creation to use builder pattern;
- Add Strategy Span for tracking strategy-level execution;
- Improve test infrastructure with helper methods in TraceStructureTestBase;
- Update tests with new attributes checks.

Author: sdubov

agents/agents-features/agents-features-opentelemetry/README.md

@@ -21,9 +21,10 @@ Key OpenTelemetry concepts
 
 The OpenTelemetry feature in Koog automatically creates spans for various agent events, including:
 
-- Agent execution start and end
+- Agent creation and invocation
+- Strategy execution
 - Node execution
-- LLM calls
+- LLM calls (inference)
 - Tool calls
 
 ## Installation
@@ -177,25 +178,36 @@ The OpenTelemetry feature creates different types of spans for various operation
 2. **Invoke Agent Span**
     - Purpose: One concrete execution (run) of an agent.
     - Emitted: At the start of a run. Closed on successful finish or error.
-    - Parent: Parent: **Create Agent Span**. Children: **Node Execute Span** instances, and, indirectly, LLM and Tool spans within nodes.
-    - Useful for: Measuring run‑level timing, status, and grouping of all node, tool, and LLM activity for a run.
+    - Parent: **Create Agent Span**. Children: **Strategy Span** instances, and, indirectly, node, tool, and LLM spans within strategies.
+    - Useful for: Measuring run‑level timing, status, and grouping of all strategy, node, tool, and LLM activity for a run.
     - Key attributes:
         - `gen_ai.operation.name` = `invoke_agent`
         - `gen_ai.agent.id`
         - `gen_ai.conversation.id`
         - `gen_ai.system` (LLM provider)
         - `gen_ai.response.finish_reasons` (on error)
 
-3. **Node Execute Span**
+3. **Strategy Span**
+    - Purpose: Execution of a strategy within an agent run.
+    - Emitted: At the start of strategy execution. Closed when the strategy completes or errors.
+    - Parent: **Invoke Agent Span**. Children: **Node Execute Span** instances.
+    - Useful for: Tracking strategy-level execution, grouping all node executions within a strategy, and measuring strategy performance.
+    - Key attributes:
+        - `gen_ai.conversation.id`
+        - `koog.strategy.name`
+        - `koog.event.id`
+    - Note: This is a custom span type specific to Koog, not defined in the OpenTelemetry Semantic Conventions.
+
+4. **Node Execute Span**
     - Purpose: Execution of a single node in the agent strategy.
     - Emitted: Immediately before a node runs. Closed after the node completes or errors.
-    - Parent: **Invoke Agent Span**. Children: **Inference Spans** and **Execute Tool Span** instances created by the node.
+    - Parent: **Strategy Span**. Children: **Inference Spans** and **Execute Tool Span** instances created by the node.
     - Useful for: Understanding strategy flow and attributing LLM or tool work to a specific node.
     - Key attributes:
         - `gen_ai.conversation.id`
         - `koog.node.id`
 
-4. **Inference Span**
+5. **Inference Span**
     - Purpose: A single LLM call (prompt execution).
     - Emitted: Before the LLM is invoked. Closed after responses are received.
     - Parent: **Node Execute Span**.
@@ -216,7 +228,7 @@ The OpenTelemetry feature creates different types of spans for various operation
         - `gen_ai.usage.total_tokens` (when available)
         - `gen_ai.response.finish_reasons` (Stop, ToolCalls, etc.)
 
-5. **Execute Tool Span**
+6. **Execute Tool Span**
     - Purpose: Execution of a tool or function call triggered by the agent or LLM.
     - Emitted: When a tool is called. Closed after the tool returns a result or fails with an error during validation or execution.
     - Parent: **Node Execute Span**.

agents/agents-features/agents-features-opentelemetry/src/jvmMain/kotlin/ai/koog/agents/features/opentelemetry/attribute/KoogAttributes.kt

@@ -0,0 +1,77 @@
+package ai.koog.agents.features.opentelemetry.attribute
+
+import ai.koog.agents.utils.HiddenString
+
+/**
+ * An internal object that contains nested sealed interfaces and data classes for representing structured attributes
+ * used within the Koog framework. These attributes facilitate the creation and organization of hierarchical
+ * key-value pairs, which can be used for event tracking, strategy configuration, node identification,
+ * and subgraph definitions.
+ */
+internal object KoogAttributes {
+
+    sealed interface Koog : Attribute {
+        override val key: String
+            get() = "koog"
+
+        sealed interface Event : Koog {
+            override val key: String
+                get() = super.key.concatKey("event")
+
+            data class Id(private val id: String) : Event {
+                override val key: String = super.key.concatKey("id")
+                override val value: String = id
+            }
+        }
+
+        sealed interface Strategy : Koog {
+            override val key: String
+                get() = super.key.concatKey("strategy")
+
+            data class Name(private val name: String) : Strategy {
+                override val key: String = super.key.concatKey("name")
+                override val value: String = name
+            }
+        }
+
+        sealed interface Node : Koog {
+            override val key: String
+                get() = super.key.concatKey("node")
+
+            data class Id(private val id: String) : Node {
+                override val key: String = super.key.concatKey("id")
+                override val value: String = id
+            }
+
+            data class Input(private val input: String) : Node {
+                override val key: String = super.key.concatKey("input")
+                override val value: HiddenString = HiddenString(input)
+            }
+
+            data class Output(private val output: String) : Node {
+                override val key: String = super.key.concatKey("output")
+                override val value: HiddenString = HiddenString(output)
+            }
+        }
+
+        sealed interface Subgraph : Koog {
+            override val key: String
+                get() = super.key.concatKey("subgraph")
+
+            data class Id(private val id: String) : Subgraph {
+                override val key: String = super.key.concatKey("id")
+                override val value: String = id
+            }
+
+            data class Input(private val input: String) : Subgraph {
+                override val key: String = super.key.concatKey("input")
+                override val value: HiddenString = HiddenString(input)
+            }
+
+            data class Output(private val output: String) : Subgraph {
+                override val key: String = super.key.concatKey("output")
+                override val value: HiddenString = HiddenString(output)
+            }
+        }
+    }
+}

agents/agents-features/agents-features-opentelemetry/src/jvmMain/kotlin/ai/koog/agents/features/opentelemetry/attribute/SpanAttributes.kt

@@ -1,7 +1,19 @@
 package ai.koog.agents.features.opentelemetry.attribute
 
+import ai.koog.agents.core.tools.ToolDescriptor
 import ai.koog.agents.utils.HiddenString
+import ai.koog.prompt.llm.LLMProvider
 import ai.koog.prompt.llm.LLModel
+import ai.koog.prompt.message.ContentPart
+import ai.koog.prompt.message.Message
+import kotlinx.serialization.json.JsonArray
+import kotlinx.serialization.json.JsonArrayBuilder
+import kotlinx.serialization.json.JsonElement
+import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.JsonPrimitive
+import kotlinx.serialization.json.addJsonObject
+import kotlinx.serialization.json.buildJsonObject
+import kotlinx.serialization.json.putJsonArray
 
 /**
  * The class describe Attributes related to a Spans in GenAI system.
@@ -86,6 +98,18 @@ internal object SpanAttributes {
         }
     }
 
+    // gen_ai.provider
+
+    sealed interface Provider : GenAIAttribute {
+        override val key: String
+            get() = super.key.concatKey("provider")
+
+        data class Name(private val provider: LLMProvider) : Provider {
+            override val key: String = super.key.concatKey("name")
+            override val value: String = provider.id
+        }
+    }
+
     // gen_ai.conversation
     sealed interface Conversation : GenAIAttribute {
         override val key: String
@@ -110,6 +134,31 @@ internal object SpanAttributes {
         }
     }
 
+    // gen_ai.input
+    sealed interface Input : GenAIAttribute {
+        override val key: String
+            get() = super.key.concatKey("input")
+
+        // gen_ai.input.messages
+        data class Messages(private val messages: List<Message>) : Input {
+            override val key: String = super.key.concatKey("messages")
+            override val value: HiddenString = HiddenString(
+                JsonArray(
+                    messages.map { message ->
+                        buildJsonObject {
+                            put("role", JsonPrimitive(message.role.name))
+                            putJsonArray("parts") {
+                                message.parts.forEach { part ->
+                                    addContentPart(part, message)
+                                }
+                            }
+                        }
+                    }
+                ).toString()
+            )
+        }
+    }
+
     // gen_ai.output
     sealed interface Output : GenAIAttribute {
         override val key: String
@@ -121,6 +170,25 @@ internal object SpanAttributes {
             override val value: String = type.id
         }
 
+        // gen_ai.output.messages
+        data class Messages(private val messages: List<Message>) : Output {
+            override val key: String = super.key.concatKey("messages")
+            override val value: HiddenString = HiddenString(
+                JsonArray(
+                    messages.map { message ->
+                        buildJsonObject {
+                            put("role", JsonPrimitive(message.role.name))
+                            putJsonArray("parts") {
+                                message.parts.forEach { part ->
+                                    addContentPart(part, message)
+                                }
+                            }
+                        }
+                    }
+                ).toString()
+            )
+        }
+
         enum class OutputType(val id: String) {
             TEXT("text"),
             JSON("json"),
@@ -278,6 +346,18 @@ internal object SpanAttributes {
                 override val key: String = super.key.concatKey("id")
                 override val value: String = id
             }
+
+            // gen_ai.tool.call.arguments
+            data class Arguments(private val arguments: JsonObject) : Call {
+                override val key: String = super.key.concatKey("arguments")
+                override val value: HiddenString = HiddenString(arguments.toString())
+            }
+
+            // gen_ai.tool.call.result
+            data class Result(private val result: JsonElement) : Call {
+                override val key: String = super.key.concatKey("result")
+                override val value: HiddenString = HiddenString(result.toString())
+            }
         }
 
         // gen_ai.tool.description
@@ -292,16 +372,111 @@ internal object SpanAttributes {
             override val value: String = name
         }
 
-        // Custom tool attribute with tool arguments used for tool calls
-        data class InputValue(private val input: String) : Attribute {
-            override val key: String = "input.value"
-            override val value: HiddenString = HiddenString(input)
+        // gen_ai.tool.definitions
+        data class Definitions(private val tools: List<ToolDescriptor>) : Tool {
+            override val key: String = super.key.concatKey("definitions")
+            override val value: HiddenString = HiddenString(
+                JsonArray(
+                    tools.map { tool ->
+                        buildJsonObject {
+                            put("type", JsonPrimitive("function"))
+                            put("name", JsonPrimitive(tool.name))
+                            put("description", JsonPrimitive(tool.description))
+                        }
+                    }
+                ).toString()
+            )
         }
+    }
+
+    // gen_ai.system_instructions
+    data class SystemInstructions(private val messages: List<Message.System>) : GenAIAttribute {
+        override val key: String = "system_instructions"
+        override val value: HiddenString = run {
+            val jsonObjects = messages.flatMap { (parts, metaInfo) ->
+                parts.map { part ->
+                    JsonObject(
+                        mapOf(
+                            "type" to JsonPrimitive("text"),
+                            "content" to JsonPrimitive(part.text)
+                        )
+                    )
+                }
+            }
+
+            HiddenString(JsonArray(jsonObjects).toString())
+        }
+    }
+
+    //region Private Methods
+
+    private fun JsonArrayBuilder.addContentPart(part: ContentPart, message: Message) {
+        when (part) {
+            is ContentPart.Text -> {
+                when (message) {
+                    is Message.Tool.Call -> {
+                        addJsonObject {
+                            put("type", JsonPrimitive("tool_call"))
+                            message.id?.let { id -> put("id", JsonPrimitive(id)) }
+                            put("name", JsonPrimitive(message.tool))
+                            put("arguments", message.contentJson)
+                        }
+                    }
+
+                    is Message.Tool.Result -> {
+                        addJsonObject {
+                            put("type", JsonPrimitive("tool_call_response"))
+                            message.id?.let { id -> put("id", JsonPrimitive(id)) }
+                            put("result", JsonPrimitive(part.text))
+                        }
+                    }
+
+                    else -> {
+                        addJsonObject {
+                            put("type", JsonPrimitive("text"))
+                            put("content", JsonPrimitive(part.text))
+                        }
+                    }
+                }
+            }
 
-        // Custom tool attribute with tool execution results used for tool calls
-        data class OutputValue(private val output: String) : Attribute {
-            override val key: String = "output.value"
-            override val value: HiddenString = HiddenString(output)
+            is ContentPart.Image -> {
+                addJsonObject {
+                    put("type", JsonPrimitive("image"))
+                    put("format", JsonPrimitive(part.format))
+                    put("mimeType", JsonPrimitive(part.mimeType))
+                    part.fileName?.let { name -> put("fileName", JsonPrimitive(name)) }
+                }
+            }
+
+            is ContentPart.Video -> {
+                addJsonObject {
+                    put("type", JsonPrimitive("video"))
+                    put("format", JsonPrimitive(part.format))
+                    put("mimeType", JsonPrimitive(part.mimeType))
+                    part.fileName?.let { name -> put("fileName", JsonPrimitive(name)) }
+                }
+            }
+
+            is ContentPart.Audio -> {
+                addJsonObject {
+                    put("type", JsonPrimitive("audio"))
+                    put("format", JsonPrimitive(part.format))
+                    put("mimeType", JsonPrimitive(part.mimeType))
+                    part.fileName?.let { name -> put("fileName", JsonPrimitive(name)) }
+                }
+            }
+
+            is ContentPart.File -> {
+                addJsonObject {
+                    put("type", JsonPrimitive("file"))
+                    put("format", JsonPrimitive(part.format))
+                    put("mimeType", JsonPrimitive(part.mimeType))
+                    part.fileName?.let { name -> put("fileName", JsonPrimitive(name)) }
+                }
+            }
         }
     }
+
+    //endregion Private Methods
 }