instana 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 35cfa89077e641cdd3e6fb0a97008f1e10ad7b703dc5b2b79e90a383dfc30099
-  data.tar.gz: dd9b39744a6432f619e496c759da84bffdfe114824bef0bbbcea155dbef3a284
+  metadata.gz: ca8072a81b44cce54a3a2db8ef236038fa4814226c714e88f12285ea952eede4
+  data.tar.gz: 6f3b666908eb9442c1a8e6d3d1b9a332576bb818810a2c588df4de2232c1b65a
 SHA512:
-  metadata.gz: 47d8317281da1f8ae6adb6f740055d4845f125da6ccac65ce03ff68e4efc9a1eb22530f62571ef12bad952866832d99076b1ba4d62a6c876d0aaf4ab3b9c6ae5
-  data.tar.gz: bc463f59a0662b0fe8ff5e34996631b1ed01215ef22e8f16781e7a249936e602959c1fecba74a3fe42e0c718f0ed37a4c62aa732c3b0f37f92cb49d9472e1e6f
+  metadata.gz: 84861f4a775983202c19731ce78302bf5e7cfd677591bf9b42014be4dee8b93efd1e6606910f756bbba495584a932ac860eb76cad5cf6539202d0588c3c01592
+  data.tar.gz: ab26f124f9e087501046f56645649aed9b077ee656120d99ac1c375f44552f92345e338c1d5495c28e4a1959a7c459bf652511e13031912812a1acef003ca3f3

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

data/lib/instana/span_filtering.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# (c) Copyright IBM Corp. 2025
+
+require 'instana/span_filtering/configuration'
+require 'instana/span_filtering/filter_rule'
+require 'instana/span_filtering/condition'
+
+module Instana
+  # SpanFiltering module provides functionality to filter spans based on configured rules
+  module SpanFiltering
+    class << self
+      attr_reader :configuration
+
+      # Initialize the span filtering configuration
+      # @return [Configuration] The span filtering configuration
+      def initialize
+        @configuration = Configuration.new
+      end
+
+      # Check if span filtering is deactivated
+      # @return [Boolean] True if span filtering is deactivated
+      def deactivated?
+        @configuration&.deactivated || false
+      end
+
+      # Check if a span should be filtered out
+      # @param span [Hash] The span to check
+      # @return [Hash, nil] A result hash with filtered and suppression keys if filtered, nil if not filtered
+      def filter_span(span)
+        return nil if deactivated?
+        return nil unless @configuration
+
+        # Check include rules first (whitelist)
+        if @configuration.include_rules.any?
+          # If we have include rules, only keep spans that match at least one include rule
+          unless @configuration.include_rules.any? { |rule| rule.matches?(span) }
+            return { filtered: true, suppression: false }
+          end
+          # If it matches an include rule, continue to exclude rules
+        end
+
+        # Check exclude rules (blacklist)
+        @configuration.exclude_rules.each do |rule|
+          if rule.matches?(span)
+            return { filtered: true, suppression: rule.suppression }
+          end
+        end
+
+        nil # Keep the span if no rules match
+      end
+
+      # Reset the configuration (mainly for testing)
+      def reset
+        @configuration = nil
+      end
+    end
+
+    # Initialize on module load
+    initialize
+  end
+end

data/lib/instana/trace/span.rb

@@ -159,15 +159,17 @@ module Instana
     # @return [Span]
     #
     def close(end_time = ::Instana::Util.now_in_ms)
+      result = ::Instana::SpanFiltering.filter_span(self)
       if end_time.is_a?(Time)
         end_time = ::Instana::Util.time_to_ms(end_time)
       end
-
       @attributes[:d] = end_time - @attributes[:ts]
       @ended = true
-      # Add this span to the queue for reporting
-      ::Instana.processor.on_finish(self)
 
+      if result.nil?
+        # Add this span to the queue for reporting
+        ::Instana.processor.on_finish(self)
+      end
       self
     end
 

data/lib/instana/version.rb

@@ -2,6 +2,6 @@
 # (c) Copyright Instana Inc. 2016
 
 module Instana
-  VERSION = "2.0.0"
+  VERSION = "2.1.0"
   VERSION_FULL = "instana-#{VERSION}"
 end