anthropic 1.78.0 → 1.79.0

data/lib/anthropic/helpers/tracing/streamed_message.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+module Anthropic
+  module Helpers
+    module Tracing
+      class << self
+        # A failure to record must not fail the application's code, so an error raised in the block
+        # is logged, and the value is then `nil`.
+        #
+        # @param what [String]
+        def recording(what)
+          yield
+        rescue StandardError => e
+          OpenTelemetry.logger.debug("anthropic: could not record #{what} on its span: #{e.class}")
+          nil
+        end
+
+        # The enumerator that reads `events` and records the Message they carry on `span`, and what
+        # it has recorded so far.
+        #
+        # @param span [OpenTelemetry::Trace::Span]
+        # @param events [Enumerable<Anthropic::Internal::Type::BaseModel>] the events of the stream
+        # @param params [Hash{Symbol=>Object}] the request's body
+        # @param start_time [Float] when the API call started, on the monotonic clock
+        # @param content [Boolean] whether the span has the `content` attributes
+        # @param content_limit [Integer] the most bytes the `content` attributes hold
+        #
+        # @return [Array(Enumerator, Anthropic::Helpers::Tracing::StreamedMessage)]
+        def follow_streamed_message(span, events, params:, start_time:, content:, content_limit: CONTENT_LIMIT)
+          tracker = StreamedMessage.new(
+            span,
+            params: params,
+            start_time: start_time,
+            content: content,
+            content_limit: content_limit
+          )
+          recording = Enumerator.new do |y|
+            events.each do |event|
+              tracker.observe(event)
+              y << event
+            end
+            tracker.ended_by_server
+          ensure
+            tracker.set_attributes
+          end
+          # The SDK closes a stream by rewinding its enumerator. That does not resume a read
+          # suspended in `Enumerator#next`, whose `ensure` would never run, so the Message is
+          # recorded here too.
+          recording.define_singleton_method(:rewind) do
+            tracker.set_attributes
+            events.rewind
+            self
+          end
+          [recording, tracker]
+        end
+
+        # Runs the block, in which a stream helper folds one event into the Message it accumulates,
+        # and gives that Message to the span that follows `stream`, when one does. An event that the
+        # block fails on leaves the span without the Message.
+        #
+        # @param stream [Anthropic::Internal::Type::BaseStream] the raw stream that the helper reads
+        #
+        # @return [Anthropic::Models::Message, Anthropic::Models::Beta::BetaMessage]
+        def accumulate_streamed_message(stream)
+          tracker = stream.streamed_message if stream.is_a?(Anthropic::Internal::TracedStream)
+          tracker&.snapshot = nil
+          message = yield
+          tracker&.snapshot = message
+          message
+        end
+      end
+
+      # What a span records of a streamed Message, as far as the stream has been read. None of its
+      # methods raises. The content is not rebuilt here: it comes from the Message that a stream
+      # helper accumulates ({Tracing.accumulate_streamed_message}), so a raw stream has none.
+      class StreamedMessage
+        # The counts of `message_start` that a later `message_delta` replaces with the final ones.
+        PROVISIONAL_USAGE = [:output_tokens, :output_tokens_details, :iterations].freeze
+
+        # @param value [Anthropic::Models::Message, Anthropic::Models::Beta::BetaMessage, nil]
+        attr_writer :snapshot
+
+        # @param span [OpenTelemetry::Trace::Span]
+        # @param params [Hash{Symbol=>Object}] the request's body
+        # @param start_time [Float] when the API call started, on the monotonic clock
+        # @param content [Boolean] whether the span has the `content` attributes
+        # @param content_limit [Integer] the most bytes the `content` attributes hold
+        def initialize(span, params:, start_time:, content:, content_limit: CONTENT_LIMIT)
+          @span = span
+          @params = params
+          @start_time = start_time
+          @content = content
+          @content_limit = content_limit
+          @timed = false
+          @message = nil
+          @snapshot = nil
+          @stopped = false
+          @recorded = false
+        end
+
+        # @param event [Anthropic::Internal::Type::BaseModel]
+        def observe(event)
+          Tracing.recording("a streamed message") { fold(event) }
+        end
+
+        # `[]` reads a field of an event as it is, so nothing is converted: a stream is mostly content
+        # deltas, which cost nothing here after the first.
+        #
+        # @param event [Anthropic::Internal::Type::BaseModel]
+        private def fold(event)
+          case event[:type].to_sym
+          in :message_start
+            message = event[:message]
+            @message = {
+              id: message[:id],
+              model: message[:model],
+              usage: message[:usage].to_h.except(*PROVISIONAL_USAGE)
+            }
+          in :content_block_start if @message && event[:content_block][:type].to_sym == :fallback
+            @message[:model] = event[:content_block][:to][:model]
+          in :content_block_delta unless @timed
+            @timed = true
+            @span.set_attribute(
+              GEN_AI_RESPONSE_TIME_TO_FIRST_CHUNK,
+              Anthropic::Internal::Util.monotonic_secs - @start_time
+            )
+          in :message_delta unless @message.nil?
+            event[:usage].to_h.each do |key, value|
+              # The cache writes by lifetime come from `message_start` only.
+              @message[:usage][key] = value unless value.nil? || key == :cache_creation
+            end
+            stop_reason = event[:delta][:stop_reason]
+            @message[:stop_reason] = stop_reason unless stop_reason.nil?
+          in :message_stop
+            @stopped = true
+          else
+            nil
+          end
+        end
+
+        # The server ending the stream is the only end that sets a status here: `OK` after
+        # `message_stop`, and `api_error` before it, where the server cut the stream short.
+        def ended_by_server
+          # A second read of the stream ends at once, after the span.
+          return if @recorded
+
+          Tracing.recording("a streamed message") do
+            if @stopped
+              @span.status = OpenTelemetry::Trace::Status.ok
+            else
+              @span.status = OpenTelemetry::Trace::Status.error
+              @span.set_attribute(Anthropic::Internal::Tracing::ERROR_TYPE, "api_error")
+            end
+          end
+        end
+
+        # Only the first call does anything.
+        def set_attributes
+          return if @recorded
+
+          @recorded = true
+          Tracing.recording("a streamed message") do
+            unless @message.nil?
+              Anthropic::Internal::Tracing.set_response_attributes(
+                @span,
+                Anthropic::Internal::Tracing::SpanName::MESSAGES_CREATE,
+                @message
+              )
+              Tracing.set_computed_usage_attributes(@span, @message[:usage])
+            end
+          end
+          set_content
+        end
+
+        # The content of the request is written again with the output, so that the size bound counts both.
+        private def set_content
+          return if !@content || @snapshot.nil?
+
+          Tracing.recording("a streamed message") do
+            content = @snapshot.content
+            # The input of a tool use is the text of its JSON until its block ends, and `arguments` holds an object.
+            content = content&.map { _1[:input].is_a?(String) ? {**_1.to_h, input: {}} : _1 } unless @stopped
+            Tracing.set_message_content_attributes(@span, @params, content, limit: @content_limit)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/anthropic/helpers/tracing/tool_spans.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module Anthropic
+  module Helpers
+    module Tracing
+      class << self
+        # Returns `nil` when the client's spans are disabled, or when the span cannot start. A failure
+        # to read `params` is logged, and the span then starts without attributes.
+        #
+        # @param client [Anthropic::Client]
+        # @param params [Hash{Symbol=>Object}] the runner's, as the application gave them
+        #
+        # @return [OpenTelemetry::Trace::Span, nil]
+        def start_tool_runner_span(client, params)
+          tracer = client.open_telemetry_tracer
+          return nil if tracer.nil?
+
+          names = Anthropic::Internal::Tracing
+          attributes = recording("the tool runner") do
+            {
+              **client.open_telemetry_attributes,
+              names::GEN_AI_OPERATION_NAME => GEN_AI_OPERATION_NAME_VALUE_INVOKE_AGENT,
+              names::GEN_AI_REQUEST_MODEL => params[:model]&.to_s,
+              GEN_AI_CONVERSATION_ID => conversation_id(params[:request_options]),
+              GEN_AI_OUTPUT_TYPE => (GEN_AI_OUTPUT_TYPE_VALUE_JSON if json_output_format?(params))
+            }.compact
+          end
+          recording("the tool runner") do
+            tracer.start_span("anthropic.messages.tool_runner", kind: :internal, attributes: attributes)
+          end
+        end
+
+        # The status is `ERROR` for `error`, `OK` for a loop that returned, and unset when the
+        # application stopped the loop.
+        #
+        # @param span [OpenTelemetry::Trace::Span]
+        # @param returned [Boolean] whether the loop returned
+        # @param error [StandardError, nil] what the loop failed with
+        def end_tool_runner_span(span, returned:, error:)
+          recording("the tool runner") do
+            if error
+              Anthropic::Internal::Tracing.set_error_status(span, error)
+            elsif returned
+              span.status = OpenTelemetry::Trace::Status.ok
+            end
+            span.finish
+          end
+        end
+
+        # Returns `nil` when the client's spans are disabled, or when the span cannot start.
+        # {end_tool_use_span} ends the span.
+        #
+        # @param client [Anthropic::Client]
+        # @param tool [Anthropic::Helpers::Tools::BaseTool] the tool that runs
+        # @param tool_use [Anthropic::Models::Beta::BetaToolUseBlock]
+        # @param request_options [Anthropic::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [OpenTelemetry::Trace::Span, nil]
+        def start_tool_use_span(client, tool, tool_use, request_options)
+          tracer = client.open_telemetry_tracer
+          return nil if tracer.nil?
+
+          mcp = tool.is_a?(Anthropic::Helpers::Tools::Mcp::Tool)
+          operation = mcp ? "anthropic.mcp_tool_use" : "anthropic.custom_tool_use"
+          attributes = {
+            **client.open_telemetry_attributes,
+            Anthropic::Internal::Tracing::GEN_AI_OPERATION_NAME => GEN_AI_OPERATION_NAME_VALUE_EXECUTE_TOOL,
+            GEN_AI_TOOL_NAME => tool_use.name,
+            GEN_AI_TOOL_CALL_ID => tool_use.id,
+            GEN_AI_TOOL_TYPE => GEN_AI_TOOL_TYPE_VALUE_FUNCTION
+          }
+          # Read as it is, so that a value of another type sets no attribute and raises nothing.
+          toolset_name = tool_use[:toolset_name]
+          attributes[ANTHROPIC_TOOLSET_NAME] = toolset_name if toolset_name.is_a?(String)
+          description = tool_description(tool)
+          attributes[GEN_AI_TOOL_DESCRIPTION] = description unless description.nil?
+          # Options that cannot be read set no ID, and do not fail the run.
+          id = begin
+            conversation_id(request_options)
+          rescue StandardError
+            nil
+          end
+          attributes[GEN_AI_CONVERSATION_ID] = id unless id.nil?
+          recording("the tool run") do
+            tracer.start_span(
+              "#{operation} #{tool_use.name}",
+              kind: :internal,
+              attributes: attributes
+            )
+          end
+        end
+
+        # `nil` for no description, an empty one, or one that is not text ({utf8_text}): it can come from
+        # an MCP server.
+        #
+        # @param tool [Anthropic::Helpers::Tools::BaseTool]
+        #
+        # @return [String, nil]
+        def tool_description(tool)
+          description = tool.class.doc_string
+          return nil unless description.is_a?(String) && !description.empty?
+
+          utf8_text(description)
+        end
+
+        # @param client [Anthropic::Client]
+        # @param span [OpenTelemetry::Trace::Span]
+        # @param input [Hash{Symbol=>Object}] the `input` of the `tool_use` block
+        # @param result [Hash{Symbol=>Object}, nil] the `tool_result` block, or `nil` for a run that was
+        #   interrupted, which leaves the status unset
+        def end_tool_use_span(client, span, input, result)
+          recording("the tool run") do
+            next unless span.recording? && client.open_telemetry_content?
+
+            set_content_attributes(
+              span,
+              nil,
+              {
+                GEN_AI_TOOL_CALL_ARGUMENTS => input,
+                ANTHROPIC_TOOL_RESULT_CONTENT => (tool_result_content(result[:content]) unless result.nil?)
+              },
+              limit: client.open_telemetry_max_content_bytes
+            )
+          end
+          recording("the tool run") do
+            if result&.[](:is_error)
+              span.status = OpenTelemetry::Trace::Status.error
+              span.set_attribute(Anthropic::Internal::Tracing::ERROR_TYPE, "tool_error")
+            elsif result
+              span.status = OpenTelemetry::Trace::Status.ok
+            end
+            span.finish
+          end
+        end
+      end
+    end
+  end
+end

data/lib/anthropic/helpers/tracing.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Anthropic
+  module Helpers
+    # @api private
+    #
+    # The span attributes that {Anthropic::Internal::Tracing} cannot take from its tables: the
+    # computed ones, the Message that a stream carries, and the content of requests and responses.
+    # The tool runner's two `INTERNAL` spans start and end here too.
+    module Tracing
+    end
+  end
+end

data/lib/anthropic/helpers/vertex/client.rb

@@ -43,6 +43,9 @@ module Anthropic
         #   the Vertex URL rewrite and OAuth header happen inside the continuation, per
         #   attempt.
         #
+        # @param open_telemetry [Hash{Symbol=>Object}, Boolean, nil] OpenTelemetry tracing of this
+        #   client's API calls. See {Anthropic::Client#initialize}.
+        #
         def initialize(
           region: ENV["CLOUD_ML_REGION"],
           project_id: ENV["ANTHROPIC_VERTEX_PROJECT_ID"],
@@ -51,7 +54,8 @@ module Anthropic
           timeout: nil,
           initial_retry_delay: DEFAULT_INITIAL_RETRY_DELAY,
           max_retry_delay: DEFAULT_MAX_RETRY_DELAY,
-          middleware: nil
+          middleware: nil,
+          open_telemetry: nil
         )
           begin
             require("googleauth")
@@ -111,7 +115,8 @@ module Anthropic
             max_retries: max_retries,
             initial_retry_delay: initial_retry_delay,
             max_retry_delay: max_retry_delay,
-            middleware: middleware
+            middleware: middleware,
+            open_telemetry: open_telemetry
           )
 
           @messages = Anthropic::Resources::Messages.new(client: self)
@@ -184,6 +189,18 @@ module Anthropic
           super
         end
 
+        # @api private
+        #
+        # @return [Hash{String=>String}]
+        def open_telemetry_attributes
+          {**super, Anthropic::Internal::Tracing::GEN_AI_PROVIDER_NAME => "gcp.vertex_ai"}
+        end
+
+        # @api private
+        #
+        # @return [String]
+        private def open_telemetry_scope = "#{super}.vertex"
+
         # @api private
         #
         # The Vertex provider middleware: rewrites the canonical request into