opentelemetry-config 0.1.0

data/lib/opentelemetry/config/propagation.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  # Config module — propagation configuration helpers.
+  module Config
+    class << self
+      private
+
+      # Configures the global text-map propagator from the propagator_cfg hash.
+      def configure_propagation(propagator_cfg)
+        return unless propagator_cfg
+
+        propagators = extract_propagator_names(propagator_cfg)
+        return if propagators.empty?
+
+        composite_propagators = propagators.filter_map { |name| resolve_propagator(name) }
+        return if composite_propagators.empty?
+
+        OpenTelemetry::Context::Propagation::CompositeTextMapPropagator.compose_propagators(composite_propagators)
+      end
+
+      # Extracts an ordered, deduplicated list of propagator name strings from
+      # the config. Names from +composite+ come first, then any additional names
+      # from +composite_list+ that were not already included.
+      def extract_propagator_names(cfg)
+        propagators = []
+        Array(cfg.composite).each do |entry|
+          next unless entry
+
+          entry.members.each do |m|
+            next if m == :additional_properties
+
+            propagators << m.to_s if entry[m]
+          end
+          (entry.additional_properties || {}).each_key { |k| propagators << k.to_s }
+        end
+        propagators += cfg.composite_list.split(',').map(&:strip) if cfg.composite_list.is_a?(String)
+        propagators.uniq
+      end
+
+      # Returns a propagator instance for the given name, or nil with a warning.
+      def resolve_propagator(name)
+        case name
+        when 'tracecontext'
+          OpenTelemetry::Trace::Propagation::TraceContext.text_map_propagator
+        when 'baggage'
+          OpenTelemetry::Baggage::Propagation.text_map_propagator
+        when 'b3'
+          const_get_propagator('OpenTelemetry::Propagator::B3::Single')
+        when 'b3multi'
+          const_get_propagator('OpenTelemetry::Propagator::B3::Multi')
+        when 'jaeger'
+          const_get_propagator('OpenTelemetry::Propagator::Jaeger')
+        when 'ottrace'
+          const_get_propagator('OpenTelemetry::Propagator::OTTrace')
+        when 'xray'
+          const_get_propagator('OpenTelemetry::Propagator::XRay')
+        when 'google_cloud_trace_context'
+          const_get_propagator('OpenTelemetry::Propagator::GoogleCloudTraceContext')
+        else
+          OpenTelemetry.logger.warn("Unknown propagator: #{name}")
+          nil
+        end
+      end
+
+      # Looks up a propagator class by fully-qualified name and returns its text_map_propagator.
+      def const_get_propagator(class_name)
+        Kernel.const_get(class_name).text_map_propagator
+      rescue NameError
+        OpenTelemetry.logger.warn("Propagator #{class_name} not available — is the gem installed?")
+        nil
+      end
+    end
+  end
+end

data/lib/opentelemetry/config/resource.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  # Config module — resource configuration helpers.
+  module Config
+    class << self
+      private
+
+      # Priority: attributes > attribute_list > detected > base
+      def build_resource(resource_cfg)
+        base = OpenTelemetry::SDK::Resources::Resource.default
+
+        return base unless resource_cfg
+
+        detected = build_detected_attributes(resource_cfg.detection_development)
+
+        explicit = {}
+        Array(resource_cfg.attributes).each do |attr|
+          next unless attr.name && !attr.value.nil?
+
+          explicit[attr.name] = coerce_attribute_value(attr.value, attr.type)
+        end
+
+        if resource_cfg.attributes_list.is_a?(String)
+          resource_cfg.attributes_list.split(',').each do |pair|
+            key, value = pair.strip.split('=', 2)
+            explicit[key] ||= value if key && value
+          end
+        end
+
+        OpenTelemetry.logger.warn('Config: schema_url is supported; ignoring.') if resource_cfg.schema_url
+
+        attrs = detected.merge(explicit)
+        custom = OpenTelemetry::SDK::Resources::Resource.create(attrs)
+        base.merge(custom)
+      end
+
+      # type coercion
+      def coerce_attribute_value(value, type)
+        case type
+        when 'string'       then value.to_s
+        when 'bool'         then coerce_bool?(value)
+        when 'int'          then Integer(value)
+        when 'double'       then Float(value)
+        when 'string_array' then Array(value).map(&:to_s)
+        when 'bool_array'   then Array(value).map { |v| coerce_bool?(v) }
+        when 'int_array'    then Array(value).map { |v| Integer(v) }
+        when 'double_array' then Array(value).map { |v| Float(v) }
+        else value # no type field → use the YAML-parsed value as-is
+        end
+      end
+
+      def coerce_bool?(value)
+        case value
+        when true,  'true',  1 then true
+        when false, 'false', 0 then false
+        else !!value
+        end
+      end
+
+      # Extract the attributes from an ExperimentalResourceDetection struct.
+      def build_detected_attributes(detection_cfg)
+        return {} unless detection_cfg
+
+        included_patterns = Array(detection_cfg.attributes&.included)
+        excluded_patterns = Array(detection_cfg.attributes&.excluded)
+        detector_names    = detector_names_from(detection_cfg.detectors)
+
+        raw = detector_names.each_with_object({}) do |name, attrs|
+          attrs.merge!(run_detector(name).attribute_enumerator.to_h)
+        end
+
+        # File.fnmatch: * matches any chars except /, so "process.*" covers
+        # "process.pid", "process.runtime.name", etc.
+        raw.select do |key, _|
+          included = included_patterns.empty? || included_patterns.any? { |pat| File.fnmatch(pat, key) }
+          excluded = excluded_patterns.any? { |pat| File.fnmatch(pat, key) }
+          included && !excluded
+        end
+      end
+
+      # Flattens an array of ExperimentalResourceDetector structs into the list
+      # of detector names whose presence flag is set (e.g. container, host).
+      def detector_names_from(detectors)
+        Array(detectors).flat_map do |detector|
+          next [] unless detector
+
+          names = detector.members.filter_map do |m|
+            next if m == :additional_properties
+
+            m.to_s if detector[m]
+          end
+          names + Array(detector.additional_properties&.keys).map(&:to_s)
+        end
+      end
+
+      # Returns a Resource for the given detector name.
+      def run_detector(name)
+        case name
+        when 'container'
+          detect_resource('OpenTelemetry::Resource::Detector::Container')
+        when 'aws'
+          # Run all AWS sub-detectors; each returns an empty resource if not on that platform.
+          detect_resource('OpenTelemetry::Resource::Detector::AWS', %i[ec2 ecs eks lambda])
+        when 'azure'
+          detect_resource('OpenTelemetry::Resource::Detector::Azure')
+        when 'google_cloud_platform'
+          detect_resource('OpenTelemetry::Resource::Detector::GoogleCloudPlatform')
+        else
+          OpenTelemetry.logger.warn("Config: unknown resource detector '#{name}'; skipping.")
+          OpenTelemetry::SDK::Resources::Resource.create({})
+        end
+      end
+
+      # Looks up a resource detector class by fully-qualified name and calls detect.
+      def detect_resource(class_name, *)
+        Kernel.const_get(class_name).detect(*)
+      rescue NameError
+        OpenTelemetry.logger.warn("Config: resource detector '#{class_name}' is not available — is the gem installed?")
+        OpenTelemetry::SDK::Resources::Resource.create({})
+      end
+    end
+  end
+end

data/lib/opentelemetry/config/trace.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Config
+    # Trace component builder for configuring TracerProvider from declarative config.
+    module Trace
+      module_function
+
+      # Builds a TracerProvider from the parsed YAML tracer_provider config.
+      # Returns a noop-configured provider if config is nil.
+      def build_tracer_provider(config, resource)
+        return OpenTelemetry::Trace::TracerProvider.new unless config
+
+        sampler = build_sampler(config.sampler)
+        span_limits = build_span_limits(config.limits)
+
+        tp = OpenTelemetry::SDK::Trace::TracerProvider.new(
+          resource: resource,
+          sampler: sampler,
+          span_limits: span_limits
+        )
+
+        Array(config.processors).each do |proc_cfg|
+          processor = build_span_processor(proc_cfg)
+          tp.add_span_processor(processor) if processor
+        rescue StandardError => e
+          OpenTelemetry.logger.warn("Failed to build span processor: #{e.message}")
+        end
+
+        tp
+      end
+
+      # Builds a span processor (simple or batch) from config hash.
+      def build_span_processor(proc_cfg)
+        raise ArgumentError, 'must not specify multiple span processor type' if proc_cfg.batch && proc_cfg.simple
+
+        if proc_cfg.batch
+          build_batch_span_processor(proc_cfg.batch)
+        elsif proc_cfg.simple
+          build_simple_span_processor(proc_cfg.simple)
+        else
+          raise ArgumentError, 'unsupported span processor type, must be one of simple or batch'
+        end
+      end
+
+      # Builds a BatchSpanProcessor with exporter and optional tuning options.
+      def build_batch_span_processor(cfg)
+        exporter = build_span_exporter(cfg.exporter)
+        opts = {
+          schedule_delay: cfg.schedule_delay&.to_f,
+          exporter_timeout: cfg.export_timeout&.to_f,
+          max_queue_size: cfg.max_queue_size&.to_i,
+          max_export_batch_size: cfg.max_export_batch_size&.to_i
+        }.compact
+
+        OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(exporter, **opts)
+      end
+
+      # Builds a SimpleSpanProcessor wrapping the configured exporter.
+      def build_simple_span_processor(cfg)
+        exporter = build_span_exporter(cfg.exporter)
+        OpenTelemetry::SDK::Trace::Export::SimpleSpanProcessor.new(exporter)
+      end
+
+      # Builds a span exporter from config; supports console and otlp_http.
+      def build_span_exporter(exp_cfg)
+        raise ArgumentError, 'no exporter config' unless exp_cfg
+
+        configured = 0
+        exporter   = nil
+
+        if exp_cfg.console
+          configured += 1
+          exporter = OpenTelemetry::SDK::Trace::Export::ConsoleSpanExporter.new
+        end
+
+        if exp_cfg.otlp_http
+          configured += 1
+          exporter = build_otlp_http_span_exporter(exp_cfg.otlp_http)
+        end
+
+        raise ArgumentError, 'must not specify multiple exporters' if configured > 1
+        raise ArgumentError, 'no valid span exporter'              if exporter.nil?
+
+        exporter
+      end
+
+      # Builds an OTLP HTTP span exporter from the given endpoint/headers config.
+      def build_otlp_http_span_exporter(cfg)
+        headers = headers_to_hash(cfg)
+        opts = {
+          endpoint: cfg.endpoint,
+          headers: headers.empty? ? nil : headers,
+          compression: cfg.compression,
+          timeout: cfg.timeout && (cfg.timeout / 1000.0) # YAML ms → Ruby seconds
+        }.compact
+
+        OpenTelemetry::Exporter::OTLP::Exporter.new(**opts)
+      end
+
+      # Builds a sampler from config; defaults to ParentBased(ALWAYS_ON).
+      def build_sampler(sampler_cfg)
+        s = OpenTelemetry::SDK::Trace::Samplers
+
+        # Default: parent-based with always_on root
+        return s.parent_based(root: s::ALWAYS_ON) unless sampler_cfg
+
+        if sampler_cfg.parent_based
+          build_parent_based_sampler(sampler_cfg.parent_based)
+        elsif sampler_cfg.always_on
+          s::ALWAYS_ON
+        elsif sampler_cfg.always_off
+          s::ALWAYS_OFF
+        elsif sampler_cfg.trace_id_ratio_based
+          ratio = sampler_cfg.trace_id_ratio_based.ratio || 1.0
+          s.trace_id_ratio_based(ratio.to_f)
+        else
+          s.parent_based(root: s::ALWAYS_ON)
+        end
+      end
+
+      # Builds a ParentBased sampler with configurable root and remote/local delegates.
+      def build_parent_based_sampler(cfg)
+        s = OpenTelemetry::SDK::Trace::Samplers
+
+        root = cfg.root ? build_sampler(cfg.root) : s::ALWAYS_ON
+
+        opts = {
+          root: root,
+          remote_parent_sampled: cfg.remote_parent_sampled && build_sampler(cfg.remote_parent_sampled),
+          remote_parent_not_sampled: cfg.remote_parent_not_sampled && build_sampler(cfg.remote_parent_not_sampled),
+          local_parent_sampled: cfg.local_parent_sampled && build_sampler(cfg.local_parent_sampled),
+          local_parent_not_sampled: cfg.local_parent_not_sampled && build_sampler(cfg.local_parent_not_sampled)
+        }.compact
+
+        s.parent_based(**opts)
+      end
+
+      # Builds SpanLimits from config; returns the SDK default when config is nil.
+      def build_span_limits(limits_cfg)
+        return OpenTelemetry::SDK::Trace::SpanLimits::DEFAULT unless limits_cfg
+
+        opts = {
+          attribute_count_limit: limits_cfg.attribute_count_limit,
+          attribute_length_limit: limits_cfg.attribute_value_length_limit,
+          event_count_limit: limits_cfg.event_count_limit,
+          link_count_limit: limits_cfg.link_count_limit,
+          event_attribute_count_limit: limits_cfg.event_attribute_count_limit,
+          link_attribute_count_limit: limits_cfg.link_attribute_count_limit
+        }.compact
+
+        OpenTelemetry::SDK::Trace::SpanLimits.new(**opts)
+      end
+
+      # Converts the OTLP exporter headers (array of NameStringValuePair structs)
+      # into a flat Hash. Falls back to the comma-separated headers_list string.
+      def headers_to_hash(cfg)
+        headers = {}
+
+        Array(cfg.headers).each do |pair|
+          headers[pair.name] = pair.value if pair&.name
+        end
+
+        if headers.empty? && cfg.headers_list.is_a?(String)
+          cfg.headers_list.split(',').each do |entry|
+            key, value = entry.strip.split('=', 2)
+            headers[key] = value if key && value
+          end
+        end
+
+        headers
+      end
+    end
+
+    private_constant :Trace
+  end
+end

data/lib/opentelemetry/config/version.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+# SPDX-License-Identifier: Apache-2.0
+
+module OpenTelemetry
+  module Config
+    VERSION = '0.1.0'
+  end
+end

data/lib/opentelemetry/config.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+# SPDX-License-Identifier: Apache-2.0
+
+require 'date'
+require 'yaml'
+
+require_relative 'config/propagation'
+require_relative 'config/resource'
+require_relative 'config/constants'
+require_relative 'config/trace'
+
+module OpenTelemetry
+  # Config module handles declarative configuration of OpenTelemetry components
+  # from YAML files.
+  module Config
+    ENV_CONFIG_FILE = 'OTEL_CONFIG_FILE'
+    private_constant :ENV_CONFIG_FILE
+
+    class << self
+      # Parses the file referenced by +OTEL_CONFIG_FILE+, creates the components
+      # it describes, and installs them as the global OpenTelemetry state.
+      #
+      # @return [RubySDK] the installed SDK handle
+      def configure
+        install(create(parse(ENV.fetch(ENV_CONFIG_FILE, nil))))
+      end
+
+      # Same as {configure}, but reads the configuration from an explicit path.
+      #
+      # @param path [String] path to a declarative configuration YAML file
+      # @return [RubySDK] the installed SDK handle
+      def configure_from_file(path)
+        install(create(parse(path)))
+      end
+
+      # Parses a declarative configuration file into the configuration model.
+      #
+      # @param path [String, nil] path to a declarative configuration YAML file
+      # @return [Model::OpenTelemetryConfiguration, nil] nil when the file is
+      #   unset, missing, or invalid
+      def parse(path)
+        if path.to_s.empty?
+          OpenTelemetry.logger.info('No OTEL_CONFIG_FILE defined.')
+          return nil
+        end
+
+        content = File.read(path)
+        OpenTelemetry::Config::Model::OpenTelemetryConfiguration.from_hash(YAML.safe_load(content, permitted_classes: [Date, Time]))
+      rescue Errno::ENOENT => e
+        OpenTelemetry.logger.error("Config file not found: #{e.message}")
+        nil
+      rescue Psych::SyntaxError => e
+        OpenTelemetry.logger.error("YAML parse error: #{e.message}")
+        nil
+      end
+
+      # Creates the components described by a configuration model without
+      # modifying global OpenTelemetry state.
+      #
+      # @param config [Model::OpenTelemetryConfiguration, nil]
+      # @return [RubySDK] {NOOP_SDK} when the configuration is absent, invalid,
+      #   disabled, or opentelemetry-sdk isn't loaded
+      def create(config)
+        return NOOP_SDK if config.nil?
+
+        unless defined?(OpenTelemetry::SDK)
+          warn '[opentelemetry-config] opentelemetry-sdk is not loaded. ' \
+               'Add `gem "opentelemetry-sdk"` to your Gemfile.'
+          return NOOP_SDK
+        end
+
+        if config.disabled
+          OpenTelemetry.logger.info('OpenTelemetry SDK disabled by configuration.')
+          return NOOP_SDK
+        end
+
+        resource = build_resource(config.resource)
+
+        # tracer_provider will be noop if opentelemetry-sdk is not installed
+        tracer_provider = Trace.build_tracer_provider(config.tracer_provider, resource)
+
+        propagators = configure_propagation(config.propagator)
+
+        RubySDK.new(
+          tracer_provider: tracer_provider,
+          propagator: propagators,
+          resource: resource
+        )
+      end
+
+      # Assigns the components of a RubySDK to the global OpenTelemetry state.
+      # NOOP_SDK will skip installation and leave the global state untouched.
+      #
+      # @param ruby_sdk [RubySDK]
+      # @return [RubySDK] the same SDK handle
+      def install(ruby_sdk)
+        return ruby_sdk if ruby_sdk.equal?(NOOP_SDK)
+
+        OpenTelemetry.tracer_provider = ruby_sdk.tracer_provider if ruby_sdk.tracer_provider
+        OpenTelemetry.propagation = ruby_sdk.propagator if ruby_sdk.propagator
+        ruby_sdk
+      end
+    end
+  end
+end

data/lib/opentelemetry-config.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Copyright The OpenTelemetry Authors
+# SPDX-License-Identifier: Apache-2.0
+
+require 'opentelemetry/config'

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification
+name: opentelemetry-config
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- OpenTelemetry Authors
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-api
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.11.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.11.0
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-common
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.25'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.25'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-exporter-otlp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.34.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.34.1
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-sdk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.13.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.13.0
+email:
+- cncf-opentelemetry-contributors@lists.cncf.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".yardopts"
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/opentelemetry-config.rb
+- lib/opentelemetry/config.rb
+- lib/opentelemetry/config/constants.rb
+- lib/opentelemetry/config/generated_constants.rb
+- lib/opentelemetry/config/propagation.rb
+- lib/opentelemetry/config/resource.rb
+- lib/opentelemetry/config/trace.rb
+- lib/opentelemetry/config/version.rb
+homepage: https://github.com/open-telemetry/opentelemetry-ruby
+licenses:
+- Apache-2.0
+metadata:
+  changelog_uri: https://rubydoc.info/gems/opentelemetry-config/0.1.0/file/CHANGELOG.md
+  source_code_uri: https://github.com/open-telemetry/opentelemetry-ruby/tree/opentelemetry-config/v0.1.0/config
+  bug_tracker_uri: https://github.com/open-telemetry/opentelemetry-ruby/issues
+  documentation_uri: https://rubydoc.info/gems/opentelemetry-config/0.1.0
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Declarative Config implementation for OpenTelemetry
+test_files: []