clicksend-opentelemetry 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0af816c4b5ff18d37e86e352b4d0deee0a48113c66a8a6b0afcbf2a6a41b8753
+  data.tar.gz: 8ae1ea1e1ffb6c812e7e5ea3d922641ed45e3da6a841f7e4e02a9236a07a3185
+SHA512:
+  metadata.gz: c53aa4d5940bef92d06089b2e2ce40c38178a88754667692af2baa541fca6e36694664dc1cb7fc8c77a432b7bd5ab0a8395f8df9170399238990f649ce8f0d06
+  data.tar.gz: 57faca30aa2d16c156e336c34dd54b525947bd8a0d6c24d57ac1b1a1ac9bc84e8bc35a45301efcf1b167644c624e53f0a986611dee3d4bf92e6b9a2ed468517c

data/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to `clicksend-opentelemetry` are documented here. It is versioned and released
+separately from [`clicksend`](https://github.com/prayantr/clicksend/blob/master/CHANGELOG.md). The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html). While the version is 0.x, a minor
+release may rename span attributes as OpenTelemetry's semantic conventions change.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-06
+
+The first release.
+
+### Added
+
+- `Clicksend::OpenTelemetry::Instrumenter`, passed to `Clicksend::Client.new(instrumenter:)`. One
+  span of kind CLIENT per ClickSend API call, retries included, named `clicksend <operation>`
+  (`clicksend <METHOD>` when there is no operation). Attributes: `http.request.method`,
+  `server.address`, `server.port`, `url.path` (never the query string; `record_path: false` leaves
+  it out, and the path out of the exception event's message), `http.response.status_code`,
+  `error.type`, and `clicksend.operation`, `clicksend.idempotent`, `clicksend.attempts`,
+  `clicksend.ambiguous`, `clicksend.response_code`.
+  Each retry is a `clicksend.retry` span event. A failed call sets the span status to ERROR and
+  adds an `exception` event whose message is built only from the class, HTTP status, ClickSend's
+  `response_code` and the request line, never from the exception's own message.
+- `Clicksend::OpenTelemetry::FanOut`, which sends the client's events to several instrumenters
+  (for example `ActiveSupport::Notifications` and the OpenTelemetry instrumenter) while the
+  request still runs once.
+- The instrumenter never changes a call's outcome: its own failures go to
+  `OpenTelemetry.handle_error`, the request runs exactly once, and errors, including ambiguous
+  ones, pass through unchanged.
+- Requires Ruby 3.3 or newer, `clicksend` 1.x (from 1.1) and `opentelemetry-api` 1.x. The SDK and
+  exporters are the application's choice.
+
+[Unreleased]: https://github.com/prayantr/clicksend/compare/clicksend-opentelemetry-v0.1.0...HEAD
+[0.1.0]: https://github.com/prayantr/clicksend/releases/tag/clicksend-opentelemetry-v0.1.0

data/LICENSE.txt

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Prayantr (https://prayantr.com), Amit Solanki, Braj Pratap Singh
+Copyright (c) 2026 Amit Solanki and contributors
+
+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.

data/README.md

@@ -0,0 +1,119 @@
+# clicksend-opentelemetry
+
+OpenTelemetry spans for the [clicksend](https://github.com/prayantr/clicksend) gem, built only on
+its public `instrumenter:` hook. It depends on `opentelemetry-api`; your application chooses the
+SDK and exporter.
+
+**Optional.** `clicksend` doesn't depend on this gem or on OpenTelemetry, and works the same
+without it. Add it only if you want ClickSend spans in your traces.
+
+> It lives in the clicksend repository and is released separately from `clicksend`, on its own
+> version line ([CHANGELOG](CHANGELOG.md)). While it is 0.x, a minor release may rename attributes
+> as OpenTelemetry's semantic conventions change. Unofficial: not affiliated with ClickSend.
+
+Requires Ruby 3.3 or newer, `clicksend` 1.x (1.1 or later) and `opentelemetry-api` 1.x.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "clicksend-opentelemetry", "~> 0.1"
+```
+
+## Usage
+
+```ruby
+# config/initializers/clicksend.rb
+require "clicksend/opentelemetry"
+
+CLICKSEND = Clicksend::Client.new(instrumenter: Clicksend::OpenTelemetry::Instrumenter.new)
+```
+
+The instrumenter takes its tracer from the global provider when it is built. Before
+`OpenTelemetry::SDK.configure` runs, that is the API's proxy, which forwards to the SDK once it is
+configured, so the order of your initializers doesn't matter. Pass `tracer_provider:` to use
+another provider.
+
+To keep your `ActiveSupport::Notifications` subscribers as well, combine both with `FanOut`. Put
+the OpenTelemetry instrumenter **last**: its span then covers only the request, and a subscriber
+that raises after the request finished (which the client ignores) is not recorded as the span's
+error.
+
+```ruby
+CLICKSEND = Clicksend::Client.new(
+  instrumenter: Clicksend::OpenTelemetry::FanOut.new(ActiveSupport::Notifications, Clicksend::OpenTelemetry::Instrumenter.new)
+)
+```
+
+Options:
+- `base_url:` the client's `base_url`, if it isn't the default `https://rest.clicksend.com`. The
+  instrumentation payload has no host, so `server.address` and `server.port` come from here.
+- `record_path: false` leaves out `url.path`, and the path in the exception event's message. Paths never contain a query string, but some contain
+  a message ID (`sms.receipt`, `sms.cancel`), and paths you pass to `client.request` are recorded as
+  you wrote them.
+
+## What is recorded
+
+One span per API call, retries included: kind CLIENT, named `clicksend <operation>` (for example
+`clicksend sms.deliver`), or `clicksend <METHOD>` for `client.request` without `operation:`. Paths
+are never used in span names, because they can contain IDs. `sms.search_history` reads history page
+by page, so it produces one `clicksend sms.history` span per page.
+
+| Attribute | From |
+|---|---|
+| `http.request.method`, `url.path`, `server.address`, `server.port` | the call |
+| `http.response.status_code` | the last response, if there was one |
+| `error.type`, span status ERROR, an `exception` event | a failed call. The event's message is built from the class, HTTP status, ClickSend's `response_code` and the request line only, never from the exception's own message |
+| `clicksend.operation`, `clicksend.idempotent`, `clicksend.attempts`, `clicksend.ambiguous`, `clicksend.response_code` | the `request.clicksend` payload |
+
+Each retry adds a `clicksend.retry` event (`clicksend.retry.attempt`, `clicksend.retry.delay` in
+seconds, `error.type`, `http.response.status_code`).
+
+`http.request.method`, `server.*`, `url.path`, `http.response.status_code` and `error.type` are
+OpenTelemetry's stable HTTP attribute names. The span describes a logical call that may span
+several HTTP attempts, so it doesn't claim to be an HTTP client span: it has no `url.full`, and the
+attempt count is `clicksend.attempts`, not `http.request.resend_count` (which describes one
+physical request).
+
+Never recorded: phone numbers, message text, `custom_string`, request or response bodies, query
+strings, headers and credentials. The specs check the exported spans for each of these.
+
+A message ClickSend refuses inside an HTTP 200 (`Clicksend::MessageRejected`) is detected after the
+HTTP call succeeded, so its span is not an error.
+
+## HTTP-level instrumentation records the query string
+
+With `opentelemetry-instrumentation-faraday`, each HTTP attempt becomes a child CLIENT span of this
+gem's span (Net::HTTP's own span is then suppressed). With only
+`opentelemetry-instrumentation-net_http`, each attempt is a `GET`/`POST` span plus a `connect`
+span. **Those spans record the query string** (`url.full` or `url.query`), and
+`sms.history(to:)` and `sms.search_history` put the recipient's phone number there
+(`q=to:+61...`). Those instrumentations also send a `traceparent` header to ClickSend. This gem
+can't change what they record. With `opentelemetry-instrumentation-net_http` 0.29.1 and
+`-faraday` 0.33.0 (checked):
+- `untraced_hosts: ["rest.clicksend.com"]` on the Net::HTTP instrumentation drops its spans for
+  ClickSend and keeps this gem's span;
+- the Faraday instrumentation has no such option, so don't enable it in an application that
+  calls history by number. `OpenTelemetry::Common::Utilities.untraced { ... }` around a call
+  suppresses the Faraday span, but this gem's span too.
+
+## Guarantees
+
+The instrumenter never changes a call's outcome. Its own failures go to
+`OpenTelemetry.handle_error`, the request runs exactly once, and errors, including ambiguous
+ones, pass through unchanged. A send that times out is still a single-attempt, ambiguous
+`Clicksend::TimeoutError` with tracing on. The specs show this with a failing tracer, a failing
+span, a send timeout against `Clicksend::Testing::FakeAPI`, and a real local server.
+
+## Development
+
+The specs run against the `clicksend` in this repository (`path: "../.."` in the Gemfile), with
+their own bundle:
+
+```sh
+cd companions/clicksend-opentelemetry
+bundle install
+bundle exec rspec
+```
+
+When the core gem's version changes, run `bundle install` here too, so `Gemfile.lock` matches it.

data/lib/clicksend/opentelemetry/version.rb

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

data/lib/clicksend/opentelemetry.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require "uri"
+require "opentelemetry"
+require "clicksend"
+require_relative "opentelemetry/version"
+
+module Clicksend
+  # OpenTelemetry tracing for Clicksend::Client, built only on the client's
+  # public instrumenter hook (see Clicksend::Instrumentation):
+  #
+  #   require "clicksend/opentelemetry"
+  #
+  #   CLICKSEND = Clicksend::Client.new(instrumenter: Clicksend::OpenTelemetry::Instrumenter.new)
+  #
+  # Each logical API call (retries included) becomes one span of kind CLIENT,
+  # named after its operation ("clicksend sms.deliver"); each retry is a
+  # "clicksend.retry" event on it. Spans never hold phone numbers, message
+  # text, bodies, query strings, headers or credentials: only what the
+  # request.clicksend payload holds, plus the server address.
+  module OpenTelemetry
+    # Spans for request.clicksend, span events for retry.clicksend.
+    #
+    # The instrumenter never changes a call's outcome. Its own failures are
+    # sent to ::OpenTelemetry.handle_error, the request block runs exactly once
+    # whatever happens, and the request's own result or exception is passed
+    # through untouched. (Clicksend::Connection also ignores instrumenter
+    # failures after the request has run; this class does not rely on that.)
+    class Instrumenter
+      SPAN_KEY = ::OpenTelemetry::Context.create_key("clicksend-span")
+      private_constant :SPAN_KEY
+
+      # @param tracer_provider [#tracer] defaults to the global provider (a
+      #   proxy until the SDK is configured, so creating the client first is fine)
+      # @param base_url [String] the client's base_url, for server.address and
+      #   server.port (the instrumentation payload does not carry the host)
+      # @param record_path [Boolean] whether to set url.path. Paths never hold
+      #   query strings; some hold a message ID, and paths you pass to
+      #   Client#request are reported as written.
+      def initialize(tracer_provider: ::OpenTelemetry.tracer_provider, base_url: Clicksend::Client::DEFAULT_BASE_URL, record_path: true)
+        @tracer = tracer_provider.tracer("clicksend-opentelemetry", VERSION)
+        uri = URI.parse(base_url)
+        @server = {"server.address" => uri.host, "server.port" => uri.port}.freeze
+        @record_path = record_path
+        freeze
+      end
+
+      # The Clicksend::Instrumentation interface.
+      def instrument(name, payload = {}, &block)
+        case name
+        when "request.clicksend" then block ? trace(payload, &block) : nil
+        when "retry.clicksend" then add_retry_event(payload, &block)
+        else block&.call(payload)
+        end
+      end
+
+      def inspect
+        "#<#{self.class.name}>"
+      end
+
+      private
+
+      def trace(payload)
+        span = safely { @tracer.start_span(span_name(payload), kind: :client, attributes: start_attributes(payload)) }
+        token = safely { attach(span) } if span
+        begin
+          result = yield payload
+        rescue Exception => e # rubocop:disable Lint/RescueException
+          safely { record_failure(span, e) } if span
+          raise
+        ensure
+          safely { finish(span, token, payload) } if span
+        end
+        result
+      end
+
+      # Makes the span current, so HTTP-level spans (Faraday, Net::HTTP
+      # instrumentation) nest under it and retry events can find it.
+      def attach(span)
+        ::OpenTelemetry::Context.attach(::OpenTelemetry::Trace.context_with_span(span).set_value(SPAN_KEY, span))
+      end
+
+      def finish(span, token, payload)
+        ::OpenTelemetry::Context.detach(token) if token
+        attributes = {
+          "http.response.status_code" => payload[:http_status],
+          "clicksend.response_code" => payload[:response_code],
+          "clicksend.attempts" => payload[:attempts],
+          "clicksend.ambiguous" => payload[:ambiguous]
+        }.compact
+        span.add_attributes(attributes) unless attributes.empty?
+      ensure
+        span.finish
+      end
+
+      # The exception's message is never recorded: an API error's message holds
+      # ClickSend's response_msg, and a foreign exception's may hold anything.
+      def record_failure(span, error)
+        type = error.class.name || "Exception"
+        span.set_attribute("error.type", type)
+        span.add_event("exception", attributes: {
+          "exception.type" => type,
+          "exception.message" => safe_message(error),
+          "exception.stacktrace" => Array(error.backtrace).join("\n")
+        })
+        span.status = ::OpenTelemetry::Trace::Status.error(type)
+      end
+
+      def add_retry_event(payload)
+        safely do
+          span = ::OpenTelemetry::Context.current.value(SPAN_KEY)
+          span&.add_event("clicksend.retry", attributes: {
+            "clicksend.retry.attempt" => payload[:attempt],
+            "clicksend.retry.delay" => payload[:delay]&.to_f,
+            "error.type" => payload[:error_class],
+            "http.response.status_code" => payload[:http_status]
+          }.compact)
+        end
+        yield payload if block_given?
+      end
+
+      def span_name(payload)
+        payload[:operation] ? "clicksend #{payload[:operation]}" : "clicksend #{payload[:http_method].to_s.upcase}"
+      end
+
+      def start_attributes(payload)
+        attributes = @server.merge(
+          "http.request.method" => payload[:http_method].to_s.upcase,
+          "clicksend.operation" => payload[:operation],
+          "clicksend.idempotent" => payload[:idempotent]
+        )
+        attributes["url.path"] = payload[:path] if @record_path
+        attributes.compact
+      end
+
+      # Class, HTTP status, ClickSend's response_code and the request line:
+      # all already present in the request.clicksend payload. Without
+      # record_path the request line is the method alone.
+      def safe_message(error)
+        parts = [error.class.name]
+        parts << "HTTP #{error.http_status}" if error.respond_to?(:http_status) && error.http_status
+        parts << error.response_code if error.respond_to?(:response_code) && error.response_code.is_a?(String)
+        if error.is_a?(Clicksend::Error) && error.request
+          parts << (@record_path ? "(#{error.request})" : "(#{error.request.http_method.to_s.upcase})")
+        end
+        parts.join(" ")
+      end
+
+      def safely
+        yield
+      rescue => e
+        ::OpenTelemetry.handle_error(exception: e, message: "clicksend-opentelemetry")
+        nil
+      end
+    end
+
+    # Sends every event to several instrumenters by nesting them, so the
+    # request still runs exactly once:
+    #
+    #   Clicksend::OpenTelemetry::FanOut.new(ActiveSupport::Notifications, Clicksend::OpenTelemetry::Instrumenter.new)
+    #
+    # The first instrumenter is the outermost. Put the OpenTelemetry one last:
+    # its span then covers only the request, and an exception raised by an
+    # outer subscriber after the request finished (which the client ignores)
+    # is never recorded as the span's error.
+    class FanOut
+      def initialize(*instrumenters)
+        raise ArgumentError, "every instrumenter must respond to #instrument" unless instrumenters.all? { |i| i.respond_to?(:instrument) }
+
+        @instrumenters = instrumenters.freeze
+        freeze
+      end
+
+      def instrument(name, payload = {}, &block)
+        chain = @instrumenters.reverse.reduce(block) do |inner, instrumenter|
+          proc { |yielded| instrumenter.instrument(name, yielded || payload, &inner) }
+        end
+        chain&.call(payload)
+      end
+
+      def inspect
+        "#<#{self.class.name} #{@instrumenters.map(&:inspect).join(", ")}>"
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification
+name: clicksend-opentelemetry
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Amit Solanki
+- Braj Pratap Singh
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: clicksend
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-api
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+description: An instrumenter for Clicksend::Client that opens one CLIENT span per
+  ClickSend API call, with retries as span events. Never records phone numbers, message
+  text, bodies, query strings or credentials. Not affiliated with ClickSend.
+email:
+- amit@prayantr.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/clicksend/opentelemetry.rb
+- lib/clicksend/opentelemetry/version.rb
+homepage: https://github.com/prayantr/clicksend
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/prayantr/clicksend/tree/master/companions/clicksend-opentelemetry
+  changelog_uri: https://github.com/prayantr/clicksend/blob/master/companions/clicksend-opentelemetry/CHANGELOG.md
+  bug_tracker_uri: https://github.com/prayantr/clicksend/issues
+  documentation_uri: https://github.com/prayantr/clicksend/blob/master/companions/clicksend-opentelemetry/README.md
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
+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: OpenTelemetry spans for the clicksend gem's instrumentation hook.
+test_files: []