appsignal 4.10.0-java → 5.0.0.rc.1-java

data/lib/appsignal/metrics/opentelemetry_backend.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "appsignal/opentelemetry/attributes"
+
+module Appsignal
+  module Metrics
+    # @!visibility private
+    #
+    # Routes custom metric helper calls through the OpenTelemetry metrics
+    # SDK using the meter provider configured at `Appsignal.start` time when
+    # collector mode is active. Mirrors the Python integration's
+    # `appsignal/metrics.py`:
+    #
+    # - `set_gauge` uses a synchronous OTel Gauge.
+    # - `increment_counter` uses an UpDownCounter so negative increments
+    #   work (Counter would reject them).
+    # - `add_distribution_value` uses a Histogram.
+    #
+    # Instruments are created once per name and cached: the OTel SDK logs a
+    # "duplicate instrument registration" warning and swaps the instrument
+    # if `create_*` is called again for the same name. Tags attach at record
+    # time, not at instrument creation time.
+    module OpenTelemetryBackend
+      MUTEX = Mutex.new
+
+      class << self
+        def set_gauge(name, value, tags)
+          instrument(:gauge, name).record(
+            value.to_f,
+            :attributes => Appsignal::OpenTelemetry::Attributes.format(tags)
+          )
+        end
+
+        def increment_counter(name, value, tags)
+          instrument(:up_down_counter, name).add(
+            value.to_f,
+            :attributes => Appsignal::OpenTelemetry::Attributes.format(tags)
+          )
+        end
+
+        def add_distribution_value(name, value, tags)
+          instrument(:histogram, name).record(
+            value.to_f,
+            :attributes => Appsignal::OpenTelemetry::Attributes.format(tags)
+          )
+        end
+
+        # @!visibility private
+        #
+        # Test-only. Drops the cached meter and instruments so the next
+        # call re-resolves `OpenTelemetry.meter_provider`.
+        def reset!
+          MUTEX.synchronize do
+            @meter = nil
+            @gauges = nil
+            @counters = nil
+            @histograms = nil
+          end
+        end
+
+        private
+
+        # Fetch the named instrument, creating and caching it on first use.
+        # The lookup-or-create runs under the mutex so two concurrent
+        # first-time calls don't both create the instrument (which would
+        # make the SDK log a duplicate-registration warning).
+        def instrument(kind, name)
+          name = name.to_s
+          MUTEX.synchronize do
+            case kind
+            when :gauge
+              (@gauges ||= {})[name] ||= meter.create_gauge(name)
+            when :up_down_counter
+              (@counters ||= {})[name] ||= meter.create_up_down_counter(name)
+            when :histogram
+              (@histograms ||= {})[name] ||= meter.create_histogram(name)
+            end
+          end
+        end
+
+        # Only called from `instrument` while the mutex is held, so the plain
+        # memoisation needs no extra locking of its own.
+        def meter
+          @meter ||= ::OpenTelemetry.meter_provider.meter("appsignal-helpers")
+        end
+      end
+    end
+  end
+end

data/lib/appsignal/opentelemetry/attributes.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Appsignal
+  module OpenTelemetry
+    # @!visibility private
+    #
+    # Coerces user-supplied tag hashes into a shape the OpenTelemetry SDK
+    # accepts as attribute values: string keys, and values restricted to
+    # the primitive types the OTLP spec allows. Anything else falls back
+    # to `to_s`. Shared by the metric and log backends so both behave
+    # identically.
+    module Attributes
+      class << self
+        def format(attrs)
+          attrs.each_with_object({}) do |(key, value), result|
+            result[key.to_s] = format_value(value)
+          end
+        end
+
+        private
+
+        def format_value(value)
+          case value
+          when String, Integer, Float, TrueClass, FalseClass then value
+          else value.to_s
+          end
+        end
+      end
+    end
+  end
+end

data/lib/appsignal/opentelemetry/dependencies.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Appsignal
+  module OpenTelemetry
+    # @!visibility private
+    #
+    # The OpenTelemetry gems collector mode supports, mapped to their version
+    # requirements. Each gem maps to an array of requirement strings so a gem
+    # can carry more than one constraint later, even though each holds a single
+    # `~>` requirement today. These gems are *not* declared in the gemspec:
+    # they are optional and only required when collector mode is active. Apps
+    # that opt into collector mode install them into their own bundle (see the
+    # collector documentation).
+    #
+    # Each requirement pins a floor and a ceiling. The floor is the version the
+    # minimum supported Ruby (3.1) resolves to in our CI collector matrix. The
+    # ceiling is a pessimistic `~>` cap at the next major version. We set the
+    # cap loosely on purpose so it does not block customers from updating these
+    # gems within a major version.
+    #
+    # This file must stay free of any other dependency so it can be required
+    # directly from a Gemfile (see `gemfiles/collector.rb`) and from the
+    # runtime version gate in `Appsignal::OpenTelemetry.configure` without
+    # loading the rest of the gem.
+    REQUIRED_GEMS = {
+      "opentelemetry-sdk" => ["~> 1.10"],
+      "opentelemetry-common" => ["~> 0.23"],
+      "opentelemetry-metrics-sdk" => ["~> 0.12"],
+      "opentelemetry-logs-sdk" => ["~> 0.4"],
+      "opentelemetry-exporter-otlp" => ["~> 0.32"],
+      "opentelemetry-exporter-otlp-metrics" => ["~> 0.7"],
+      "opentelemetry-exporter-otlp-logs" => ["~> 0.3"]
+    }.freeze
+  end
+end

data/lib/appsignal/opentelemetry/error_type.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Appsignal
+  module OpenTelemetry
+    # @!visibility private
+    #
+    # Builds the OpenTelemetry attribute that describes what kind of failure
+    # ended an operation.
+    #
+    # The semantic conventions ask for `error.type` on a span whose operation
+    # failed, and for it to be left unset on one that succeeded. The value has to
+    # have low cardinality, which for an exception means its class name rather
+    # than its message. A failure we have no name for becomes `_OTHER`, which is
+    # the fallback the conventions define.
+    module ErrorType
+      ATTRIBUTE = "error.type"
+
+      # The value the semantic conventions use for a failure the
+      # instrumentation has no name for.
+      OTHER = "_OTHER"
+
+      class << self
+        # The attributes describing the given failure, as a Hash to pass to
+        # `add_opentelemetry_attributes`. Takes the name of the failure: an
+        # exception's class name, or the error code a datastore reported.
+        #
+        # An anonymous exception class has no name, and a datastore does not
+        # always report a code, so a missing name falls back to `_OTHER` rather
+        # than leaving the span with no `error.type` at all.
+        def attributes_for(name)
+          value = name.to_s
+          { ATTRIBUTE => value.empty? ? OTHER : value }
+        end
+      end
+    end
+  end
+end

data/lib/appsignal/opentelemetry/http_client_request.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Appsignal
+  module OpenTelemetry
+    # @!visibility private
+    #
+    # Builds the OpenTelemetry attributes that describe an outgoing HTTP request.
+    #
+    # The semantic conventions ask for the request method, the host and port
+    # being called, and the full URL. Those together are also what the trace
+    # timeline reads to recognize an outgoing request.
+    #
+    # The URL is built from the parts rather than taken whole, which has two
+    # consequences worth knowing about.
+    #
+    # It never contains credentials. A URL can carry a username and password,
+    # which the conventions say must not be sent. Building the URL from the
+    # scheme, host, port and path means there is nowhere for them to come from.
+    #
+    # It never contains the query string either. The conventions do ask for it,
+    # but the query string of a call to somebody else's API is the part most
+    # likely to carry a key or a token, and unlike an incoming request it is not
+    # something the application chose the shape of. Anything a caller passes as a
+    # path is cut at the first question mark for the same reason, because some
+    # clients hand us a request target rather than a path.
+    module HttpClientRequest
+      ADDRESS_ATTRIBUTE = "server.address"
+      PORT_ATTRIBUTE = "server.port"
+      URL_ATTRIBUTE = "url.full"
+
+      # The port each scheme uses when a URL does not name one. Left out of the
+      # URL, which is how a URL is normally written, but still reported as the
+      # port, which the conventions ask for either way.
+      DEFAULT_PORTS = {
+        "http" => 80,
+        "https" => 443
+      }.freeze
+
+      class << self
+        # The attributes describing the given request, as a Hash to pass to
+        # `add_opentelemetry_attributes`. Takes the request's parts, because
+        # some clients hand us a URI and others only the parts.
+        def attributes_for(method:, scheme: nil, host: nil, port: nil, path: nil)
+          attributes = HttpMethod.attributes_for(method)
+          attributes[ADDRESS_ATTRIBUTE] = host.to_s unless host.to_s.empty?
+
+          port = port_for(scheme, port)
+          attributes[PORT_ATTRIBUTE] = port if port
+
+          url = url_for(scheme, host, port, path)
+          attributes[URL_ATTRIBUTE] = url if url
+
+          attributes
+        end
+
+        private
+
+        # A client that was not given a port uses the one its scheme implies, so
+        # report that rather than nothing.
+        def port_for(scheme, port)
+          Integer(port, :exception => false) || DEFAULT_PORTS[scheme.to_s]
+        end
+
+        def url_for(scheme, host, port, path)
+          return if scheme.to_s.empty? || host.to_s.empty?
+
+          url = +"#{scheme}://#{host}"
+          url << ":#{port}" if port && port != DEFAULT_PORTS[scheme.to_s]
+          url << path_without_query(path)
+          url
+        end
+
+        # Some clients report the path of a request to the root of a host as
+        # empty, and others as "/". The request goes to "/" either way, so say so
+        # rather than let the URL differ by which client made the request.
+        def path_without_query(path)
+          without_query = path.to_s.split("?", 2).first.to_s
+          without_query.empty? ? "/" : without_query
+        end
+      end
+    end
+  end
+end

data/lib/appsignal/opentelemetry/http_method.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Appsignal
+  module OpenTelemetry
+    # @!visibility private
+    #
+    # Builds the OpenTelemetry attributes that describe an HTTP request method.
+    #
+    # The semantic conventions treat `http.request.method` as a closed set of
+    # known method names, so an arbitrary value cannot be passed through. A
+    # method outside the set becomes `_OTHER`, and a method that only matches
+    # after upcasing is replaced by its canonical form. Both of those cases keep
+    # the value we were given in `http.request.method_original`, so the original
+    # is never lost.
+    module HttpMethod
+      # The methods the semantic conventions know about: those defined in
+      # RFC 9110, plus PATCH from RFC 5789.
+      KNOWN_METHODS = [
+        "CONNECT",
+        "DELETE",
+        "GET",
+        "HEAD",
+        "OPTIONS",
+        "PATCH",
+        "POST",
+        "PUT",
+        "TRACE"
+      ].freeze
+
+      # The value the semantic conventions use for a method they do not know.
+      OTHER = "_OTHER"
+
+      METHOD_ATTRIBUTE = "http.request.method"
+      ORIGINAL_ATTRIBUTE = "http.request.method_original"
+
+      class << self
+        # The attributes describing the given request method, as a Hash to pass
+        # to `add_opentelemetry_attributes`. Returns an empty Hash when there is
+        # no method to describe, so a caller that could not read one can pass
+        # the result on without checking.
+        def attributes_for(method)
+          original = method.to_s
+          return {} if original.empty?
+
+          # Method names are case sensitive, so a value that already matches a
+          # known method is used as it is, with nothing to preserve.
+          return { METHOD_ATTRIBUTE => original } if KNOWN_METHODS.include?(original)
+
+          canonical = original.upcase
+          if KNOWN_METHODS.include?(canonical)
+            { METHOD_ATTRIBUTE => canonical, ORIGINAL_ATTRIBUTE => original }
+          else
+            { METHOD_ATTRIBUTE => OTHER, ORIGINAL_ATTRIBUTE => original }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/appsignal/opentelemetry/http_response.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Appsignal
+  module OpenTelemetry
+    # @!visibility private
+    #
+    # Builds the OpenTelemetry attributes that describe an HTTP response.
+    #
+    # The semantic conventions ask for the response status code on the span of an
+    # HTTP request, whether that is a request this application handled or one it
+    # made. They ask for it only when a response was actually received or sent,
+    # so a request that never got one is described without it.
+    module HttpResponse
+      STATUS_CODE_ATTRIBUTE = "http.response.status_code"
+
+      class << self
+        # The attributes describing the given response status, as a Hash to pass
+        # to `add_opentelemetry_attributes`. Returns an empty Hash when there is
+        # no status to describe, so a caller whose request produced no response
+        # can pass the result on without checking.
+        def attributes_for(status)
+          code = Integer(status, :exception => false)
+          return {} unless code
+
+          { STATUS_CODE_ATTRIBUTE => code }
+        end
+      end
+    end
+  end
+end

data/lib/appsignal/opentelemetry/http_server_request.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Appsignal
+  module OpenTelemetry
+    # @!visibility private
+    #
+    # Builds the OpenTelemetry attributes that describe an incoming HTTP
+    # request.
+    #
+    # The semantic conventions ask for the request method, the path and the
+    # scheme on the span of a request a server handled. Those three together are
+    # also what the trace timeline reads to recognize a web request.
+    #
+    # The path is the concrete path the request was made to, such as `/users/1`.
+    # It is not the route template the application matched it against, which the
+    # conventions call `http.route` and which a Rack application does not
+    # necessarily have.
+    #
+    # The query string is asked for whenever the request had one. It is sent
+    # whole, without the leading question mark, and it is not filtered here. The
+    # collector filters it with the `filter_request_query_parameters` option, and
+    # builds the request's query parameters out of it.
+    #
+    # Every value is optional, because reading any of them from the request can
+    # fail. An attribute we have no value for is left out rather than sent
+    # empty.
+    module HttpServerRequest
+      PATH_ATTRIBUTE = "url.path"
+      SCHEME_ATTRIBUTE = "url.scheme"
+      QUERY_ATTRIBUTE = "url.query"
+
+      class << self
+        # The attributes describing the given request, as a Hash to pass to
+        # `add_opentelemetry_attributes`.
+        def attributes_for(method:, path: nil, scheme: nil, query: nil)
+          attributes = HttpMethod.attributes_for(method)
+          attributes[PATH_ATTRIBUTE] = path.to_s unless path.to_s.empty?
+          attributes[SCHEME_ATTRIBUTE] = scheme.to_s unless scheme.to_s.empty?
+          attributes[QUERY_ATTRIBUTE] = query.to_s unless query.to_s.empty?
+          attributes
+        end
+      end
+    end
+  end
+end

data/lib/appsignal/opentelemetry/messaging.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Appsignal
+  module OpenTelemetry
+    # @!visibility private
+    #
+    # Builds the OpenTelemetry attributes that describe a messaging operation,
+    # which for AppSignal means a background job being enqueued or performed.
+    #
+    # The semantic conventions ask for the messaging system, the name of the
+    # operation, and the kind of operation it was. The name is the job library's
+    # own word for what happened. The kind is one of the five values the
+    # conventions define, and AppSignal only ever produces two of them:
+    # enqueuing a job sends a message, and performing one processes it.
+    #
+    # They also ask for the destination of the message, which for a job library
+    # is the queue it is on, and for how many messages a span covers when it
+    # covers a batch of them.
+    #
+    # The system is the only part that differs per job library, so each
+    # integration passes its own.
+    module Messaging
+      SYSTEM_ATTRIBUTE = "messaging.system"
+      OPERATION_NAME_ATTRIBUTE = "messaging.operation.name"
+      OPERATION_TYPE_ATTRIBUTE = "messaging.operation.type"
+      DESTINATION_ATTRIBUTE = "messaging.destination.name"
+      BATCH_COUNT_ATTRIBUTE = "messaging.batch.message_count"
+
+      # The operations AppSignal records, and the kind of operation the
+      # conventions class each of them as.
+      ENQUEUE = "enqueue"
+      PERFORM = "perform"
+      OPERATION_TYPES = {
+        ENQUEUE => "send",
+        PERFORM => "process"
+      }.freeze
+
+      class << self
+        # The attributes describing a job being enqueued, as a Hash to pass to
+        # `add_opentelemetry_attributes`.
+        def enqueue_attributes(system, destination: nil, batch_size: nil)
+          attributes_for(system, ENQUEUE, destination, batch_size)
+        end
+
+        # The attributes describing a job being performed, as a Hash to pass to
+        # `add_opentelemetry_attributes`.
+        def perform_attributes(system, destination: nil, batch_size: nil)
+          attributes_for(system, PERFORM, destination, batch_size)
+        end
+
+        private
+
+        def attributes_for(system, operation, destination, batch_size)
+          {
+            SYSTEM_ATTRIBUTE => system,
+            OPERATION_NAME_ATTRIBUTE => operation,
+            OPERATION_TYPE_ATTRIBUTE => OPERATION_TYPES.fetch(operation),
+            DESTINATION_ATTRIBUTE => destination_name(destination),
+            BATCH_COUNT_ATTRIBUTE => batch_count(batch_size)
+          }.compact
+        end
+
+        # The queue the job is on, which the conventions call the destination of
+        # the message. A job whose queue we cannot name is described without it.
+        def destination_name(destination)
+          name = destination.to_s
+          name unless name.empty?
+        end
+
+        # How many messages the span covers. The conventions ask for this only
+        # when a span describes a batch, and say it must not be set on a span
+        # that describes a single message.
+        def batch_count(batch_size)
+          return unless batch_size
+
+          count = batch_size.to_i
+          count if count.positive?
+        end
+      end
+    end
+  end
+end

data/lib/appsignal/opentelemetry/rendering.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Appsignal
+  module OpenTelemetry
+    # @!visibility private
+    #
+    # Builds the OpenTelemetry attributes that describe an event as template
+    # rendering.
+    #
+    # Rendering a template has no semantic convention to describe it, so these
+    # events say which group they belong to directly. The trace timeline reads
+    # `appsignal.group` before it looks at any convention attribute, and
+    # "render" is the group it shows as "Templating".
+    module Rendering
+      GROUP_ATTRIBUTE = "appsignal.group"
+      GROUP = "render"
+
+      ATTRIBUTES = { GROUP_ATTRIBUTE => GROUP }.freeze
+
+      class << self
+        # The attributes describing an event as template rendering, as a Hash
+        # to pass to `add_opentelemetry_attributes`.
+        def attributes
+          ATTRIBUTES
+        end
+      end
+    end
+  end
+end

data/lib/appsignal/opentelemetry/sql_db_system.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Appsignal
+  module OpenTelemetry
+    # @!visibility private
+    #
+    # Maps a SQL library's own name for the engine it is talking to onto the
+    # `db.system.name` semantic conventions value for that engine.
+    #
+    # Each library names engines differently, and none of them matches the
+    # semantic conventions spelling, so every SQL integration needs a lookup.
+    # Kept as one map per library, each keyed on that library's own
+    # vocabulary, rather than one shared map: ActiveRecord's `ADAPTER_NAME`
+    # strings, Sequel's `database_type` symbols, and DataMapper's
+    # `DataObjects` connection class names do not collide today, but nothing
+    # about that is enforced by combining them. A wrong value passed into the
+    # wrong library's lookup would silently return another library's answer
+    # instead of nil, and a library's own gaps would be invisible next to two
+    # other libraries' complete entries. ROM is the exception: its payload
+    # already carries Sequel's own `database_type` symbol, so it is
+    # legitimate for it to share Sequel's map, not just convenient.
+    #
+    # A name none of these maps recognise returns `nil`, so the caller's own
+    # `other_sql` fallback applies -- exactly what already happens for a
+    # library this gem has no mapping for at all.
+    #
+    # This intentionally follows the older semantic conventions value set:
+    # SQL Server maps to `mssql`, not the current registry's
+    # `microsoft.sql_server`, and Oracle maps to `oracle`, not `oracle.db`.
+    # That is what the AppSignal collector's sanitizer recognizes today;
+    # emitting the newer values would silently turn sanitization off for
+    # those engines' queries.
+    module SqlDbSystem
+      # ActiveRecord's `ADAPTER_NAME`. Rails bundles the Postgres, Mysql2,
+      # SQLite and (7.1+) Trilogy adapters; SQL Server and Oracle come from
+      # the separate `activerecord-sqlserver-adapter` and
+      # `activerecord-oracle_enhanced-adapter` gems, which declare
+      # `ADAPTER_NAME` the same way.
+      ACTIVE_RECORD = {
+        "PostgreSQL" => "postgresql",
+        "Mysql2" => "mysql",
+        "Trilogy" => "mysql",
+        "SQLite" => "sqlite",
+        "SQLServer" => "mssql",
+        "OracleEnhanced" => "oracle"
+      }.freeze
+
+      # Sequel's `database_type`. ROM's dry-monitor payload reuses this
+      # symbol directly, so `name_for_sequel` is also ROM's lookup.
+      SEQUEL = {
+        :postgres => "postgresql",
+        :mysql => "mysql",
+        :sqlite => "sqlite",
+        :mssql => "mssql",
+        :oracle => "oracle"
+      }.freeze
+
+      # DataMapper's `DataObjects` connection classes.
+      DATA_MAPPER = {
+        "DataObjects::Postgres::Connection" => "postgresql",
+        "DataObjects::Mysql::Connection" => "mysql",
+        "DataObjects::Sqlite3::Connection" => "sqlite",
+        "DataObjects::SqlServer::Connection" => "mssql"
+      }.freeze
+
+      class << self
+        # The `db.system.name` value for an ActiveRecord connection's
+        # `adapter_name`, or `nil` when the adapter is not one this map
+        # recognises.
+        def name_for_active_record(adapter_name)
+          ACTIVE_RECORD[adapter_name]
+        end
+
+        # The `db.system.name` value for Sequel's `database_type`, or `nil`
+        # when it is not one this map recognises. Also the lookup ROM's
+        # formatter uses, since ROM reports this same symbol.
+        def name_for_sequel(database_type)
+          SEQUEL[database_type]
+        end
+
+        # The `db.system.name` value for DataMapper's connection class name,
+        # or `nil` when it is not one this map recognises.
+        def name_for_data_mapper(connection_class_name)
+          DATA_MAPPER[connection_class_name]
+        end
+      end
+    end
+  end
+end