Gate LangSmith-specific attributes behind tracing_langsmith_compat

Add tracing_langsmith_compat config option (default: false) that:
- Adds langsmith.span.kind attribute to spans
- Adds input.value/output.value for LangSmith panels
- Auto-sets tracing_metadata_prefix to 'langsmith.metadata'

Standard gen_ai.* attributes are always emitted regardless of this
setting. This allows users of other OTel backends to avoid the
LangSmith-specific noise while LangSmith users get full integration.

Also replaces the made-up gen_ai.prompt/gen_ai.completion fallback
attributes with proper gen_ai.tool.input/gen_ai.tool.output for
tool spans.

Author: pcomans

docs/_advanced/observability.md

@@ -77,11 +77,13 @@ RubyLLM.configure do |config|
   config.tracing_enabled = true
 
   # Log prompt/completion content (default: false)
-  # Enable for full LangSmith functionality
   config.tracing_log_content = true
 
   # Max content length before truncation (default: 10000)
   config.tracing_max_content_length = 5000
+  
+  # Enable LangSmith-specific span attributes (default: false)
+  config.tracing_langsmith_compat = true
 end
 ```
 
@@ -106,11 +108,13 @@ chat = RubyLLM.chat
 chat.ask("Hello!")
 ```
 
-Metadata appears as `metadata.*` attributes by default. For LangSmith's metadata panel, set:
+Metadata appears as `metadata.*` attributes by default. When `tracing_langsmith_compat` is enabled, metadata uses the `langsmith.metadata.*` prefix for proper LangSmith panel integration.
+
+You can also set a custom prefix:
 
 ```ruby
 RubyLLM.configure do |config|
-  config.tracing_metadata_prefix = 'langsmith.metadata'
+  config.tracing_metadata_prefix = 'app.metadata'
 end
 ```
 
@@ -127,7 +131,7 @@ LangSmith is LangChain's observability platform with specialized LLM debugging f
 RubyLLM.configure do |config|
   config.tracing_enabled = true
   config.tracing_log_content = true
-  config.tracing_metadata_prefix = 'langsmith.metadata'
+  config.tracing_langsmith_compat = true  # Adds LangSmith-specific span attributes
 end
 ```
 
@@ -153,6 +157,11 @@ end
 
 LangSmith uses the `Langsmith-Project` header (not `service_name`) to organize traces.
 
+When `tracing_langsmith_compat = true`, RubyLLM adds these additional attributes for LangSmith integration:
+- `langsmith.span.kind` - Identifies span type (LLM, TOOL)
+- `input.value` / `output.value` - Populates LangSmith's Input/Output panels
+- `langsmith.metadata.*` - Custom metadata appears in LangSmith's metadata panel
+
 ### Other Backends
 
 RubyLLM works with any OpenTelemetry-compatible backend. Configure the `opentelemetry-exporter-otlp` gem to send traces to your platform of choice.

lib/ruby_llm/chat.rb

@@ -159,6 +159,8 @@ def complete_without_instrumentation(&)
     end
 
     def complete_with_span(span, &)
+      langsmith = @config.tracing_langsmith_compat
+
       # Set request attributes
       if span.recording?
         span.add_attributes(
@@ -167,7 +169,8 @@ def complete_with_span(span, &)
             provider: @provider.slug,
             session_id: @session_id,
             temperature: @temperature,
-            metadata: @metadata
+            metadata: @metadata,
+            langsmith_compat: langsmith
           )
         )
 
@@ -176,7 +179,8 @@ def complete_with_span(span, &)
           span.add_attributes(
             Instrumentation::SpanBuilder.build_message_attributes(
               messages,
-              max_length: @config.tracing_max_content_length
+              max_length: @config.tracing_max_content_length,
+              langsmith_compat: langsmith
             )
           )
         end
@@ -200,7 +204,8 @@ def complete_with_span(span, &)
           span.add_attributes(
             Instrumentation::SpanBuilder.build_completion_attributes(
               response,
-              max_length: @config.tracing_max_content_length
+              max_length: @config.tracing_max_content_length,
+              langsmith_compat: langsmith
             )
           )
         end
@@ -304,20 +309,23 @@ def execute_tool(tool_call)
     def execute_tool_with_span(tool_call, span)
       tool = tools[tool_call.name.to_sym]
       args = tool_call.arguments
+      langsmith = @config.tracing_langsmith_compat
 
       if span.recording?
         span.add_attributes(
           Instrumentation::SpanBuilder.build_tool_attributes(
             tool_call: tool_call,
-            session_id: @session_id
+            session_id: @session_id,
+            langsmith_compat: langsmith
           )
         )
 
         if @config.tracing_log_content
           span.add_attributes(
             Instrumentation::SpanBuilder.build_tool_input_attributes(
               tool_call: tool_call,
-              max_length: @config.tracing_max_content_length
+              max_length: @config.tracing_max_content_length,
+              langsmith_compat: langsmith
             )
           )
         end
@@ -329,7 +337,8 @@ def execute_tool_with_span(tool_call, span)
         span.add_attributes(
           Instrumentation::SpanBuilder.build_tool_output_attributes(
             result: result,
-            max_length: @config.tracing_max_content_length
+            max_length: @config.tracing_max_content_length,
+            langsmith_compat: langsmith
           )
         )
       end

lib/ruby_llm/configuration.rb

@@ -51,7 +51,8 @@ class Configuration
                   :tracing_enabled,
                   :tracing_log_content,
                   :tracing_max_content_length,
-                  :tracing_metadata_prefix
+                  :tracing_metadata_prefix,
+                  :tracing_langsmith_compat
 
     def initialize
       @request_timeout = 300
@@ -79,6 +80,13 @@ def initialize
       @tracing_log_content = false
       @tracing_max_content_length = 10_000
       @tracing_metadata_prefix = 'metadata'
+      @tracing_langsmith_compat = false
+    end
+
+    def tracing_langsmith_compat=(value)
+      @tracing_langsmith_compat = value
+      # Auto-set metadata prefix for LangSmith when enabling compat mode
+      @tracing_metadata_prefix = 'langsmith.metadata' if value
     end
 
     def instance_variables

lib/ruby_llm/instrumentation.rb

@@ -121,41 +121,44 @@ def describe_attachments(attachments)
           "[#{descriptions.join(', ')}]"
         end
 
-        def build_message_attributes(messages, max_length:)
+        def build_message_attributes(messages, max_length:, langsmith_compat: false)
           attrs = {}
           messages.each_with_index do |msg, idx|
             attrs["gen_ai.prompt.#{idx}.role"] = msg.role.to_s
             content = extract_content_text(msg.content)
             attrs["gen_ai.prompt.#{idx}.content"] = truncate_content(content, max_length)
           end
           # Set input.value for LangSmith Input panel (last user message)
-          last_user_msg = messages.reverse.find { |m| m.role.to_s == 'user' }
-          if last_user_msg
-            content = extract_content_text(last_user_msg.content)
-            attrs['input.value'] = truncate_content(content, max_length)
+          if langsmith_compat
+            last_user_msg = messages.reverse.find { |m| m.role.to_s == 'user' }
+            if last_user_msg
+              content = extract_content_text(last_user_msg.content)
+              attrs['input.value'] = truncate_content(content, max_length)
+            end
           end
           attrs
         end
 
-        def build_completion_attributes(message, max_length:)
+        def build_completion_attributes(message, max_length:, langsmith_compat: false)
           attrs = {}
           attrs['gen_ai.completion.0.role'] = message.role.to_s
           content = extract_content_text(message.content)
           truncated = truncate_content(content, max_length)
           attrs['gen_ai.completion.0.content'] = truncated
           # Set output.value for LangSmith Output panel
-          attrs['output.value'] = truncated
+          attrs['output.value'] = truncated if langsmith_compat
           attrs
         end
 
-        def build_request_attributes(model:, provider:, session_id:, temperature: nil, metadata: nil)
+        def build_request_attributes(model:, provider:, session_id:, temperature: nil, metadata: nil,
+                                     langsmith_compat: false)
           attrs = {
-            'langsmith.span.kind' => 'LLM',
             'gen_ai.system' => provider.to_s,
             'gen_ai.operation.name' => 'chat',
             'gen_ai.request.model' => model.id,
             'gen_ai.conversation.id' => session_id
           }
+          attrs['langsmith.span.kind'] = 'LLM' if langsmith_compat
           attrs['gen_ai.request.temperature'] = temperature if temperature
           build_metadata_attributes(attrs, metadata) if metadata
           attrs
@@ -188,33 +191,32 @@ def build_response_attributes(response)
           attrs
         end
 
-        def build_tool_attributes(tool_call:, session_id:)
-          {
-            'langsmith.span.kind' => 'TOOL',
+        def build_tool_attributes(tool_call:, session_id:, langsmith_compat: false)
+          attrs = {
             'gen_ai.operation.name' => 'tool',
             'gen_ai.tool.name' => tool_call.name.to_s,
             'gen_ai.tool.call.id' => tool_call.id,
             'gen_ai.conversation.id' => session_id
           }
+          attrs['langsmith.span.kind'] = 'TOOL' if langsmith_compat
+          attrs
         end
 
-        def build_tool_input_attributes(tool_call:, max_length:)
+        def build_tool_input_attributes(tool_call:, max_length:, langsmith_compat: false)
           args = tool_call.arguments
-          input = args.is_a?(String) ? args : args.to_json
+          input = args.is_a?(String) ? args : JSON.generate(args)
           truncated = truncate_content(input, max_length)
-          {
-            'input.value' => truncated, # LangSmith Input panel
-            'gen_ai.prompt' => truncated # GenAI convention fallback
-          }
+          attrs = { 'gen_ai.tool.input' => truncated }
+          attrs['input.value'] = truncated if langsmith_compat
+          attrs
         end
 
-        def build_tool_output_attributes(result:, max_length:)
+        def build_tool_output_attributes(result:, max_length:, langsmith_compat: false)
           output = result.is_a?(String) ? result : result.to_s
           truncated = truncate_content(output, max_length)
-          {
-            'output.value' => truncated,     # LangSmith Output panel
-            'gen_ai.completion' => truncated # GenAI convention fallback
-          }
+          attrs = { 'gen_ai.tool.output' => truncated }
+          attrs['output.value'] = truncated if langsmith_compat
+          attrs
         end
       end
     end