tarantool-opentelemetry 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 442ed8384e3de8f11710f2f653fb3d91967eb0c980264ca8bd7dd0a1f94f5231
+  data.tar.gz: 1a9cf8df40e0f0a4b892132205953221c903e5b119b5b3b040e5a305b395fef7
+SHA512:
+  metadata.gz: 82ed9d4aa063391c54c75a1bd428c556a1212cae27d6235fd128df7b2e1a7a81ac8182c7505cb640b9d829b47fd401ee21a78c09e56d553256f2382de6640ea3
+  data.tar.gz: 60b959f146d5902900e69af6082fb7847308e7b62112e4466b4dd11417724924f7d2da90e3bcf10a61836bbfb8c97e5d8bad58b3b25c7a1ea12de74dcb2bbd1e

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.0 (2026-10-17)
+
+First release.
+
+- `Tarantool::OpenTelemetry::Instrumenter`: an `instrumenter:` for `Tarantool::Client` and `Pool` that opens one
+  client span per request and lifecycle event, with `db.*` and `server.*` attributes; chains another
+  instrumenter; `db_statement: :include` adds the SQL text.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Starlexxx
+
+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,83 @@
+# tarantool-opentelemetry
+
+OpenTelemetry spans for [tarantool-client](../tarantool-client). The client reports every request and
+lifecycle event to an `instrumenter:`; this gem is one that opens a client span per event, so a Tarantool
+call shows up in a trace next to the HTTP and SQL spans of the application.
+
+## Installation
+
+Requirements: Ruby >= 3.2, `opentelemetry-api` 1.x; an SDK and exporter configured by the application as
+usual (`opentelemetry-sdk`, `opentelemetry-exporter-otlp`).
+
+```ruby
+gem 'tarantool-opentelemetry'
+```
+
+```ruby
+require 'tarantool/opentelemetry'
+
+client = Tarantool::Client.new('tcp://app:secret@db1:3301', instrumenter: Tarantool::OpenTelemetry::Instrumenter.new)
+pool = Tarantool::Client::Pool.new(uris, instrumenter: Tarantool::OpenTelemetry::Instrumenter.new)
+```
+
+`Pool` hands the instrumenter to every member. tarantool-crud and tarantool-model talk through the client, so
+their calls are traced too.
+
+## Options
+
+```ruby
+Tarantool::OpenTelemetry::Instrumenter.new(
+  instrumenter: ActiveSupport::Notifications,            # chained: receives every event, inside the span
+  tracer: OpenTelemetry.tracer_provider.tracer('my-app'), # default: tracer 'tarantool-client', its version
+  db_statement: :include                                  # default :omit; :include adds the SQL text
+)
+```
+
+The chained instrumenter gets the same event name, the same payload object and the original block, so
+tarantool-rails' log subscriber or a custom subscriber keeps working under the span.
+
+## Spans
+
+One span per event, kind client, the client's block run inside it (a span current in the caller becomes
+the parent).
+
+| Event | Span name | Attributes |
+|---|---|---|
+| `request.tarantool` | `tarantool.select users`, `tarantool.call crud.get`, `tarantool.execute`, `tarantool.ping`; `tarantool` when a space, index or field name failed to resolve and no request was built | `db.system` `tarantool`, `db.operation`, `db.tarantool.space`, `db.tarantool.index`, `db.tarantool.function`, `db.tarantool.statement_id`, `db.tarantool.schema_reloaded`, `db.statement` (only with `db_statement: :include`), `server.address`, `server.port` |
+| `disconnect.tarantool` | `tarantool.disconnect` | `tarantool.reason` |
+| `reconnect.tarantool` | `tarantool.reconnect` | `tarantool.attempts` |
+| `reconnect_failed.tarantool` | `tarantool.reconnect_failed` | `tarantool.attempts` |
+| `fork.tarantool` | `tarantool.fork` | |
+| `role_change.tarantool` | `tarantool.role_change` | `tarantool.read_only` |
+| `shutdown.tarantool` | `tarantool.shutdown` | `tarantool.pending` |
+
+Every span has `db.system` and, when the payload carries the instance address, `server.address` and
+`server.port` (a unix socket path goes to `server.address` alone). An attribute is set only when the payload
+has the key; Symbols become Strings, ids stay Integers.
+
+A request that raises gets the exception recorded on the span once, the status set to error with the
+exception's message, and the exception re-raised. Keys, tuples, call arguments, SQL bindings and credentials
+never appear: the client does not put them in the payload. `db.statement` is opt-in because the SQL text can
+carry literals.
+
+## Development
+
+```sh
+cd tarantool-opentelemetry
+bundle exec rspec                                                                  # unit, no server
+INTEGRATION=1 TARANTOOL_URI=tcp://app:secret@localhost:3301 bundle exec rspec     # against a client container
+```
+
+The integration specs need one of the tarantool-client containers (`podman compose -f
+tarantool-client/docker-compose.yml up -d --wait tarantool-2.11 tarantool-3`, ports 3301 and 3302).
+
+## Public API
+
+`Tarantool::OpenTelemetry::Instrumenter`.
+
+Everything else, including anything tagged `@api private` in its source comment, is an implementation detail
+and may change in any release.
+
+## License
+
+MIT, see [LICENSE](LICENSE).

data/lib/tarantool/opentelemetry/attributes.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module OpenTelemetry
+    # Span name and attributes of one client event. Only keys present in the payload become attributes, and the
+    # payload never carries keys, tuples, arguments or credentials; the SQL text is added only when asked for.
+    # @api private
+    module Attributes
+      REQUEST = 'request.tarantool'
+      DB_KEYS = {
+        request: 'db.operation', space: 'db.tarantool.space', index: 'db.tarantool.index',
+        function: 'db.tarantool.function', statement_id: 'db.tarantool.statement_id',
+        schema_reloaded: 'db.tarantool.schema_reloaded'
+      }.freeze
+      EVENT_KEYS = {
+        reason: 'tarantool.reason', attempts: 'tarantool.attempts', read_only: 'tarantool.read_only',
+        pending: 'tarantool.pending'
+      }.freeze
+      private_constant :REQUEST, :DB_KEYS, :EVENT_KEYS
+
+      module_function
+
+      def name(event, payload)
+        return "tarantool.#{event.delete_suffix('.tarantool')}" unless event == REQUEST
+        return 'tarantool' unless payload.key?(:request)
+
+        ['tarantool', payload[:request], payload[:space] || payload[:function]].compact.join(' ').sub(' ', '.')
+      end
+
+      def for(event, payload, db_statement:)
+        attributes = { 'db.system' => 'tarantool' }
+        keys = event == REQUEST ? DB_KEYS : EVENT_KEYS
+        keys.each { |key, attribute| attributes[attribute] = value(payload[key]) if payload.key?(key) }
+        attributes['db.statement'] = payload[:sql] if db_statement == :include && payload.key?(:sql)
+
+        attributes.merge(server(payload[:address]))
+      end
+
+      def value(value) = value.is_a?(Symbol) ? value.to_s : value
+
+      # host:port or [ipv6]:port; anything without a port is a unix socket path.
+      def server(address)
+        return {} if address.nil?
+
+        host, port = address.match(/\A\[?(.+?)\]?:(\d+)\z/)&.captures
+        return { 'server.address' => address } unless port
+
+        { 'server.address' => host, 'server.port' => port.to_i }
+      end
+    end
+  end
+end

data/lib/tarantool/opentelemetry/instrumenter.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Tarantool
+  module OpenTelemetry
+    # An instrumenter for Tarantool::Client and Pool: one client span per event, the block run inside it. Another
+    # instrumenter (ActiveSupport::Notifications, a logger wrapper) can be chained; it runs inside the span too.
+    class Instrumenter
+      DB_STATEMENT = %i[omit include].freeze
+      private_constant :DB_STATEMENT
+
+      def initialize(instrumenter: nil, tracer: nil, db_statement: :omit)
+        unless DB_STATEMENT.include?(db_statement)
+          raise ArgumentError, "db_statement must be :omit or :include, got #{db_statement.inspect}"
+        end
+
+        @instrumenter = instrumenter
+        @tracer = tracer || ::OpenTelemetry.tracer_provider.tracer('tarantool-client', Tarantool::Client::VERSION)
+        @db_statement = db_statement
+      end
+
+      # The client fills the payload (request, space, index, ...) inside the block, once names are resolved, so the
+      # name and attributes are set when the block is done. Finishing here rather than through Tracer#in_span records
+      # an exception once, with its message as the status description.
+      def instrument(name, payload, &block)
+        span = @tracer.start_span(Attributes.name(name, payload), kind: :client)
+        ::OpenTelemetry::Trace.with_span(span) { run(name, payload, &block) }
+      rescue StandardError => e
+        span&.record_exception(e)
+        span&.status = ::OpenTelemetry::Trace::Status.error(e.message)
+        raise
+      ensure
+        describe(span, name, payload) if span
+        span&.finish
+      end
+
+      private
+
+      def describe(span, name, payload)
+        span.name = Attributes.name(name, payload)
+        span.add_attributes(Attributes.for(name, payload, db_statement: @db_statement))
+      end
+
+      def run(name, payload, &)
+        @instrumenter ? @instrumenter.instrument(name, payload, &) : yield
+      end
+    end
+  end
+end

data/lib/tarantool/opentelemetry/version.rb

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

data/lib/tarantool/opentelemetry.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'opentelemetry'
+require 'tarantool/client'
+
+require_relative 'opentelemetry/version'
+require_relative 'opentelemetry/attributes'
+require_relative 'opentelemetry/instrumenter'
+
+module Tarantool
+  # OpenTelemetry spans for the events a Tarantool::Client emits through its instrumenter.
+  module OpenTelemetry
+  end
+end

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification
+name: tarantool-opentelemetry
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Starlexxx
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-10-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-api
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: tarantool-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+description: An instrumenter for tarantool-client that turns every request and lifecycle
+  event into an OpenTelemetry client span, with db.* attributes and without keys,
+  tuples or credentials.
+email:
+- apavlovskiy088@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/tarantool/opentelemetry.rb
+- lib/tarantool/opentelemetry/attributes.rb
+- lib/tarantool/opentelemetry/instrumenter.rb
+- lib/tarantool/opentelemetry/version.rb
+homepage: https://github.com/Starlexxx/tarantool-ruby
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/Starlexxx/tarantool-ruby/tree/master/tarantool-opentelemetry
+  changelog_uri: https://github.com/Starlexxx/tarantool-ruby/blob/master/tarantool-opentelemetry/CHANGELOG.md
+  bug_tracker_uri: https://github.com/Starlexxx/tarantool-ruby/issues
+  homepage_uri: https://github.com/Starlexxx/tarantool-ruby
+  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.2'
+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: OpenTelemetry spans for tarantool-client
+test_files: []