dash0-opentelemetry 0.1.0

data/lib/dash0/opentelemetry/instrumentation_installer.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright 2026 Dash0 Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+module Dash0
+  module OpenTelemetry
+    # Installs per-library instrumentation lazily via a `TracePoint(:end)`: an
+    # initial sweep for already-loaded libraries, then a re-sweep each time a class
+    # or module finishes being defined, so a library loaded after us is still
+    # caught.
+    #
+    # Ported, with light adaptation, from the upstream
+    # `opentelemetry-auto-instrumentation` gem's `OTelInitializer`
+    # (open-telemetry/opentelemetry-ruby-instrumentation), Apache-2.0.
+    module InstrumentationInstaller
+      @mutex = Mutex.new
+      @trace_point = nil
+
+      class << self
+        # Sweeps once for already-loaded libraries, then — unless everything
+        # relevant is already installed — installs a TracePoint(:end) that
+        # re-sweeps whenever a class or module finishes being defined.
+        #
+        # @param [Array<String>] enabled_names canonical instrumentation names to
+        #   restrict installation to; empty means "all registered".
+        def start(enabled_names = enabled_instrumentation_names)
+          sweep(enabled_names)
+          return if relevant_instrumentations(enabled_names).all?(&:installed?)
+
+          @trace_point = TracePoint.new(:end) { sweep(enabled_names) }
+          @trace_point.enable
+        end
+
+        # Exposed for testing/inspection.
+        attr_reader :trace_point
+
+        # Returns the canonical instrumentation names enabled via
+        # OTEL_RUBY_ENABLED_INSTRUMENTATIONS, or [] when the variable is unset
+        # (meaning: install everything registered).
+        def enabled_instrumentation_names
+          raw = ENV['OTEL_RUBY_ENABLED_INSTRUMENTATIONS'].to_s
+          return [] if raw.strip.empty?
+
+          lookup = registry_lookup
+          raw.split(',').filter_map do |entry|
+            normalized = entry.strip.downcase
+            canonical = lookup[normalized]
+            if canonical.nil? && ENV['DASH0_DEBUG'] == 'true'
+              warn "#{Dash0::OpenTelemetry::LOG_PREFIX} Unknown instrumentation '#{entry.strip}'"
+            end
+            canonical
+          end
+        end
+
+        private
+
+        # Installs every relevant instrumentation that is installable right now.
+        def sweep(enabled_names)
+          @mutex.synchronize do
+            ready = relevant_instrumentations(enabled_names).select do |instrumentation|
+              ready_to_install?(instrumentation)
+            end
+            ::OpenTelemetry::Instrumentation.registry.install(ready.map(&:name)) unless ready.empty?
+          end
+        rescue StandardError => e
+          if ENV['DASH0_DEBUG'] == 'true'
+            warn "#{Dash0::OpenTelemetry::LOG_PREFIX} instrumentation sweep failed: #{e.message}"
+          end
+        end
+
+        # Whether this instrumentation is installable right now.
+        def ready_to_install?(instrumentation)
+          return false if instrumentation.installed?
+
+          instrumentation.present? && instrumentation.enabled? && instrumentation.compatible?
+        rescue StandardError, ScriptError
+          false
+        end
+
+        # The instrumentation instances this process should install: those named by
+        # +enabled_names+, or every registered instrumentation when +enabled_names+
+        # is empty.
+        def relevant_instrumentations(enabled_names)
+          registry = ::OpenTelemetry::Instrumentation.registry
+          if enabled_names.empty?
+            registry_instrumentation_classes.map(&:instance)
+          else
+            enabled_names.filter_map { |name| registry.lookup(name) }
+          end
+        rescue StandardError
+          []
+        end
+
+        # All instrumentation classes registered in the OpenTelemetry registry. The
+        # registry only exposes lookup/install publicly, so enumerate its internal
+        # collection to derive the supported set.
+        def registry_instrumentation_classes
+          registry = ::OpenTelemetry::Instrumentation.registry
+          registry.instance_variable_get(:@instrumentation) || []
+        rescue StandardError
+          []
+        end
+
+        # Builds and caches a hash mapping alias names (snake_case, no prefix) to
+        # canonical instrumentation names.
+        def registry_lookup
+          @registry_lookup ||= registry_instrumentation_classes.each_with_object({}) do |klass, lookup|
+            canonical = klass.instance.name
+            registry_aliases_for(canonical).each do |alias_name|
+              lookup[alias_name] ||= canonical
+            end
+          rescue StandardError
+            next
+          end
+        end
+
+        # All snake_case alias strings for a fully-qualified instrumentation name,
+        # e.g. "OpenTelemetry::Instrumentation::Net::HTTP" => ["net_http", ...].
+        def registry_aliases_for(instrumentation_name)
+          suffix = instrumentation_name.delete_prefix('OpenTelemetry::Instrumentation::')
+          segment_variants = suffix.split('::').map do |segment|
+            [snake_case(segment), segment.downcase].uniq
+          end
+
+          segment_variants.reduce(['']) do |aliases, variants|
+            aliases.flat_map do |prefix|
+              variants.map { |variant| prefix.empty? ? variant : "#{prefix}_#{variant}" }
+            end
+          end
+        end
+
+        def snake_case(value)
+          value
+            .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+            .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+            .tr('-', '_')
+            .downcase
+        end
+      end
+    end
+  end
+end

data/lib/dash0/opentelemetry/lifecycle.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright 2026 Dash0 Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+module Dash0
+  module OpenTelemetry
+    # Process-lifecycle concerns: an optional bootstrap span at startup, and
+    # graceful flushing of pending telemetry on shutdown.
+    module Lifecycle
+      BOOTSTRAP_SPAN_ENV = 'DASH0_BOOTSTRAP_SPAN'
+      FLUSH_ON_SIGNALS_ENV = 'DASH0_FLUSH_ON_SIGTERM_SIGINT'
+      FLUSH_ON_EXIT_ENV = 'DASH0_FLUSH_ON_EXIT'
+
+      # Name of the tracer used for the bootstrap span.
+      BOOTSTRAP_TRACER = 'dash0-ruby-distribution'
+
+      # Per-provider shutdown timeout (seconds). Bounds how long process exit can
+      # block flushing telemetry to a slow or unreachable collector.
+      SHUTDOWN_TIMEOUT_SECONDS = 2.0
+
+      # Signals whose default action would otherwise terminate the process without
+      # running `at_exit`, so we flush explicitly before re-raising.
+      FLUSH_SIGNALS = %w[TERM INT].freeze
+
+      @shutdown_mutex = Mutex.new
+      @shutdown_done = false
+
+      class << self
+        # Installs the configured lifecycle behaviors. Called once, after the SDK
+        # has been configured.
+        def install
+          name = bootstrap_span_name
+          create_bootstrap_span(name) if name
+          install_signal_handlers if flush_on_signals?
+          install_exit_handler if flush_on_exit?
+        end
+
+        # Gracefully shuts down the tracer, meter, and logger providers, flushing
+        # pending telemetry. Idempotent: only the first call performs the shutdown.
+        def shutdown
+          @shutdown_mutex.synchronize do
+            return if @shutdown_done
+
+            @shutdown_done = true
+          end
+
+          providers.each do |provider|
+            provider.shutdown(timeout: SHUTDOWN_TIMEOUT_SECONDS)
+          rescue StandardError => e
+            Dash0::OpenTelemetry.log_debug("Error during provider shutdown: #{e.message}")
+          end
+        end
+
+        def shutdown?
+          @shutdown_done
+        end
+
+        # Resets the one-time shutdown guard. Intended for tests only.
+        def reset_for_testing!
+          @shutdown_done = false
+        end
+
+        private
+
+        def bootstrap_span_name
+          Environment.present?(BOOTSTRAP_SPAN_ENV) ? ENV.fetch(BOOTSTRAP_SPAN_ENV).strip : nil
+        end
+
+        def flush_on_signals?
+          Environment.opted_in?(FLUSH_ON_SIGNALS_ENV)
+        end
+
+        # On by default; disabled only by an explicit opt-out.
+        def flush_on_exit?
+          !Environment.opted_out?(FLUSH_ON_EXIT_ENV)
+        end
+
+        def create_bootstrap_span(name)
+          ::OpenTelemetry.tracer_provider.tracer(BOOTSTRAP_TRACER).in_span(name, kind: :internal) { nil }
+        rescue StandardError => e
+          Dash0::OpenTelemetry.log_debug("Could not create bootstrap span: #{e.message}")
+        end
+
+        # Installs SIGTERM/SIGINT handlers that flush, then re-raise the signal so
+        # the process terminates with the expected disposition. The shutdown runs
+        # in a fresh thread because a signal trap runs in a restricted context
+        # where acquiring the SDK's mutexes would raise; a thread body escapes it.
+        #
+        # Signal handlers can only be installed from the main thread; if we are not
+        # on it, skip them rather than raise (the at-exit flush still applies).
+        def install_signal_handlers
+          return unless Thread.current == Thread.main
+
+          FLUSH_SIGNALS.each do |signal|
+            Signal.trap(signal) do
+              Thread.new { shutdown }.join
+              Signal.trap(signal, 'DEFAULT')
+              Process.kill(signal, Process.pid)
+            end
+          end
+        rescue ArgumentError => e
+          Dash0::OpenTelemetry.log_debug("Could not install signal handlers: #{e.message}")
+        end
+
+        def install_exit_handler
+          at_exit { shutdown }
+        end
+
+        # The configured SDK providers that can be shut down. When a signal's SDK
+        # is not installed, `OpenTelemetry` may not define the accessor at all, and
+        # API no-op providers do not respond to `shutdown`; both are skipped.
+        def providers
+          %i[tracer_provider meter_provider logger_provider].filter_map do |name|
+            next unless ::OpenTelemetry.respond_to?(name)
+
+            provider = ::OpenTelemetry.public_send(name)
+            provider if provider.respond_to?(:shutdown)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/dash0/opentelemetry/resource/distribution.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright 2026 Dash0 Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+module Dash0
+  module OpenTelemetry
+    module Resource
+      # Resource detector that identifies this distribution via the
+      # `telemetry.distro.*` resource attributes.
+      #
+      # `OpenTelemetry::SDK` must be loaded before this is called.
+      module Distribution
+        # Value of the `telemetry.distro.name` resource attribute.
+        NAME = 'dash0-ruby'
+
+        module_function
+
+        def detect
+          ::OpenTelemetry::SDK::Resources::Resource.create(
+            'telemetry.distro.name' => NAME,
+            'telemetry.distro.version' => Dash0::OpenTelemetry::VERSION
+          )
+        end
+      end
+    end
+  end
+end

data/lib/dash0/opentelemetry/resource/kubernetes_pod.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright 2026 Dash0 Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+module Dash0
+  module OpenTelemetry
+    module Resource
+      # Resource detector that derives `k8s.pod.uid` by parsing cgroup files,
+      # gated on an `/etc/hosts` marker that indicates a Kubernetes-managed
+      # environment. Ported from the Node.js distribution's
+      # `opentelemetry-resource-detector-kubernetes-pod`.
+      #
+      # `OpenTelemetry::SDK` must be loaded before `detect` is called.
+      module KubernetesPod
+        ETC_HOSTS_FILE = '/etc/hosts'
+        EXPECTED_FIRST_LINE_IN_ETC_HOSTS = '# Kubernetes-managed hosts file'
+
+        POD_UID_CHARS = 36
+        POD_LABEL = 'pod'
+        POD_LABEL_MOUNT_PART = '/pods/'
+        POD_UID_PART_CHARS = POD_UID_CHARS + POD_LABEL.length # "pod" + 36-char uid
+        CONTAINER_ID_CHARS = 64
+
+        # cgroup v1
+        PROC_SELF_MOUNTINFO_FILE = '/proc/self/mountinfo'
+        # cgroup v2
+        PROC_SELF_CGROUP_FILE = '/proc/self/cgroup'
+
+        # Matches slice names like "kubepods-pode462ffed_94ce_4806_a52e_d2726f448f15.slice".
+        POD_UID_IN_CGROUP_LINE_REGEX =
+          /\A[a-z_-]*pod(?<uid>[0-9a-f]{8}[-_][0-9a-f]{4}[-_][0-9a-f]{4}[-_][0-9a-f]{4}[-_][0-9a-f]{12})\.slice\z/
+
+        extend self
+
+        # The detector interface: the only public method.
+        def detect
+          attributes = {}
+          uid = pod_uid
+          attributes['k8s.pod.uid'] = uid if uid
+          ::OpenTelemetry::SDK::Resources::Resource.create(attributes)
+        end
+
+        private
+
+        # @return [String, nil] the pod uid, or nil when not on Kubernetes or not
+        #   determinable.
+        def pod_uid
+          return nil unless kubernetes?
+
+          pod_uid_from_cgroup_v1(candidate_lines(read_file(PROC_SELF_MOUNTINFO_FILE), POD_UID_CHARS)) ||
+            pod_uid_from_cgroup_v2(candidate_lines(read_file(PROC_SELF_CGROUP_FILE), CONTAINER_ID_CHARS))
+        end
+
+        def kubernetes?
+          kubernetes_managed_hosts?(read_file(ETC_HOSTS_FILE))
+        end
+
+        def kubernetes_managed_hosts?(content)
+          return false if content.nil? || content.strip.empty?
+
+          first_line = content.split("\n").first
+          !first_line.nil? && first_line.start_with?(EXPECTED_FIRST_LINE_IN_ETC_HOSTS)
+        end
+
+        # cgroup v1: a mountinfo line containing "/pods/" followed by the 36-char uid.
+        def pod_uid_from_cgroup_v1(lines)
+          mount = lines.find do |line|
+            index = line.index(POD_LABEL_MOUNT_PART)
+            index&.positive?
+          end
+          return nil unless mount
+
+          part_after_pod_label = mount.split(POD_LABEL_MOUNT_PART)[1]
+          return nil if part_after_pod_label.nil? || part_after_pod_label.empty?
+
+          part_after_pod_label[0, POD_UID_CHARS]
+        end
+
+        # cgroup v2: the penultimate "/"-separated segment of a cgroup line, either
+        # "pod<uid>" or a "…pod<uid>.slice" name (with "_" normalized to "-").
+        def pod_uid_from_cgroup_v2(lines)
+          lines.each do |line|
+            segments = line.split('/')
+            next if segments.length <= 2
+
+            penultimate = segments[-2]
+            uid = pod_uid_from_segment(penultimate)
+            return uid if uid
+          end
+          nil
+        end
+
+        def pod_uid_from_segment(segment)
+          if segment.start_with?(POD_LABEL) && segment.length == POD_UID_PART_CHARS
+            segment[POD_LABEL.length, POD_UID_CHARS]
+          elsif (match = POD_UID_IN_CGROUP_LINE_REGEX.match(segment))
+            match[:uid].tr('_', '-')
+          else
+            # Questionable: this may extract a wrong uid, but mirrors upstream's
+            # last-resort behavior.
+            segment
+          end
+        end
+
+        def candidate_lines(content, minimum_length)
+          return [] if content.nil? || content.empty?
+
+          content.split("\n").map(&:strip).select { |line| line.length > minimum_length }
+        end
+
+        def read_file(filename)
+          File.read(filename, encoding: 'utf-8')
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/dash0/opentelemetry/resource/service_name_fallback.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright 2026 Dash0 Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+module Dash0
+  module OpenTelemetry
+    module Resource
+      # Resource detector that provides a fallback `service.name` when none has
+      # been configured, derived from the application's own identity.
+      #
+      # Because the distribution boots at interpreter startup via `RUBYOPT`, the
+      # program name is usually the wrapper the container runs (`bundle`, `puma`,
+      # `rackup`), not the application. Sampling that would report every Ruby
+      # service under the same meaningless name, so instead we read the app's
+      # identity from its project files, best signal first:
+      #
+      #   1. `config/application.rb` / `config/app.rb` `module <Name>` — Rails, Hanami
+      #   2. `config.ru` — the `run <AppClass>` target or an inline app class
+      #      (modular Sinatra, Roda, plain Rack, single-file Rails)
+      #   3. the entry script name, when it is not a known wrapper
+      #
+      # When none of these yields a name (e.g. a classic Sinatra app run through a
+      # wrapper), we return nil and let the SDK's `unknown_service` stand — honest
+      # absence beats a wrapper's name.
+      #
+      # The fallback is skipped when a service name is already configured via
+      # `OTEL_SERVICE_NAME` or a `service.name` in `OTEL_RESOURCE_ATTRIBUTES`, or
+      # when opted out with `DASH0_AUTOMATIC_SERVICE_NAME=false`.
+      #
+      # `OpenTelemetry::SDK` must be loaded before `detect` is called.
+      module ServiceNameFallback
+        AUTOMATIC_SERVICE_NAME_ENV = 'DASH0_AUTOMATIC_SERVICE_NAME'
+        SERVICE_NAME_KEY = 'service.name'
+
+        # Files whose top-level `module <Name>` names the application (Rails, Hanami).
+        APP_MODULE_FILES = ['config/application.rb', 'config/app.rb'].freeze
+        CONFIG_RU = 'config.ru'
+        # Any of these in a directory marks it as a plausible application root.
+        PROJECT_MARKERS = (APP_MODULE_FILES + [CONFIG_RU, 'Gemfile']).freeze
+        # How far up from the working directory to look for the application root.
+        MAX_ROOT_WALK = 4
+        # Config files are tiny; cap the read so a pathological file can't stall boot.
+        MAX_CONFIG_BYTES = 64 * 1024
+
+        # Program names that are wrappers/launchers rather than the application, so
+        # they carry no service identity and must not be used as a name.
+        WRAPPER_EXECUTABLES = %w[
+          bundle bundler rake rackup ruby irb spring rails
+          puma unicorn thin falcon sidekiq resque foreman
+        ].freeze
+
+        # A `run <X>` / `class < <X>` target whose leading constant is one of these
+        # is a framework generic (`run Rails.application`, `run Sinatra::Application`),
+        # not the app's own name, so it is not a usable signal.
+        FRAMEWORK_GENERICS = %w[Rails Sinatra Hanami Rack].freeze
+
+        extend self
+
+        # The detector interface: the only public method.
+        def detect
+          attributes = {}
+          name = fallback_service_name
+          attributes[SERVICE_NAME_KEY] = name if name
+          ::OpenTelemetry::SDK::Resources::Resource.create(attributes)
+        end
+
+        private
+
+        # @return [String, nil] the derived service name, or nil when a name is
+        #   already configured, the fallback is opted out, or none can be derived.
+        def fallback_service_name(program_name = $PROGRAM_NAME, root = app_root)
+          return nil if service_name_configured?
+
+          name_from_project(root) || derive_from_program_name(program_name)
+        end
+
+        def name_from_project(root)
+          return nil unless root
+
+          derive_from_app_module(root) || derive_from_config_ru(root)
+        end
+
+        # Rails/Hanami: the top-level `module <Name>` in the app's config file.
+        def derive_from_app_module(root)
+          APP_MODULE_FILES.each do |relative_path|
+            source = read_project_file(root, relative_path)
+            next unless source
+
+            match = source.match(/^module\s+([A-Z]\w*)/)
+            return underscore(match[1]) if match
+          end
+          nil
+        end
+
+        # config.ru: an inline app class (single-file Rails, inline Sinatra) or the
+        # `run <AppClass>` target. Framework generics (`Rails.application`,
+        # `Sinatra::Application`) carry no identity and are skipped.
+        def derive_from_config_ru(root)
+          source = read_project_file(root, CONFIG_RU)
+          return nil unless source
+
+          inline = source.match(/^\s*class\s+([A-Z]\w*)\s*<\s*(?:Rails::Application|Sinatra::(?:Base|Application))/)
+          return underscore(inline[1]) if inline
+
+          run_target = source.match(/^\s*run\s+\(?\s*([A-Z]\w*(?:::[A-Z]\w*)*)/)
+          if run_target && !FRAMEWORK_GENERICS.include?(run_target[1].split('::').first)
+            return underscore(run_target[1])
+          end
+
+          nil
+        end
+
+        def derive_from_program_name(program_name)
+          return nil if program_name.nil?
+
+          name = File.basename(program_name.to_s).delete_suffix('.rb')
+          return nil if name.empty? || WRAPPER_EXECUTABLES.include?(name)
+
+          name
+        end
+
+        # Walks up from the working directory to the nearest ancestor that looks
+        # like an application root, or nil if none is found within MAX_ROOT_WALK.
+        def app_root(start = Dir.pwd)
+          dir = File.expand_path(start)
+          MAX_ROOT_WALK.times do
+            return dir if PROJECT_MARKERS.any? { |marker| File.readable?(File.join(dir, marker)) }
+
+            parent = File.dirname(dir)
+            break if parent == dir
+
+            dir = parent
+          end
+          nil
+        rescue StandardError
+          nil
+        end
+
+        def read_project_file(root, relative_path)
+          path = File.join(root, relative_path)
+          return nil unless File.readable?(path)
+
+          File.read(path, MAX_CONFIG_BYTES)
+        rescue StandardError
+          nil
+        end
+
+        # CamelCase / namespaced constant to snake_case: DemoApp -> demo_app,
+        # CheckoutAPI -> checkout_api, MyApp::Web -> my_app_web.
+        def underscore(name)
+          name
+            .gsub('::', '_')
+            .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+            .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+            .tr('-', '_')
+            .downcase
+        end
+
+        def service_name_configured?
+          opted_out? || otel_service_name_set? || service_name_in_resource_attributes?
+        end
+
+        def opted_out?
+          Environment.opted_out?(AUTOMATIC_SERVICE_NAME_ENV)
+        end
+
+        def otel_service_name_set?
+          Environment.present?('OTEL_SERVICE_NAME')
+        end
+
+        # Parses OTEL_RESOURCE_ATTRIBUTES the same way the upstream env detector
+        # does, stripping surrounding quotes, to see if a non-empty service.name
+        # is present.
+        def service_name_in_resource_attributes?
+          raw = ENV.fetch('OTEL_RESOURCE_ATTRIBUTES', nil)
+          return false if raw.nil? || raw.strip.empty?
+
+          raw.split(',').any? do |pair|
+            key, value = pair.split('=', 2)
+            next false unless value && key.strip == SERVICE_NAME_KEY
+
+            !value.strip.gsub(/\A"|"\z/, '').strip.empty?
+          end
+        end
+      end
+    end
+  end
+end