dash0-opentelemetry 0.1.0

data/lib/dash0/opentelemetry/sdk_configuration.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright 2026 Dash0 Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+module Dash0
+  module OpenTelemetry
+    # Configures the OpenTelemetry SDK with Dash0 defaults. Leans on the Ruby
+    # SDK's env-driven configurator: once the endpoint/protocol defaults are set
+    # and the exporter gems are required, `OpenTelemetry::SDK.configure` wires
+    # up the OTLP exporters and processors from the environment. We own the
+    # resource. Traces, metrics, and logs are all exported over OTLP/HTTP-protobuf
+    # to the same collector base URL (`/v1/traces`, `/v1/metrics`, `/v1/logs`).
+    #
+    # Metrics and logs support activates simply by requiring their SDK gems: they
+    # prepend `ConfiguratorPatch` modules that fill in the otherwise-empty
+    # metrics/logs configuration hooks the base SDK calls during `configure`.
+    module SdkConfiguration
+      # OTLP is only supported over HTTP/protobuf in the Ruby SDK's default path.
+      DEFAULT_PROTOCOL = 'http/protobuf'
+
+      # DASH0_DEBUG_PRINT_SPANS=true additionally prints every span to stdout.
+      DEBUG_PRINT_SPANS_ENV = 'DASH0_DEBUG_PRINT_SPANS'
+
+      # When the operator/injector mounts a Bundler-less gem bundle, its path is
+      # exposed here and the distribution is responsible for putting the bundled
+      # gems on the load path itself.
+      ADDITIONAL_GEM_PATH_ENV = 'OTEL_RUBY_ADDITIONAL_GEM_PATH'
+
+      # Comma-separated allowlist gems to NOT put on the load path (see
+      # #disallowed_lib_names). Mirrors the upstream env var.
+      DISALLOWED_LIB_PATH_ENV = 'DISALLOWED_LIB_PATH'
+
+      # Non-`opentelemetry-*` gems from the bundle that the SDK closure requires at
+      # load time and must therefore be on the load path: the OTLP exporter's
+      # protobuf deps, plus `logger` (required by `opentelemetry-api`; a default gem
+      # today, but a bundled gem from Ruby 4.0, at which point requiring it without
+      # this entry would fail). Kept minimal to avoid shadowing the app's own gems.
+      ADDITIONAL_LIB_GEM_ALLOWLIST = %w[googleapis-common-protos-types google-protobuf logger].freeze
+
+      module_function
+
+      # @param base_url [String] the Dash0 collector base URL. The generic
+      #   `OTEL_EXPORTER_OTLP_ENDPOINT` is used (not a signal-specific variable),
+      #   so each exporter appends its own `/v1/{traces,metrics,logs}` path.
+      def apply(base_url:)
+        configure_exporter_defaults(base_url)
+        require_sdk_gems
+        resource = build_resource
+
+        ::OpenTelemetry::SDK.configure do |c|
+          c.resource = resource
+        end
+
+        install_debug_span_printer if Environment.opted_in?(DEBUG_PRINT_SPANS_ENV)
+      end
+
+      def configure_exporter_defaults(base_url)
+        Environment.set_default('OTEL_EXPORTER_OTLP_ENDPOINT', base_url)
+        Environment.set_default('OTEL_EXPORTER_OTLP_PROTOCOL', DEFAULT_PROTOCOL)
+      end
+
+      def require_sdk_gems
+        wire_additional_gem_path
+        require 'opentelemetry-sdk'
+        require 'opentelemetry-metrics-sdk'
+        require 'opentelemetry-logs-sdk'
+        require 'opentelemetry-exporter-otlp'
+        require 'opentelemetry-exporter-otlp-metrics'
+        require 'opentelemetry-exporter-otlp-logs'
+        require 'opentelemetry-resource-detector-container'
+        # Populate the instrumentation registry so the installer can sweep it.
+        require 'opentelemetry-instrumentation-all'
+      end
+
+      # In the injected (Bundler-less) environment the OpenTelemetry gems live only
+      # under OTEL_RUBY_ADDITIONAL_GEM_PATH; put their `lib` directories on the load
+      # path so the requires above resolve. A no-op when the variable is unset
+      # (e.g. running under Bundler, where the gems are already resolvable).
+      def wire_additional_gem_path
+        gem_path = ENV.fetch(ADDITIONAL_GEM_PATH_ENV, nil)
+        return if gem_path.nil? || !Dir.exist?(gem_path)
+
+        allowlist = ADDITIONAL_LIB_GEM_ALLOWLIST - disallowed_lib_names
+        Dir.glob(File.join(gem_path, 'gems', '*')).each do |gem_dir|
+          next unless on_load_path?(File.basename(gem_dir), allowlist)
+
+          lib = File.join(gem_dir, 'lib')
+          $LOAD_PATH.unshift(lib) if Dir.exist?(lib) && !$LOAD_PATH.include?(lib)
+        end
+      end
+
+      # Gems opted out of via DISALLOWED_LIB_PATH (comma-separated).
+      def disallowed_lib_names
+        ENV.fetch(DISALLOWED_LIB_PATH_ENV, '').split(',').map(&:strip).reject(&:empty?)
+      end
+
+      def on_load_path?(gem_dir_name, allowlist)
+        gem_dir_name.start_with?('opentelemetry-') ||
+          allowlist.any? { |name| gem_dir_name.start_with?("#{name}-") }
+      end
+
+      # Adds a console span exporter *after* configure. It must not be added inside
+      # the configure block: the SDK configurator only builds the env-driven OTLP
+      # exporter when no span processor was registered manually, so adding one
+      # there would silently disable OTLP export. Appending to the already-built
+      # provider keeps OTLP and adds console output alongside it.
+      def install_debug_span_printer
+        ::OpenTelemetry.tracer_provider.add_span_processor(
+          ::OpenTelemetry::SDK::Trace::Export::SimpleSpanProcessor.new(
+            ::OpenTelemetry::SDK::Trace::Export::ConsoleSpanExporter.new
+          )
+        )
+      end
+
+      # Builds the resource merged onto the SDK's default resource (process, SDK,
+      # and service-name-from-env attributes) by the configurator. Beyond the
+      # distro identity, this runs the upstream container detector plus the two
+      # custom Dash0 detectors. On key conflicts the later `merge` argument wins;
+      # distro attributes are applied last so they always take effect.
+      def build_resource
+        ::OpenTelemetry::SDK::Resources::Resource.create({})
+                                                 .merge(::OpenTelemetry::Resource::Detector::Container.detect)
+                                                 .merge(Resource::KubernetesPod.detect)
+                                                 .merge(Resource::ServiceNameFallback.detect)
+                                                 .merge(Resource::Distribution.detect)
+      end
+    end
+  end
+end

data/lib/dash0/opentelemetry/version.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright 2026 Dash0 Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+module Dash0
+  module OpenTelemetry
+    VERSION = '0.1.0'
+
+    # Lowest Ruby version the distribution supports. Kept here (in a file that
+    # must stay parse-safe on older Rubies) so the requirable entry point can
+    # gate on it before requiring anything that uses newer syntax.
+    MINIMUM_RUBY_VERSION = '3.3.0'
+  end
+end

data/lib/dash0/opentelemetry.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright 2026 Dash0 Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+require 'dash0/opentelemetry/version'
+require 'dash0/opentelemetry/environment'
+require 'dash0/opentelemetry/resource/distribution'
+require 'dash0/opentelemetry/resource/kubernetes_pod'
+require 'dash0/opentelemetry/resource/service_name_fallback'
+require 'dash0/opentelemetry/instrumentation_installer'
+require 'dash0/opentelemetry/lifecycle'
+require 'dash0/opentelemetry/sdk_configuration'
+require 'dash0/opentelemetry/boot'
+
+module Dash0
+  # Namespace for the Dash0 OpenTelemetry distribution for Ruby.
+  #
+  # The distribution activates as a side effect of requiring the gem's entry
+  # point (`require 'dash0-opentelemetry'`), typically via
+  # `RUBYOPT="-r dash0-opentelemetry"`. Requiring this namespace on its own has no
+  # side effects; the boot sequence is triggered explicitly via {boot!}.
+  module OpenTelemetry
+    # Prefix used for all messages the distribution writes to stderr.
+    LOG_PREFIX = '[Dash0 OpenTelemetry Distribution]'
+
+    # Boots the distribution. This is the single entry point that the requirable
+    # entry file (`lib/dash0-opentelemetry.rb`) invokes.
+    def self.boot!
+      Boot.run
+    end
+
+    # Logs an error-level message to stderr. Always emitted.
+    def self.log_error(message)
+      warn "#{LOG_PREFIX} #{message}"
+    end
+
+    # Logs a debug-level message to stderr, only when DASH0_DEBUG=true.
+    def self.log_debug(message)
+      return unless Environment.debug?
+
+      warn "#{LOG_PREFIX} #{message}"
+    end
+  end
+end

data/lib/dash0-opentelemetry.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright 2026 Dash0 Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+# Requirable entry point for the Dash0 OpenTelemetry distribution for Ruby.
+#
+# This is the file the Dash0 operator/injector points `RUBYOPT="-r ..."` at.
+# Requiring it boots the distribution as a side effect.
+#
+# IMPORTANT: the injector preloads this file into whatever Ruby the target app
+# runs and performs no Ruby-version detection of its own. So this file must stay
+# syntactically conservative (parse-safe on older Rubies) and check the runtime
+# version BEFORE requiring any of the distribution's other files, which are free
+# to use modern syntax. On an unsupported Ruby we stand down cleanly rather than
+# crash the host application.
+
+# When the operator/injector preloads this file via `RUBYOPT="-r <abs path>"`,
+# Ruby loads it by absolute path without activating the gem, and no Bundler is
+# involved, so this gem's own `lib` is not on the load path yet. Put it there so
+# `require 'dash0/...'` resolves. (Under Bundler this is a harmless no-op.)
+dash0_lib_dir = __dir__
+$LOAD_PATH.unshift(dash0_lib_dir) unless $LOAD_PATH.include?(dash0_lib_dir)
+
+require 'dash0/opentelemetry/version'
+
+if Gem::Version.new(RUBY_VERSION) < Gem::Version.new(Dash0::OpenTelemetry::MINIMUM_RUBY_VERSION)
+  warn "[Dash0 OpenTelemetry Distribution] Ruby #{RUBY_VERSION} is not supported " \
+       "(requires >= #{Dash0::OpenTelemetry::MINIMUM_RUBY_VERSION}). " \
+       'OpenTelemetry data will not be sent to Dash0.'
+  return
+end
+
+# This rescue ensures we fail open if there is an issue loading our library.
+# Unlikely but not impossible: a missing/corrupt distribution file, or a
+# SyntaxError in our lib.
+begin
+  require 'dash0/opentelemetry'
+  Dash0::OpenTelemetry.boot!
+rescue StandardError, ScriptError => e
+  warn "[Dash0 OpenTelemetry Distribution] Initialization failed: #{e.message}. " \
+       'OpenTelemetry data will not be sent to Dash0.'
+end

metadata

@@ -0,0 +1,176 @@
+--- !ruby/object:Gem::Specification
+name: dash0-opentelemetry
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Dash0 Inc.
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-07-31 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-exporter-otlp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.33.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.33.0
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-exporter-otlp-logs
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.4.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.4.0
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-exporter-otlp-metrics
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.8.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.8.0
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-instrumentation-all
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.91.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.91.0
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-logs-sdk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.1
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-metrics-sdk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.13.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.13.1
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-resource-detector-container
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.3.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.3.0
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-sdk
+  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
+description: An opinionated, zero-code OpenTelemetry distribution for Ruby that wraps
+  upstream OpenTelemetry and is designed to be injected by the Dash0 Kubernetes operator.
+email:
+- support@dash0.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CONTRIBUTING.md
+- LICENSE
+- README.md
+- RELEASING.md
+- lib/dash0-opentelemetry.rb
+- lib/dash0/opentelemetry.rb
+- lib/dash0/opentelemetry/boot.rb
+- lib/dash0/opentelemetry/environment.rb
+- lib/dash0/opentelemetry/instrumentation_installer.rb
+- lib/dash0/opentelemetry/lifecycle.rb
+- lib/dash0/opentelemetry/resource/distribution.rb
+- lib/dash0/opentelemetry/resource/kubernetes_pod.rb
+- lib/dash0/opentelemetry/resource/service_name_fallback.rb
+- lib/dash0/opentelemetry/sdk_configuration.rb
+- lib/dash0/opentelemetry/version.rb
+homepage: https://github.com/dash0hq/opentelemetry-ruby-distribution
+licenses:
+- Apache-2.0
+metadata:
+  changelog_uri: https://github.com/dash0hq/opentelemetry-ruby-distribution/blob/main/CHANGELOG.md
+  source_code_uri: https://github.com/dash0hq/opentelemetry-ruby-distribution
+  bug_tracker_uri: https://github.com/dash0hq/opentelemetry-ruby-distribution/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+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: 3.5.22
+signing_key:
+specification_version: 4
+summary: Dash0 OpenTelemetry distribution for Ruby
+test_files: []