braintrust 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f30760b63f57dfa236f8f8f74c60aabad6e693f86a57bf8699b028eb00e8639
-  data.tar.gz: fcae112dc4175b2248a853405587921f16eb2c67d2b8930e2a3877cc09b9e9d1
+  metadata.gz: 1047e872fe3a0acf40117bd9a0fcbf4e5024edbe3c1eb3d3bd1e32f60e5ffb18
+  data.tar.gz: e4c412abf3cf748ff157248feb821724ba4ffb76b67aecd8d1735179572afa93
 SHA512:
-  metadata.gz: 16e96c1f75646d2b581cb7a5c1c50ca66de3e625c75da11c6a9fd263313adea9a936e1e30f4a9733e16e56d3120737731d47ab89d858aafd7543b75011cbc9de
-  data.tar.gz: b926449904f3dafe6803f76105ee8d85b134c777b827c93b877390e318c167e1f8212eab7f207e1fc9a8e8b77cd6a2d48c5c374f412fc4af0a0f614a6c4de94e
+  metadata.gz: 41f183ac2bb20f64bca5c576f0decabdea9b7a4bcb46cbcf0c66292eb34f7e75a3b91516cd5520b4a3e207669eff0fa212afd1f75c1d6b172a44ea27bbc91e4b
+  data.tar.gz: 8a98b9ea710b69ac0b4e22cbdbed2b55bfab0d25db5fda2afc872931ce27a4eb9183433db03be6cedcb295dfca2f1fa43583620d848c55e9fa8b19629ecbfb8e

data/README.md

@@ -1,3 +1,5 @@
+[![Braintrust](./braintrust-logo.svg)](https://www.braintrust.dev/)
+
 # Braintrust Ruby SDK
 
 [![Gem Version](https://img.shields.io/gem/v/braintrust.svg)](https://rubygems.org/gems/braintrust)

data/lib/braintrust/config.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "internal/api_key_resolver"
+require_relative "internal/env"
 
 module Braintrust
   # Configuration object that reads from environment variables

data/lib/braintrust/eval/runner.rb

@@ -91,8 +91,8 @@ module Braintrust
           # Set attributes known before task execution
           eval_span.set_attribute("braintrust.parent", eval_context.parent_span_attr) if eval_context.parent_span_attr
           set_json_attr(eval_span, "braintrust.span_attributes", build_span_attributes("eval"))
-          set_json_attr(eval_span, "braintrust.input_json", {input: kase.input})
-          set_json_attr(eval_span, "braintrust.expected", kase.expected) if kase.expected
+          set_json_attr(eval_span, "braintrust.input_json", kase.input)
+          set_json_attr(eval_span, "braintrust.expected_json", kase.expected) unless kase.expected.nil?
           set_json_attr(eval_span, "braintrust.metadata", kase.metadata) if kase.metadata
           eval_span.set_attribute("braintrust.tags", kase.tags) if kase.tags
           eval_span.set_attribute("braintrust.origin", kase.origin) if kase.origin
@@ -103,7 +103,6 @@ module Braintrust
           rescue => e
             # Error already recorded on task span, set eval span status
             eval_span.status = OpenTelemetry::Trace::Status.error(e.message)
-            set_json_attr(eval_span, "braintrust.output_json", {output: nil})
             errors << "Task failed for input '#{kase.input}': #{e.message}"
             report_progress(eval_span, kase, error: e.message)
             next
@@ -134,7 +133,7 @@ module Braintrust
           end
 
           # Set output after task completes
-          set_json_attr(eval_span, "braintrust.output_json", {output: kase.output})
+          set_json_attr(eval_span, "braintrust.output_json", kase.output)
 
           report_progress(eval_span, kase, data: kase.output)
         end
@@ -151,6 +150,7 @@ module Braintrust
           task_span.set_attribute("braintrust.parent", eval_context.parent_span_attr) if eval_context.parent_span_attr
           set_json_attr(task_span, "braintrust.span_attributes", build_span_attributes("task"))
           set_json_attr(task_span, "braintrust.input_json", kase.input)
+          set_json_attr(task_span, "braintrust.expected_json", kase.expected) unless kase.expected.nil?
 
           begin
             output = eval_context.task.call(

data/lib/braintrust/internal/env.rb

@@ -5,6 +5,8 @@ module Braintrust
     # Environment variable utilities.
     module Env
       ENV_AUTO_INSTRUMENT = "BRAINTRUST_AUTO_INSTRUMENT"
+      ENV_ENVIRONMENT_NAME = "BRAINTRUST_ENVIRONMENT_NAME"
+      ENV_ENVIRONMENT_TYPE = "BRAINTRUST_ENVIRONMENT_TYPE"
       ENV_INSTRUMENT_EXCEPT = "BRAINTRUST_INSTRUMENT_EXCEPT"
       ENV_INSTRUMENT_ONLY = "BRAINTRUST_INSTRUMENT_ONLY"
       ENV_FLUSH_ON_EXIT = "BRAINTRUST_FLUSH_ON_EXIT"
@@ -26,6 +28,36 @@ module Braintrust
         parse_list(ENV_INSTRUMENT_ONLY)
       end
 
+      def self.detect_environment
+        env_type = env_value(ENV_ENVIRONMENT_TYPE)
+        env_name = env_value(ENV_ENVIRONMENT_NAME)
+        if present?(env_type) || present?(env_name)
+          return {type: env_type, name: env_name}.compact
+        end
+
+        {
+          "GITHUB_ACTIONS" => "github_actions",
+          "GITLAB_CI" => "gitlab_ci",
+          "CIRCLECI" => "circleci",
+          "BUILDKITE" => "buildkite",
+          "JENKINS_URL" => "jenkins",
+          "JENKINS_HOME" => "jenkins",
+          "TF_BUILD" => "azure_pipelines",
+          "TEAMCITY_VERSION" => "teamcity",
+          "TRAVIS" => "travis",
+          "BITBUCKET_BUILD_NUMBER" => "bitbucket"
+        }.each do |key, name|
+          return {type: "ci", name: name} if present?(ENV[key])
+        end
+        return {type: "ci", name: "ci"} if present?(ENV["CI"])
+
+        server_name = detect_server_environment_name
+        return {type: "server", name: server_name} if server_name
+
+        deployment_mode_environment(ENV["RAILS_ENV"]) ||
+          deployment_mode_environment(ENV["RACK_ENV"])
+      end
+
       # Parse a comma-separated environment variable into an array of symbols.
       # @param key [String] The environment variable name
       # @return [Array<Symbol>, nil] Array of symbols, or nil if not set
@@ -34,6 +66,55 @@ module Braintrust
         return nil unless value
         value.split(",").map(&:strip).map(&:to_sym)
       end
+
+      def self.deployment_mode_environment(value)
+        return nil unless present?(value)
+
+        normalized = value.strip.downcase
+        return {type: "server", name: normalized} if ["production", "staging"].include?(normalized)
+        return {type: "local", name: normalized} if ["development", "local"].include?(normalized)
+
+        nil
+      end
+      private_class_method :deployment_mode_environment
+
+      def self.detect_server_environment_name
+        {"VERCEL" => "vercel", "NETLIFY" => "netlify"}.each do |key, name|
+          return name if present?(ENV[key])
+        end
+        return "ecs" if present?(ENV["ECS_CONTAINER_METADATA_URI"]) || present?(ENV["ECS_CONTAINER_METADATA_URI_V4"])
+
+        aws_execution_env = env_value("AWS_EXECUTION_ENV")
+        return "ecs" if aws_execution_env&.start_with?("AWS_ECS_")
+        return "aws_lambda" if aws_execution_env&.start_with?("AWS_Lambda_")
+        return "aws_lambda" if present?(ENV["AWS_LAMBDA_FUNCTION_NAME"])
+
+        {
+          "K_SERVICE" => "cloud_run",
+          "FUNCTION_TARGET" => "gcp_functions",
+          "KUBERNETES_SERVICE_HOST" => "kubernetes",
+          "DYNO" => "heroku",
+          "FLY_APP_NAME" => "fly",
+          "RAILWAY_ENVIRONMENT" => "railway",
+          "RENDER_SERVICE_NAME" => "render"
+        }.each do |key, name|
+          return name if present?(ENV[key])
+        end
+
+        nil
+      end
+      private_class_method :detect_server_environment_name
+
+      def self.env_value(key)
+        value = ENV[key]
+        value&.strip unless value.nil? || value.strip.empty?
+      end
+      private_class_method :env_value
+
+      def self.present?(value)
+        !value.nil? && !value.strip.empty?
+      end
+      private_class_method :present?
     end
   end
 end

data/lib/braintrust/trace/span_exporter.rb

@@ -2,16 +2,20 @@
 
 require "opentelemetry/exporter/otlp"
 require_relative "../state"
+require_relative "span_origin"
 
 module Braintrust
   module Trace
-    # Custom OTLP exporter that groups spans by braintrust.parent attribute
-    # and sets the x-bt-parent HTTP header per group. This is required for
-    # the Braintrust OTLP backend to route spans to the correct experiment/project.
+    # Custom OTLP exporter for the Braintrust backend. On export it:
+    # - stamps span origin provenance onto each SpanData (via the prepended SpanOrigin behavior)
+    # - groups spans by braintrust.parent and sets the x-bt-parent header per group,
+    #   so the backend routes them to the correct experiment/project
     #
     # Thread safety: BatchSpanProcessor serializes export() calls via its
     # @export_mutex, so @headers mutation here is safe.
     class SpanExporter < OpenTelemetry::Exporter::OTLP::Exporter
+      prepend SpanOrigin
+
       PARENT_ATTR_KEY = SpanProcessor::PARENT_ATTR_KEY
       PARENT_HEADER = "x-bt-parent"
 

data/lib/braintrust/trace/span_filter.rb

@@ -16,7 +16,8 @@ module Braintrust
       SYSTEM_ATTRIBUTES = [
         "braintrust.parent",
         "braintrust.org",
-        "braintrust.app_url"
+        "braintrust.app_url",
+        "braintrust.context_json"
       ].freeze
 
       # Prefixes that indicate an AI-related span

data/lib/braintrust/trace/span_origin.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../version"
+require_relative "../internal/env"
+
+module Braintrust
+  module Trace
+    # Span origin provenance decoration.
+    #
+    # This is a *behavior*, not a type. Prepend it onto any exporter whose
+    # +export(span_data, timeout:)+ it can +super+ into, and every exported
+    # SpanData gains a +braintrust.context_json+ attribute carrying span origin
+    # (SDK name/version, instrumentation scope, environment).
+    #
+    # Because it only ever touches the SpanData copies handed to *this*
+    # exporter, the enrichment is invisible to any other exporter sharing the
+    # same tracer provider - there is no global patch and nothing leaks onto a
+    # customer's other OTel traces.
+    module SpanOrigin
+      CONTEXT_JSON_ATTR_KEY = "braintrust.context_json"
+
+      # Exporter behavior: enrich each SpanData with span origin before export.
+      # @param span_data [Array<OpenTelemetry::SDK::Trace::SpanData>]
+      # @return [Integer] export result from the wrapped exporter
+      def export(span_data, timeout: nil)
+        # Environment is process-global and stable; read it once per batch
+        # rather than once per span. It is cheap (ENV reads only).
+        environment = Internal::Env.detect_environment
+        enriched = span_data.map { |sd| SpanOrigin.enrich(sd, environment: environment) }
+        super(enriched, timeout: timeout)
+      end
+
+      # Enrich a single SpanData with span origin provenance.
+      # Mutates the SpanData in place (replacing its frozen attributes hash with
+      # a new frozen hash - it never mutates the shared hash) and returns it.
+      # @param span_data [OpenTelemetry::SDK::Trace::SpanData]
+      # @param environment [Hash, nil] process environment ({type:, name:}) or nil
+      # @return [OpenTelemetry::SDK::Trace::SpanData]
+      def self.enrich(span_data, environment:)
+        attributes = span_data.attributes || {}
+        enriched_attributes = attributes_with_origin(
+          attributes,
+          instrumentation_name: instrumentation_name(span_data),
+          environment: environment
+        )
+
+        return span_data if enriched_attributes.equal?(attributes)
+
+        span_data.attributes = enriched_attributes.freeze
+        span_data.total_recorded_attributes = enriched_attributes.length
+        span_data
+      end
+
+      def self.attributes_with_origin(attributes, instrumentation_name:, environment:)
+        context = parse_context_json(attributes[CONTEXT_JSON_ATTR_KEY])
+        span_origin = context["span_origin"].is_a?(Hash) ? context["span_origin"] : {}
+
+        span_origin_changed = false
+        unless span_origin.key?("name")
+          span_origin["name"] = "braintrust.sdk.ruby"
+          span_origin_changed = true
+        end
+        unless span_origin.key?("version")
+          span_origin["version"] = Braintrust::VERSION
+          span_origin_changed = true
+        end
+        unless span_origin.key?("instrumentation")
+          span_origin["instrumentation"] = {"name" => instrumentation_name}
+          span_origin_changed = true
+        end
+        if environment && !span_origin.key?("environment")
+          span_origin["environment"] = environment
+          span_origin_changed = true
+        end
+
+        context_changed = context["span_origin"] != span_origin || span_origin_changed
+        return attributes unless context_changed
+
+        context["span_origin"] = span_origin
+        attributes.merge(CONTEXT_JSON_ATTR_KEY => JSON.generate(context))
+      end
+
+      def self.parse_context_json(raw)
+        return {} unless raw.is_a?(String) && !raw.strip.empty?
+
+        parsed = JSON.parse(raw)
+        parsed.is_a?(Hash) ? parsed : {}
+      rescue JSON::ParserError
+        {}
+      end
+
+      def self.instrumentation_name(span)
+        if span.respond_to?(:instrumentation_scope) && span.instrumentation_scope&.respond_to?(:name)
+          return span.instrumentation_scope.name
+        end
+        if span.respond_to?(:instrumentation_library) && span.instrumentation_library&.respond_to?(:name)
+          return span.instrumentation_library.name
+        end
+
+        "braintrust-ruby"
+      end
+    end
+  end
+end

data/lib/braintrust/trace/span_processor.rb

@@ -83,9 +83,11 @@ module Braintrust
         # If no filters, keep everything
         return true if @filters.empty?
 
+        span_data = span.respond_to?(:to_span_data) ? span.to_span_data : span
+
         # Apply filters in order - first non-zero result wins
         @filters.each do |filter|
-          result = filter.call(span)
+          result = filter.call(span_data)
           return true if result > 0  # Keep span
           return false if result < 0 # Drop span
           # result == 0: no influence, continue to next filter

data/lib/braintrust/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Braintrust
-  VERSION = "0.4.0"
+  VERSION = "0.4.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: braintrust
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.1
 platform: ruby
 authors:
 - Braintrust
@@ -182,6 +182,7 @@ files:
 - lib/braintrust/trace/attachment.rb
 - lib/braintrust/trace/span_exporter.rb
 - lib/braintrust/trace/span_filter.rb
+- lib/braintrust/trace/span_origin.rb
 - lib/braintrust/trace/span_processor.rb
 - lib/braintrust/vendor/mustache.rb
 - lib/braintrust/vendor/mustache/context.rb