instana 2.0.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 35cfa89077e641cdd3e6fb0a97008f1e10ad7b703dc5b2b79e90a383dfc30099
-  data.tar.gz: dd9b39744a6432f619e496c759da84bffdfe114824bef0bbbcea155dbef3a284
+  metadata.gz: 4a940d6791ca18a45f73ca949de0268cb4195ca269991d78683d1d89c3801919
+  data.tar.gz: c4a79bc94556b873ca0d2cb3cbe2b988914e2579d6fd124bbf4925142316dd85
 SHA512:
-  metadata.gz: 47d8317281da1f8ae6adb6f740055d4845f125da6ccac65ce03ff68e4efc9a1eb22530f62571ef12bad952866832d99076b1ba4d62a6c876d0aaf4ab3b9c6ae5
-  data.tar.gz: bc463f59a0662b0fe8ff5e34996631b1ed01215ef22e8f16781e7a249936e602959c1fecba74a3fe42e0c718f0ed37a4c62aa732c3b0f37f92cb49d9472e1e6f
+  metadata.gz: f0c11ead2a6eb5e7cf4811a44b0edb6af0edbed588e712a080b5de07a704fbd28b91474e593b6342537459fe69cc0fcc60dfb83c18618e8e4ca5babea5096d6b
+  data.tar.gz: 5a22a83d6a6f930df189a914116398b372976d95f76ce86ae63b18c2f014eb4aa170a5415f5b6feb2f69b63bc9aff511d16e2d5e5bfb2682c369a0299cb5d2d3

data/lib/instana/instrumentation/instrumented_request.rb

@@ -122,6 +122,7 @@ module Instana
         long_instana_id: long_instana_id? ? sanitized_t : nil,
         external_trace_id: external_trace_id,
         external_state: @env['HTTP_TRACESTATE'],
+        external_trace_flags: context_from_trace_parent[:external_trace_flags],
         from_w3c: false
       }.reject { |_, v| v.nil? }
     end
@@ -140,6 +141,7 @@ module Instana
         external_state: @env['HTTP_TRACESTATE'],
         trace_id: trace_id,
         span_id: span_id,
+        external_trace_flags: matches['flags'],
         from_w3c: true
       }
     end

data/lib/instana/instrumentation/net-http.rb

@@ -56,7 +56,8 @@ module Instana
           # without a backtrace (no exception)
           current_span.record_exception(nil)
         end
-
+        extra_headers = ::Instana::Util.extra_header_tags(response)&.merge(::Instana::Util.extra_header_tags(request))
+        kv_payload[:http][:header] = extra_headers unless extra_headers&.empty?
         response
       rescue => e
         current_span&.record_exception(e)

data/lib/instana/instrumentation/rack.rb

@@ -10,7 +10,7 @@ module Instana
       @app = app
     end
 
-    def call(env) # rubocop:disable Metrics/CyclomaticComplexity,Metrics/MethodLength
+    def call(env)
       req = InstrumentedRequest.new(env)
       kvs = {
         http: req.request_tags
@@ -26,75 +26,14 @@ module Instana
       @trace_token = OpenTelemetry::Context.attach(trace_ctx)
       status, headers, response = @app.call(env)
 
-      if ::Instana.tracer.tracing?
-        unless req.correlation_data.empty?
-          current_span[:crid] = req.correlation_data[:id]
-          current_span[:crtp] = req.correlation_data[:type]
-        end
-
-        if !req.instana_ancestor.empty? && req.continuing_from_trace_parent?
-          current_span[:ia] = req.instana_ancestor
-        end
-
-        if req.continuing_from_trace_parent?
-          current_span[:tp] = true
-        end
-
-        if req.external_trace_id?
-          current_span[:lt] = req.external_trace_id
-        end
-
-        if req.synthetic?
-          current_span[:sy] = true
-        end
-
-        # In case some previous middleware returned a string status, make sure that we're dealing with
-        # an integer.  In Ruby nil.to_i, "asdfasdf".to_i will always return 0 from Ruby versions 1.8.7 and newer.
-        # So if an 0 status is reported here, it indicates some other issue (e.g. no status from previous middleware)
-        # See Rack Spec: https://www.rubydoc.info/github/rack/rack/file/SPEC#label-The+Status
-        kvs[:http][:status] = status.to_i
-
-        if status.to_i >= 500
-          # Because of the 5xx response, we flag this span as errored but
-          # without a backtrace (no exception)
-          ::Instana.tracer.log_error(nil)
-        end
-
-        # If the framework instrumentation provides a path template,
-        # pass it into the span here.
-        # See: https://www.instana.com/docs/tracing/custom-best-practices/#path-templates-visual-grouping-of-http-endpoints
-        kvs[:http][:path_tpl] = env['INSTANA_HTTP_PATH_TEMPLATE'] if env['INSTANA_HTTP_PATH_TEMPLATE']
-
-        # Save the span context before the trace ends so we can place
-        # them in the response headers in the ensure block
-        trace_context = ::Instana.tracer.current_span.context
-      end
-
+      trace_context = process_span_tags(req, current_span, kvs, status, env) if ::Instana.tracer.tracing?
+      merge_response_headers(kvs, headers)
       [status, headers, response]
     rescue Exception => e
       current_span.record_exception(e) if ::Instana.tracer.tracing?
       raise
     ensure
-      if ::Instana.tracer.tracing?
-        if headers
-          # Set response headers; encode as hex string
-          if trace_context.active?
-            headers['X-Instana-T'] = trace_context.trace_id_header
-            headers['X-Instana-S'] = trace_context.span_id_header
-            headers['X-Instana-L'] = '1'
-
-            headers['Tracestate'] = trace_context.trace_state_header
-          else
-            headers['X-Instana-L'] = '0'
-          end
-
-          headers['Traceparent'] = trace_context.trace_parent_header
-          headers['Server-Timing'] = "intid;desc=#{trace_context.trace_id_header}"
-        end
-        current_span.set_tags(kvs)
-        OpenTelemetry::Context.detach(@trace_token) if @trace_token
-        current_span.finish
-      end
+      finalize_trace(current_span, kvs, headers, trace_context) if ::Instana.tracer.tracing?
     end
 
     private
@@ -112,7 +51,8 @@ module Instana
             level: incoming_context[:level],
             baggage: {
               external_trace_id: incoming_context[:external_trace_id],
-              external_state: incoming_context[:external_state]
+              external_state: incoming_context[:external_state],
+              external_trace_flags: incoming_context[:external_trace_flags]
             }
           )
         end
@@ -121,5 +61,85 @@ module Instana
       end
       parent_context
     end
+
+    def process_span_tags(req, current_span, kvs, status, env)
+      add_correlation_data(req, current_span)
+      add_trace_parent_data(req, current_span)
+      add_status_and_error(kvs, status)
+      add_path_template(kvs, env)
+
+      # Save the span context before the trace ends so we can place
+      # them in the response headers in the ensure block
+      ::Instana.tracer.current_span.context
+    end
+
+    def add_correlation_data(req, current_span)
+      return if req.correlation_data.empty?
+
+      current_span[:crid] = req.correlation_data[:id]
+      current_span[:crtp] = req.correlation_data[:type]
+    end
+
+    def add_trace_parent_data(req, current_span)
+      if !req.instana_ancestor.empty? && req.continuing_from_trace_parent?
+        current_span[:ia] = req.instana_ancestor
+      end
+
+      current_span[:tp] = true if req.continuing_from_trace_parent?
+      current_span[:lt] = req.external_trace_id if req.external_trace_id?
+      current_span[:sy] = true if req.synthetic?
+    end
+
+    def add_status_and_error(kvs, status)
+      # In case some previous middleware returned a string status, make sure that we're dealing with
+      # an integer.  In Ruby nil.to_i, "asdfasdf".to_i will always return 0 from Ruby versions 1.8.7 and newer.
+      # So if an 0 status is reported here, it indicates some other issue (e.g. no status from previous middleware)
+      # See Rack Spec: https://www.rubydoc.info/github/rack/rack/file/SPEC#label-The+Status
+      kvs[:http][:status] = status.to_i
+
+      return unless status.to_i >= 500
+
+      # Because of the 5xx response, we flag this span as errored but
+      # without a backtrace (no exception)
+      ::Instana.tracer.log_error(nil)
+    end
+
+    def add_path_template(kvs, env)
+      # If the framework instrumentation provides a path template,
+      # pass it into the span here.
+      # See: https://www.instana.com/docs/tracing/custom-best-practices/#path-templates-visual-grouping-of-http-endpoints
+      kvs[:http][:path_tpl] = env['INSTANA_HTTP_PATH_TEMPLATE'] if env['INSTANA_HTTP_PATH_TEMPLATE']
+    end
+
+    def merge_response_headers(kvs, headers)
+      extra_response_headers = ::Instana::Util.extra_header_tags(headers)
+      if kvs[:http][:header].nil?
+        kvs[:http][:header] = extra_response_headers
+      else
+        kvs[:http][:header].merge!(extra_response_headers)
+      end
+    end
+
+    def finalize_trace(current_span, kvs, headers, trace_context)
+      set_response_headers(headers, trace_context) if headers
+      current_span.set_tags(kvs)
+      OpenTelemetry::Context.detach(@trace_token) if @trace_token
+      current_span.finish
+    end
+
+    def set_response_headers(headers, trace_context)
+      # Set response headers; encode as hex string
+      if trace_context.active?
+        headers['X-Instana-T'] = trace_context.trace_id_header
+        headers['X-Instana-S'] = trace_context.span_id_header
+        headers['X-Instana-L'] = '1'
+        headers['Tracestate'] = trace_context.trace_state_header
+      else
+        headers['X-Instana-L'] = '0'
+      end
+
+      headers['Traceparent'] = trace_context.trace_parent_header
+      headers['Server-Timing'] = "intid;desc=#{trace_context.trace_id_header}"
+    end
   end
 end

data/lib/instana/setup.rb

@@ -41,6 +41,7 @@ require 'instana/backend/serverless_agent'
 require 'instana/backend/agent'
 require 'instana/trace'
 require 'instana/trace/tracer_provider'
+require 'instana/span_filtering'
 
 ::Instana.setup
 ::Instana.agent.setup

data/lib/instana/span_filtering/condition.rb

@@ -0,0 +1,134 @@
+# (c) Copyright IBM Corp. 2025
+
+module Instana
+  module SpanFiltering
+    # Represents a condition for filtering spans
+    #
+    # A condition consists of:
+    # - key: The attribute to match against (category, kind, type, or span attribute)
+    # - values: List of values to match against (OR logic between values)
+    # - match_type: String matching strategy (strict, startswith, endswith, contains)
+    class Condition
+      attr_reader :key, :values, :match_type
+
+      def initialize(key, values, match_type = 'strict')
+        @key = key
+        @values = Array(values)
+        @match_type = match_type
+      end
+
+      # Check if a span matches this condition
+      # @param span [Hash] The span to check
+      # @return [Boolean] True if the span matches any of the values
+      def matches?(span)
+        attribute_value = extract_attribute(span, @key)
+        return false if attribute_value.nil?
+
+        @values.any? { |value| matches_value?(attribute_value, value) }
+      end
+
+      private
+
+      # Extract an attribute from a span
+      # @param span [Hash] The span to extract from
+      # @param key [String] The key to extract
+      # @return [Object, nil] The attribute value or nil if not found
+      def extract_attribute(span, key)
+        case key
+        when 'category'
+          # Map to appropriate span attribute for category
+          determine_category(span)
+        when 'kind'
+          # Map to appropriate span attribute for kind
+          span[:k] || span['k']
+        when 'type'
+          # Map to appropriate span attribute for type
+          span[:n] || span['n']
+        else
+          # Handle nested attributes with dot notation
+          extract_nested_attribute(span[:data] || span['data'], key)
+        end
+      end
+
+      # Determine the category of a span based on its properties
+      # @param span [Hash] The span to categorize
+      # @return [String, nil] The category or nil if not determinable
+      def determine_category(span)
+        data = span[:data] || span['data']
+        return nil unless data
+
+        if data[:http] || data['http']
+          'protocols'
+        elsif data[:redis] || data[:mysql] || data[:pg] || data[:db]
+          'databases'
+        elsif data[:sqs] || data[:sns] || data[:mq]
+          'messaging'
+        elsif (span[:n] || span['n'])&.start_with?('log.')
+          'logging'
+        end
+      end
+
+      # Extract a nested attribute using dot notation
+      # @param data [Hash] The data hash to extract from
+      # @param key [String] The key in dot notation
+      # @return [Object, nil] The attribute value or nil if not found
+      def extract_nested_attribute(data, key)
+        return nil unless data
+
+        parts = key.split('.')
+        current = data
+
+        parts.each do |part|
+          # Try symbol key first, then string key
+          if current.key?(part.to_sym)
+            current = current[part.to_sym]
+          elsif current.key?(part)
+            current = current[part]
+          else
+            return nil # Key not found
+          end
+
+          # Only return nil if the value is actually nil, not for false values
+        end
+
+        current
+      end
+
+      # Check if an attribute value matches a condition value
+      # @param attribute_value [Object] The attribute value
+      # @param condition_value [String] The condition value
+      # @return [Boolean] True if the attribute value matches the condition value
+      def matches_value?(attribute_value, condition_value)
+        # Handle wildcard
+        return true if condition_value == '*'
+
+        # Direct comparison first - this should handle boolean values correctly
+        return true if attribute_value == condition_value
+
+        # For strict matching with type conversion
+        if @match_type == 'strict'
+          # Convert to strings and compare
+          attribute_str = attribute_value.to_s
+          condition_str = condition_value.to_s
+          return attribute_str == condition_str
+        end
+
+        # For other match types, convert both to strings
+        attribute_str = attribute_value.to_s
+        condition_str = condition_value.to_s
+
+        case @match_type
+        when 'startswith'
+          attribute_str.start_with?(condition_str)
+        when 'endswith'
+          attribute_str.end_with?(condition_str)
+        when 'contains'
+          attribute_str.include?(condition_str)
+        else
+          # Default to strict matching
+          attribute_str == condition_str
+        end
+      end
+    end
+  end
+end

data/lib/instana/span_filtering/configuration.rb

@@ -0,0 +1,262 @@
+# (c) Copyright IBM Corp. 2025
+
+require 'yaml'
+
+module Instana
+  module SpanFiltering
+    # Configuration class for span filtering
+    #
+    # This class handles loading and managing span filtering rules from various sources:
+    # - YAML configuration file (via INSTANA_CONFIG_PATH)
+    # - Environment variables
+    # - Agent discovery response
+    # It supports both include and exclude rules with various matching strategies
+    class Configuration
+      attr_reader :include_rules, :exclude_rules, :deactivated
+
+      TRACING_CONFIG_WARNING = 'Please use "tracing" instead of "com.instana.tracing" for local configuration file.'.freeze
+
+      def initialize
+        @include_rules = []
+        @exclude_rules = []
+        @deactivated = false
+        load_configuration
+      end
+
+      # Load configuration from all available sources
+      def load_configuration
+        load_from_yaml
+        load_from_env_vars unless rules_loaded?
+        load_from_agent unless rules_loaded?
+      end
+
+      private
+
+      # Load configuration from agent discovery response
+      def load_from_agent
+        # Try to get discovery value immediately first
+        discovery = ::Instana.agent&.delegate&.send(:discovery_value)
+        if discovery && discovery.is_a?(Hash) && !discovery.empty?
+          process_discovery_config(discovery)
+          return
+        end
+
+        # If not available, set up a timer task to periodically check for discovery
+        setup_discovery_timer
+      rescue => e
+        Instana.logger.warn("Failed to load span filtering configuration from agent: #{e.message}")
+      end
+
+      # Set up a timer task to periodically check for discovery
+      def setup_discovery_timer
+        # Don't create a timer task if we're in a test environment
+        return if ENV.key?('INSTANA_TEST')
+
+        # Create a timer task that checks for discovery every second
+        @discovery_timer = Concurrent::TimerTask.new(execution_interval: 1) do
+          check_discovery
+        end
+
+        # Start the timer task
+        @discovery_timer.execute
+      end
+
+      # Check if discovery is available and process it
+      def check_discovery
+        discovery = ::Instana.agent&.delegate.send(:discovery_value)
+        if discovery && discovery.is_a?(Hash) && !discovery.empty?
+          process_discovery_config(discovery)
+
+          # Shutdown the timer task after successful processing
+          @discovery_timer.shutdown if @discovery_timer
+
+          return true
+        end
+
+        false
+      rescue => e
+        Instana.logger.warn("Error checking discovery in timer task: #{e.message}")
+        false
+      end
+
+      # Process the discovery configuration
+      def process_discovery_config(discovery)
+        # Check if tracing configuration exists in the discovery response
+        tracing_config = discovery['tracing']
+        return unless tracing_config
+
+        # Process filter configuration
+        if tracing_config['filter']
+          filter_config = tracing_config['filter']
+          @deactivated = filter_config['deactivate'] == true
+
+          # Process include rules
+          process_rules(filter_config['include'], true) if filter_config['include']
+
+          # Process exclude rules
+          process_rules(filter_config['exclude'], false) if filter_config['exclude']
+        end
+
+        # Process disable configuration
+        if tracing_config['disable']
+          process_disable_config(tracing_config['disable'])
+        end
+
+        # Return true to indicate successful processing
+        true
+      rescue => e
+        Instana.logger.warn("Failed to process discovery configuration: #{e.message}")
+        false
+      end
+
+      # Check if the rules are already loaded
+      def rules_loaded?
+        @include_rules.any? || @exclude_rules.any?
+      end
+
+      # Load configuration from YAML file specified by INSTANA_CONFIG_PATH
+      def load_from_yaml
+        config_path = ENV['INSTANA_CONFIG_PATH']
+        return unless config_path && File.exist?(config_path)
+
+        begin
+          yaml_content = YAML.safe_load(File.read(config_path))
+
+          # Support both "tracing" and "com.instana.tracing" as top-level keys
+          tracing_config = yaml_content['tracing'] || yaml_content['com.instana.tracing']
+          ::Instana.logger.warn(TRACING_CONFIG_WARNING) if yaml_content.key?('com.instana.tracing')
+          return unless tracing_config
+
+          # Process filter configuration
+          if tracing_config['filter']
+            filter_config = tracing_config['filter']
+            @deactivated = filter_config['deactivate'] == true
+
+            # Process include rules
+            process_rules(filter_config['include'], true) if filter_config['include']
+
+            # Process exclude rules
+            process_rules(filter_config['exclude'], false) if filter_config['exclude']
+          end
+
+          # Process disable configuration
+          if tracing_config['disable']
+            process_disable_config(tracing_config['disable'])
+          end
+        rescue => e
+          Instana.logger.warn("Failed to load span filtering configuration from YAML: #{e.message}")
+        end
+      end
+
+      # Load configuration from environment variables
+      def load_from_env_vars
+        ENV.each do |key, value|
+          next unless key.start_with?('INSTANA_TRACING_FILTER_')
+
+          parts = key.split('_')
+          next unless parts.size >= 5
+
+          policy = parts[3].downcase
+          next unless ['include', 'exclude'].include?(policy)
+
+          if parts[4] == 'ATTRIBUTES'
+            process_env_attributes(policy, parts[4..].join('_'), value)
+          elsif policy == 'exclude' && parts[4] == 'SUPPRESSION'
+            process_env_suppression(parts[3..].join('_'), value)
+          end
+        end
+
+        return unless !ENV["INSTANA_TRACING_DISABLE"].nil? && !%w[True true 1].include?(ENV["INSTANA_TRACING_DISABLE"])
+
+        process_disable_config(ENV["INSTANA_TRACING_DISABLE"].split(','))
+      end
+
+      # Process rules from YAML configuration
+      def process_rules(rules_config, is_include)
+        rules_config.each do |rule_config|
+          name = rule_config['name']
+          suppression = is_include ? false : (rule_config['suppression'] != false) # Default true for exclude
+
+          conditions = []
+          rule_config['attributes'].each do |attr_config|
+            key = attr_config['key']
+            values = attr_config['values']
+            match_type = attr_config['match_type'] || 'strict'
+
+            conditions << Condition.new(key, values, match_type)
+          end
+
+          rule = FilterRule.new(name, suppression, conditions)
+          is_include ? @include_rules << rule : @exclude_rules << rule
+        end
+      end
+
+      # Process attributes from environment variables
+      def process_env_attributes(policy, name, value)
+        # Parse rules from environment variable format
+        # Format: key;values;match_type|key;values;match_type
+        rules = value.split('|')
+        conditions = []
+
+        rules.each do |rule|
+          parts = rule.split(';')
+          next unless parts.size >= 2
+
+          key = parts[0]
+          values = parts[1].split(',')
+          match_type = parts[2] || 'strict'
+
+          conditions << Condition.new(key, values, match_type)
+        end
+
+        rule_name = "EnvRule_#{name}"
+        suppression = policy == 'exclude' # Default true for exclude
+
+        rule = FilterRule.new(rule_name, suppression, conditions)
+        policy == 'include' ? @include_rules << rule : @exclude_rules << rule
+      end
+
+      # Process suppression setting from environment variables
+      def process_env_suppression(policy_name, value)
+        # Find the corresponding rule and update its suppression value
+        rule_index = policy_name.split('_')[1].to_i
+        return if rule_index >= @exclude_rules.size
+
+        suppression = %w[1 true True].include?(value)
+        @exclude_rules[rule_index].suppression = suppression
+      end
+
+      # Process disable configuration from YAML or agent discovery
+      # @param disable_config [Array] The disable configuration array
+      def process_disable_config(disable_config)
+        return unless disable_config.is_a?(Array)
+
+        disable_config.each do |item|
+          if item.is_a?(Hash)
+            item.each do |key, value|
+              if value == true
+                update_instana_config_for_disabled_technology(key)
+              end
+            end
+          elsif item.is_a?(String)
+            update_instana_config_for_disabled_technology(item)
+          end
+        end
+      end
+
+      # Update Instana::Config for a disabled technology
+      # @param technology [String] The technology to disable
+      def update_instana_config_for_disabled_technology(technology)
+        tech_sym = technology.to_sym
+
+        case tech_sym
+        when :redis
+          ::Instana.config[:redis][:enabled] = false
+        when :databases
+          # If databases category is disabled, also disable redis
+          ::Instana.config[:redis][:enabled] = false
+        end
+      end
+    end
+  end
+end

data/lib/instana/span_filtering/filter_rule.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# (c) Copyright IBM Corp. 2025
+
+module Instana
+  module SpanFiltering
+    # Represents a filtering rule for spans
+    #
+    # A rule consists of:
+    # - name: A human-readable identifier for the rule
+    # - suppression: Whether child spans should be suppressed (only for exclude rules)
+    # - conditions: A list of conditions that must all be satisfied (AND logic)
+    class FilterRule
+      attr_reader :name
+      attr_accessor :suppression, :conditions
+
+      def initialize(name, suppression, conditions)
+        @name = name
+        @suppression = suppression
+        @conditions = conditions
+      end
+
+      # Check if a span matches this rule
+      # @param span [Hash] The span to check
+      # @return [Boolean] True if the span matches all conditions
+      def matches?(span)
+        @conditions.all? { |condition| condition.matches?(span) }
+      end
+    end
+  end
+end