splunk-otel 0.1.0

data/examples/rails-7-barebones/tests-e2e/rails_7_barebones_test.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "test-unit"
+require "net/http"
+require "json"
+
+module Splunk
+  # Rails7BarebonesTest
+  class Rails7BarebonesTest < Test::Unit::TestCase
+    test "generates spans" do
+      app_host = ENV.fetch "APP_HOST", "localhost"
+      app_port = ENV.fetch("APP_PORT", "3000").to_i
+      collector_host = ENV.fetch "COLLECTOR_HOST", "localhost"
+      collector_port = ENV.fetch("COLLECTOR_PORT", "8378").to_i
+
+      Net::HTTP.get(app_host, "/", app_port)
+
+      response = Net::HTTP.get(collector_host, "/?timeout=20&count=1", collector_port)
+      spans = JSON.parse(response)
+      assert spans.count >= 1
+
+      assert(spans.all? { |span| span["traceId"].to_s != "" })
+      assert(spans.all? { |span| span["spanId"].to_s != "" })
+      assert(spans.all? { |span| span["operationName"].to_s != "" })
+    end
+  end
+end

data/examples/rails-7-barebones/wait-for.sh

@@ -0,0 +1,191 @@
+#!/bin/sh
+
+# The MIT License (MIT)
+#
+# Copyright (c) 2017 Eficode Oy
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+VERSION="2.2.3"
+
+set -- "$@" -- "$TIMEOUT" "$QUIET" "$PROTOCOL" "$HOST" "$PORT" "$result"
+TIMEOUT=15
+QUIET=0
+# The protocol to make the request with, either "tcp" or "http"
+PROTOCOL="tcp"
+
+echoerr() {
+  if [ "$QUIET" -ne 1 ]; then printf "%s\n" "$*" 1>&2; fi
+}
+
+usage() {
+  exitcode="$1"
+  cat << USAGE >&2
+Usage:
+  $0 host:port|url [-t timeout] [-- command args]
+  -q | --quiet                        Do not output any status messages
+  -t TIMEOUT | --timeout=timeout      Timeout in seconds, zero for no timeout
+  -v | --version                      Show the version of this tool
+  -- COMMAND ARGS                     Execute command with args after the test finishes
+USAGE
+  exit "$exitcode"
+}
+
+wait_for() {
+  case "$PROTOCOL" in
+    tcp)
+      if ! command -v nc >/dev/null; then
+        echoerr 'nc command is missing!'
+        exit 1
+      fi
+      ;;
+    http)
+      if ! command -v wget >/dev/null; then
+        echoerr 'wget command is missing!'
+        exit 1
+      fi
+      ;;
+  esac
+
+  TIMEOUT_END=$(($(date +%s) + TIMEOUT))
+
+  while :; do
+    case "$PROTOCOL" in
+      tcp)
+        nc -w 1 -z "$HOST" "$PORT" > /dev/null 2>&1
+        ;;
+      http)
+        wget --timeout=1 -q "$HOST" -O /dev/null > /dev/null 2>&1
+        ;;
+      *)
+        echoerr "Unknown protocol '$PROTOCOL'"
+        exit 1
+        ;;
+    esac
+
+    result=$?
+
+    if [ $result -eq 0 ] ; then
+      if [ $# -gt 7 ] ; then
+        for result in $(seq $(($# - 7))); do
+          result=$1
+          shift
+          set -- "$@" "$result"
+        done
+
+        TIMEOUT=$2 QUIET=$3 PROTOCOL=$4 HOST=$5 PORT=$6 result=$7
+        shift 7
+        exec "$@"
+      fi
+      exit 0
+    fi
+
+    if [ $TIMEOUT -ne 0 -a $(date +%s) -ge $TIMEOUT_END ]; then
+      echo "Operation timed out" >&2
+      exit 1
+    fi
+
+    sleep 1
+  done
+}
+
+while :; do
+  case "$1" in
+    http://*|https://*)
+    HOST="$1"
+    PROTOCOL="http"
+    shift 1
+    ;;
+    *:* )
+    HOST=$(printf "%s\n" "$1"| cut -d : -f 1)
+    PORT=$(printf "%s\n" "$1"| cut -d : -f 2)
+    shift 1
+    ;;
+    -v | --version)
+    echo $VERSION
+    exit
+    ;;
+    -q | --quiet)
+    QUIET=1
+    shift 1
+    ;;
+    -q-*)
+    QUIET=0
+    echoerr "Unknown option: $1"
+    usage 1
+    ;;
+    -q*)
+    QUIET=1
+    result=$1
+    shift 1
+    set -- -"${result#-q}" "$@"
+    ;;
+    -t | --timeout)
+    TIMEOUT="$2"
+    shift 2
+    ;;
+    -t*)
+    TIMEOUT="${1#-t}"
+    shift 1
+    ;;
+    --timeout=*)
+    TIMEOUT="${1#*=}"
+    shift 1
+    ;;
+    --)
+    shift
+    break
+    ;;
+    --help)
+    usage 0
+    ;;
+    -*)
+    QUIET=0
+    echoerr "Unknown option: $1"
+    usage 1
+    ;;
+    *)
+    QUIET=0
+    echoerr "Unknown argument: $1"
+    usage 1
+    ;;
+  esac
+done
+
+if ! [ "$TIMEOUT" -ge 0 ] 2>/dev/null; then
+  echoerr "Error: invalid timeout '$TIMEOUT'"
+  usage 3
+fi
+
+case "$PROTOCOL" in
+  tcp)
+    if [ "$HOST" = "" ] || [ "$PORT" = "" ]; then
+      echoerr "Error: you need to provide a host and port to test."
+      usage 2
+    fi
+  ;;
+  http)
+    if [ "$HOST" = "" ]; then
+      echoerr "Error: you need to provide a host to test."
+      usage 2
+    fi
+  ;;
+esac
+
+wait_for "$@"

data/lib/splunk/otel/common.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Splunk
+  module Otel
+    # functions for shared functionality that will be used by multiple
+    # instrumentation libraries. Like creating RUM headers used by any
+    # HTTP library.
+    module Common
+      CORS_EXPOSE_HEADER = "Access-Control-Expose-Headers"
+      SERVER_TIMING_HEADER = "Server-Timing"
+
+      # rubocop:disable Lint/MissingCopEnableDirective
+      # rubocop:disable Metrics/PerceivedComplexity
+      # rubocop:disable Metrics/MethodLength
+      # rubocop:disable Metrics/AbcSize
+      def rum_headers(headers)
+        span = OpenTelemetry::Trace.current_span
+
+        return headers if span == OpenTelemetry::Trace::Span::INVALID
+
+        version = "00"
+        trace_id = span.context.hex_trace_id
+        span_id = span.context.hex_span_id
+        flags = span.context.trace_flags.sampled? ? "01" : "00"
+
+        trace_parent = [version, trace_id, span_id, flags]
+        headers[SERVER_TIMING_HEADER] = if (headers[SERVER_TIMING_HEADER] || "").empty?
+                                          "traceparent;desc=\"#{trace_parent.join("-")}\""
+                                        else
+                                          # rubocop:disable Layout/LineLength
+                                          "#{headers[SERVER_TIMING_HEADER]}, traceparent;desc=\"#{trace_parent.join("-")}\""
+                                        end
+
+        # TODO: check if this needs to be conditioned on CORS
+        headers[CORS_EXPOSE_HEADER] = if (headers[CORS_EXPOSE_HEADER] || "").empty?
+                                        SERVER_TIMING_HEADER
+                                      else
+                                        "#{headers[CORS_EXPOSE_HEADER]}, #{SERVER_TIMING_HEADER}"
+                                      end
+
+        headers
+      end
+
+      module_function :rum_headers
+    end
+  end
+end

data/lib/splunk/otel/instrumentation/action_pack/instrumentation.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "opentelemetry"
+require "opentelemetry-instrumentation-base"
+
+module Splunk
+  module Otel
+    module Instrumentation
+      module ActionPack
+        # The Instrumentation class contains logic to detect and install the ActionPack instrumentation
+        class Instrumentation < OpenTelemetry::Instrumentation::Base
+          MINIMUM_VERSION = Gem::Version.new("5.2.0")
+
+          install do |_config|
+            require_railtie
+          end
+
+          present do
+            defined?(::ActionController)
+          end
+
+          compatible do
+            gem_version >= MINIMUM_VERSION
+          end
+
+          option :enable_recognize_route, default: false, validate: :boolean
+
+          private
+
+          def gem_version
+            ::ActionPack.version
+          end
+
+          def require_railtie
+            require_relative "railtie"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/splunk/otel/instrumentation/action_pack/railtie.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "rack/etag"
+require_relative "../rack"
+
+module Splunk
+  module Otel
+    module Instrumentation
+      module ActionPack
+        # Install the Rack middleware for RUM responses
+        class Railtie < ::Rails::Railtie
+          config.before_initialize do |app|
+            case Rails.version
+            when /^7\./
+              # TODO: can be removed once https://github.com/rails/rails/issues/45607 is merged
+              app.middleware.insert_before(
+                ::Rack::ETag,
+                Splunk::Otel::Rack::RumMiddleware
+              )
+            else
+              app.middleware.use Splunk::Otel::Rack::RumMiddleware
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/splunk/otel/instrumentation/action_pack/version.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Splunk
+  module Otel
+    module Instrumentation
+      module ActionPack
+        VERSION = "0.1.0"
+      end
+    end
+  end
+end

data/lib/splunk/otel/instrumentation/action_pack.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Splunk
+  module Otel
+    module Instrumentation
+      # Contains the RUM instrumentation for the ActionPack gem
+      module ActionPack
+      end
+    end
+  end
+end
+
+require_relative "./action_pack/instrumentation"
+require_relative "./action_pack/version"

data/lib/splunk/otel/instrumentation/rack/middleware.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "splunk/otel/common"
+
+module Splunk
+  module Otel
+    module Rack
+      # RumMiddleware propagates context and instruments Rack responses
+      # by way of its middleware system
+      class RumMiddleware
+        def initialize(app)
+          @app = app
+        end
+
+        def call(env)
+          status, headers, body = @app.call(env)
+
+          headers = Splunk::Otel::Common.rum_headers(headers)
+
+          [status, headers, body]
+        end
+      end
+    end
+  end
+end

data/lib/splunk/otel/instrumentation/rack.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "./rack/middleware"

data/lib/splunk/otel/logging.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Splunk
+  module Otel
+    # functions for log correlation
+    module Logging
+      # return log formatted trace context
+      def format_correlation
+        resource_attributes = OpenTelemetry.tracer_provider.resource.attribute_enumerator.to_h
+        service_name = resource_attributes["service.name"]
+        span = OpenTelemetry::Trace.current_span
+
+        if span == OpenTelemetry::Trace::Span::INVALID
+          "service.name=#{service_name}"
+        else
+          %W[service.name=#{service_name} trace_id=#{span.context.hex_trace_id}
+             span_id=#{span.context.hex_span_id}].join(" ")
+        end
+      end
+
+      module_function :format_correlation
+    end
+  end
+end

data/lib/splunk/otel/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Splunk
+  module Otel
+    VERSION = "0.1.0"
+  end
+end

data/lib/splunk/otel.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require_relative "otel/version"
+require "opentelemetry/sdk"
+
+# FIXME: without this, otlp doesn't work out-of-the-box
+require "opentelemetry-exporter-otlp"
+
+module Splunk
+  # main module for application startup configuration
+  module Otel
+    # custom exception types in this gem must inherit from Splunk::Otel::Error
+    # this allows the user to rescue a generic exception type to catch all exceptions
+    class Error < StandardError; end
+
+    # Configures the OpenTelemetry SDK and instrumentation with Splunk defaults.
+    #
+    # @yieldparam [Configurator] configurator Yields a configurator to the
+    #   provided block
+    #
+    # Example usage:
+    #   Without a block defaults are installed without any instrumentation
+    #
+    #     Splunk::Otel.configure
+    #
+    #   Install instrumentation individually with optional config
+    #
+    #     Splunk::Otel.configure do |c|
+    #       c.use 'OpenTelemetry::Instrumentation::Faraday', tracer_middleware: SomeMiddleware
+    #     end
+    #
+    #   Install all instrumentation with optional config
+    #
+    #     Splunk::Otel.configure do |c|
+    #       c.use_all 'OpenTelemetry::Instrumentation::Faraday' => { tracer_middleware: SomeMiddleware }
+    #     end
+    #
+    #   Add a span processor
+    #
+    #     Splunk::Otel.configure do |c|
+    #       c.add_span_processor SpanProcessor.new(SomeExporter.new)
+    #     end
+    #
+    #   Configure everything
+    #
+    #     Splunk::Otel.configure do |c|
+    #       c.logger = Logger.new(File::NULL)
+    #       c.add_span_processor SpanProcessor.new(SomeExporter.new)
+    #       c.use_all
+    #     end
+    def configure(service_name: ENV.fetch("OTEL_SERVICE_NAME", "unnamed-ruby-service"),
+                  auto_instrument: false)
+      set_default_propagators
+      set_access_token_header
+      set_default_exporter
+      set_default_span_limits
+
+      # run SDK's setup function
+      OpenTelemetry::SDK.configure do |c|
+        c.service_name = service_name
+        c.resource = OpenTelemetry::SDK::Resources::Resource.create(
+          "splunk.distro.version" => Splunk::Otel::VERSION
+        )
+
+        c.use_all if auto_instrument
+        yield c if block_given?
+      end
+
+      # set span limits to GDI defaults if not set by the user
+      OpenTelemetry.tracer_provider.span_limits = gdi_span_limits
+
+      verify_service_name
+    end
+
+    # verify `service.name` is set and print a warning if it is still the default
+    def verify_service_name
+      provider_resource = OpenTelemetry.tracer_provider.instance_variable_get(:@resource)
+      resource_attributes = provider_resource.instance_variable_get(:@attributes)
+      service_name = resource_attributes[OpenTelemetry::SemanticConventions::Resource::SERVICE_NAME]
+      OpenTelemetry.logger.warn service_name_warning if service_name == "unknown_service"
+    end
+
+    def set_default_exporter
+      set_endpoint
+      default_env_vars({ "OTEL_EXPORTER_OTLP_TRACES_COMPRESSION" => "gzip",
+                         "OTEL_EXPORTER_OTLP_COMPRESSION" => "gzip",
+                         "OTEL_TRACES_EXPORTER" => "otlp" })
+    end
+
+    def set_endpoint
+      traces_endpoint = ENV.fetch("OTEL_EXPORTER_OTLP_TRACES_ENDPOINT", nil)
+      endpoint = ENV.fetch("OTEL_EXPORTER_OTLP_ENDPOINT", nil)
+      splunk_realm = ENV.fetch("SPLUNK_REALM", nil)
+
+      # if user hasn't set traces endpoint or endpoint but has set the realm then
+      # set the endpoints to be https://api.<SPLUNK_REALM>.signalfx.com
+      # if either endpoint variable was set by the user then use those even if
+      # they've also set SPLUNK_REALM
+      return unless traces_endpoint.to_s.empty?
+      return unless endpoint.to_s.empty?
+
+      ENV["OTEL_EXPORTER_OTLP_TRACES_ENDPOINT"] = if splunk_realm.to_s.empty? || splunk_realm.to_s.eql?("none")
+                                                    "http://localhost:4318/v1/traces"
+                                                  else
+                                                    "https://ingest.#{splunk_realm}.signalfx.com/v2/trace/otlp"
+                                                  end
+    end
+
+    # add the access token header if the env variable is set
+    def set_access_token_header
+      splunk_access_token = ENV.fetch("SPLUNK_ACCESS_TOKEN", nil)
+      return if splunk_access_token.nil?
+
+      access_header = "x-sf-token=#{splunk_access_token}"
+      headers = ENV.fetch("OTEL_EXPORTER_OTLP_HEADERS", nil)
+      ENV["OTEL_EXPORTER_OTLP_HEADERS"] = if headers.to_s.empty?
+                                            access_header
+                                          else
+                                            "#{headers},#{access_header}"
+                                          end
+    end
+
+    def set_default_propagators
+      default_env_vars({ "OTEL_PROPAGATORS" => "tracecontext,baggage" })
+    end
+
+    def set_default_span_limits
+      default_env_vars({ "OTEL_SPAN_LINK_COUNT_LIMIT" => "1000",
+                         "OTEL_RUBY_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT" => "12000" })
+    end
+
+    def gdi_span_limits
+      infinite_defaults = { "OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT" => :attribute_count_limit,
+                            "OTEL_SPAN_EVENT_COUNT_LIMIT" => :event_count_limit,
+                            "OTEL_SPAN_LINK_COUNT_LIMIT" => :link_count_limit,
+                            "OTEL_EVENT_ATTRIBUTE_COUNT_LIMIT" => :event_attribute_count_limit,
+                            "OTEL_LINK_ATTRIBUTE_COUNT_LIMIT" => :link_attribute_count_limit }
+
+      defaults = {}
+      infinite_defaults.each do |k, v|
+        defaults[v] = Float::INFINITY if ENV[k].nil?
+      end
+
+      OpenTelemetry::SDK::Trace::SpanLimits.new(**defaults)
+    end
+
+    # set environment varaible default's if the user hasn't set them
+    def default_env_vars(env)
+      env.each do |k, v|
+        ENV[k] = v if ENV[k].nil?
+      end
+    end
+
+    def service_name_warning
+      <<~WARNING
+        service.name attribute is not set, your service is unnamed and will be difficult to identify.
+        set your service name using the OTEL_SERVICE_NAME environment variable.
+        E.g. `OTEL_SERVICE_NAME="<YOUR_SERVICE_NAME_HERE>"`
+      WARNING
+    end
+
+    module_function :configure, :gdi_span_limits, :set_default_propagators, :set_default_exporter,
+                    :verify_service_name, :service_name_warning, :default_env_vars,
+                    :set_default_span_limits, :set_access_token_header, :set_endpoint
+  end
+end
+
+require "splunk/otel/logging"
+require "splunk/otel/common"
+require "splunk/otel/instrumentation/action_pack"

data/scripts/install-release-deps.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+
+set -e
+
+# instructions from https://github.com/cli/cli/blob/trunk/docs/install_linux.md#debian-ubuntu-linux-apt
+curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | gpg --dearmor -o /usr/share/keyrings/githubcli-archive-keyring.gpg
+echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | tee /etc/apt/sources.list.d/github-cli.list > /dev/null
+
+apt-get update
+apt-get -y install ca-certificates curl gnupg lsb-release gh

data/scripts/release.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+
+set -e
+
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+ROOT_DIR="${SCRIPT_DIR}/../"
+cd "${ROOT_DIR}"
+
+print_usage() {
+  cat <<EOF
+Usage: $(basename "$0") tag
+Tag example: v1.2.3
+EOF
+}
+
+if [[ $# != 1 ]]
+then
+  print_usage
+  exit 1
+fi
+
+release_tag="$1"
+# without the starting 'v'
+release_version=$(echo "$release_tag" | cut -c2-)
+
+create_gh_release() {
+  echo ">>> Creating GitHub release $release_tag ..."
+  gh release create "$release_tag" \
+    --repo "signalfx/splunk-otel-ruby" \
+    --draft \
+    --title "Release $release_tag"
+}
+
+create_gh_release
+
+bundle install
+bundle exec rake build
+bundle exec gem push pkg/splunk-otel-${release_version}.gem