gritz-otel 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3c13de06e63ce826aa5008be7098af391057f6a1c37fc5f48c09cf4c2e0a2a53
+  data.tar.gz: 9d6dc0a2a2918d253944a33f239cf65294a43e08383373c1a0dfd5f3fe0f57bb
+SHA512:
+  metadata.gz: 2e2f301f80ccbc3274444719b05d3f431456baa300753ef4d5a1ceef91b13470a259486538a26a875c1122d40d7042239fba1d4c295367520b63dc0b1499c5d0
+  data.tar.gz: 1346f9c98c2bce145ccbc172dc054f1183d7661c86d3591df14f84f9158ee1b870eebb86efe810b3f2905811ca2e3d6700e0734f8cbb97eb6932ce18acbd526c

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## 0.1.0
+
+Initial release.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 ydah
+
+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,72 @@
+# Gritz OpenTelemetry
+
+Server and client spans and worker OTLP metrics for [Gritz](https://github.com/gritzrpc/gritz). SDK providers and exporters start in worker boot hooks, after fork. This optional integration depends on `gritz-core`; applications choose their transport separately.
+
+Requires CRuby 3.3 or later and Gritz 0.4.0. The OpenTelemetry metrics SDK is currently alpha; this gem pins its supported minor versions.
+
+## Installation and configuration
+
+```ruby
+gem "gritz", "~> 0.4.0"
+gem "gritz-otel", git: "https://github.com/gritzrpc/gritz-otel.git", branch: "main"
+```
+
+The first `gritz-otel` release is being prepared. Until it is published, use the source dependency above. After publication, use `gem "gritz-otel", "~> 0.1.0"`.
+
+In the Gritz configuration file:
+
+```ruby
+require "gritz/otel"
+
+metrics_backend :otlp
+opentelemetry do |sdk|
+  sdk.service_name = "greeter"
+end
+```
+
+Set `OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318/` for OTLP/HTTP protobuf. Standard exporter endpoint, headers, certificate and compression environment variables are supported. Traces go to `/v1/traces` and metrics to `/v1/metrics`. With the default `metrics_backend :pipe`, the integration adds tracing while retaining the built-in Prometheus metrics.
+
+For a configuration object, use `Gritz::Otel.install(config) { |sdk| ... }`. The SDK block executes in each worker; create custom processors or exporters inside that block. Register the integration before starting the server. The integration owns one SDK configuration per worker process and closes its providers after application shutdown hooks and final RPC observations.
+
+## Tracing
+
+Server spans surround complete dispatch, including streaming and error mapping. `Gritz::Client` spans surround complete outgoing calls and response consumption, with native cancellation on early exit. Incoming W3C `traceparent` and `tracestate` are extracted and outgoing child contexts are injected. Lazy clients retain the context captured when the call was created. Incoming credentials and baggage are not automatically forwarded.
+
+Spans include the service, method and final gRPC status. They omit protobuf payloads and exception messages. See the [client guide](https://github.com/gritzrpc/gritz-core/blob/main/docs/guides/clients.md).
+
+## Worker metrics
+
+With `metrics_backend :otlp`, each worker records:
+
+| Instrument | Meaning |
+| --- | --- |
+| `gritz.rpc.server.duration` | Completed RPC duration, in seconds |
+| `gritz.rpc.server.requests`, `gritz.rpc.server.responses` | Messages per completed RPC |
+| `gritz.rpc.server.rejected` | Overload rejections |
+| `gritz.worker.inflight`, `gritz.worker.busy_threads`, `gritz.worker.capacity` | Worker occupancy and capacity |
+| `gritz.worker.state` | Current lifecycle state |
+| `gritz.worker.rss_bytes`, `gritz.worker.pss_bytes` | Actual Linux process memory |
+
+Worker PID and index identify each observation; service/method/status identify RPC histograms. The collector receives cumulative SDK metrics from individual workers. Master restart counts and framework-wide totals remain available through Admin `/metrics`; OTLP continues to mirror RPC deltas to the built-in pipe backend.
+
+Worker status heartbeats drive official SDK metric collection and HTTP export. Each heartbeat export is bounded by the smallest of one second, half `status_interval`, and a quarter of `shutdown_timeout`. A failed observation or export retains pipe data and does not fail the RPC. Final export and provider shutdown share the remaining graceful shutdown budget; telemetry may be dropped when that budget expires.
+
+## Development and releases
+
+```sh
+bundle install
+COVERAGE=1 bundle exec rake
+bundle exec rubocop
+bundle exec bundler-audit check --update
+bundle exec rake build
+```
+
+Tests include a real Linux three-service chain with an OTLP/HTTP protobuf collector. Core and native development dependencies use their Git repositories; runtime dependencies use published gems. See [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md) and the [release guide](docs/guides/releasing.md).
+
+See the [three-service integration report](docs/reports/T4-08-client-chain.md) for the completion checks and reproduction commands.
+
+The initial release is prepared for the project owner. Do not publish its first tag automatically.
+
+## License
+
+[MIT](LICENSE.txt).

data/lib/gritz/otel/recorder.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Gritz
+  module Otel
+    # Preserve pipe deltas while recording worker-local SDK instruments.
+    class Recorder < Gritz::Metrics::Recorder
+      def initialize(worker:, exporter: nil, timeout: 1.0)
+        super()
+        @exporter = exporter
+        @timeout = timeout
+        @attributes = { "worker.index" => worker, "process.pid" => Process.pid }
+        @rejected = 0
+        return unless exporter
+
+        meter = OpenTelemetry.meter_provider.meter("gritz", version: VERSION)
+        @duration = meter.create_histogram("gritz.rpc.server.duration", unit: "s")
+        @requests = meter.create_histogram("gritz.rpc.server.requests", unit: "{message}")
+        @responses = meter.create_histogram("gritz.rpc.server.responses", unit: "{message}")
+        @rejections = meter.create_counter("gritz.rpc.server.rejected", unit: "{request}")
+        @gauges = %w[inflight busy_threads capacity rss_bytes pss_bytes].to_h do |name|
+          [name, meter.create_gauge("gritz.worker.#{name}")]
+        end
+        @state = meter.create_gauge("gritz.worker.state")
+      end
+
+      def record_rpc(service:, method:, code:, duration:, requests:, responses:)
+        super
+        return unless @exporter
+
+        attributes = @attributes.merge("rpc.system" => "grpc", "rpc.service" => service, "rpc.method" => method, "rpc.grpc.status_code" => code)
+        observe_telemetry do
+          @duration.record(duration, attributes:)
+          @requests.record(requests, attributes:)
+          @responses.record(responses, attributes:)
+        end
+      end
+
+      def observe_rejected(total)
+        super
+        observe_telemetry do
+          @rejections&.add(total - @rejected, attributes: @attributes)
+          @rejected = total
+        end
+      end
+
+      def observe_worker(status)
+        return unless @exporter
+
+        observe_telemetry do
+          @gauges.each { |name, gauge| gauge.record(status.fetch(name.to_sym, 0), attributes: @attributes) unless name.end_with?("_bytes") }
+          memory.each { |name, value| @gauges.fetch(name).record(value, attributes: @attributes) }
+          %w[booting ready draining failed stopped].each do |state|
+            @state.record(state == status[:state] ? 1 : 0, attributes: @attributes.merge("state" => state))
+          end
+          # The official exporter is also a MetricReader. Heartbeats drive bounded exports,
+          # avoiding the alpha SDK periodic reader's unbounded shutdown join.
+          @exporter.export(@exporter.collect, timeout: @timeout) unless status[:state] == "stopped"
+        end
+      end
+
+      def close(timeout: @timeout)
+        Otel.shutdown(timeout:)
+      end
+
+      private
+
+      def observe_telemetry
+        yield
+      rescue StandardError => e
+        OpenTelemetry.logger.warn("Gritz metrics observation failed (#{e.class})")
+      end
+
+      def memory
+        return {} unless File.readable?("/proc/self/smaps_rollup")
+
+        File.read("/proc/self/smaps_rollup").scan(/^(Rss|Pss):\s+(\d+)\s+kB$/).to_h.transform_keys { |key| "#{key.downcase}_bytes" }
+            .transform_values { |value| value.to_i * 1024 }
+      rescue SystemCallError
+        {}
+      end
+    end
+  end
+end

data/lib/gritz/otel/tracing.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Gritz
+  module Otel
+    # @api private
+    module Tracing
+      def self.within(context, kind:, parent:, &block)
+        OpenTelemetry::Context.with_current(parent) do
+          span = start_span(context, kind)
+          code = 0
+          begin
+            OpenTelemetry::Trace.with_span(span, &block)
+          rescue Gritz::Error => e
+            code = e.grpc_code
+            raise
+          rescue StandardError
+            code = 13
+            raise
+          ensure
+            code = 1 if code.zero? && context.cancelled?
+            finish_span(span, code)
+          end
+        end
+      end
+
+      def self.start_span(context, kind)
+        attributes = { "rpc.system" => "grpc", "rpc.service" => context.method.service, "rpc.method" => context.method.name }
+        OpenTelemetry.tracer_provider.tracer("gritz", VERSION).start_span(context.method.full_name, kind:, attributes:)
+      rescue StandardError => e
+        OpenTelemetry.logger.warn("Gritz tracing failed to start (#{e.class})")
+        OpenTelemetry::Trace::Span::INVALID
+      end
+
+      def self.finish_span(span, code)
+        span.set_attribute("rpc.grpc.status_code", code)
+        span.status = OpenTelemetry::Trace::Status.error("RPC failed") unless code.zero?
+        span.finish
+      rescue StandardError => e
+        OpenTelemetry.logger.warn("Gritz tracing failed to finish (#{e.class})")
+      end
+    end
+
+    # Wraps the complete server dispatch, including streaming and error mapping.
+    class ServerTracing
+      def initialize(app) = @app = app
+
+      def call(context)
+        return @app.call(context) if ENV["OTEL_SDK_DISABLED"] == "true"
+
+        carrier = context.metadata.slice("traceparent", "tracestate").transform_values do |value|
+          value.is_a?(Array) ? value.join(",") : value
+        end
+        parent = OpenTelemetry.propagation.extract(carrier, context: OpenTelemetry::Context.empty)
+        Tracing.within(context, kind: :server, parent:) do
+          context.trace_context = OpenTelemetry::Context.current
+          @app.call(context)
+        end
+      end
+    end
+
+    # Capture the caller when the invocation is created, before lazy stream consumption.
+    class ClientTracing
+      def initialize(app)
+        @app = app
+        @parent = OpenTelemetry::Context.current
+      end
+
+      def call(context)
+        return @app.call(context) if ENV["OTEL_SDK_DISABLED"] == "true"
+
+        parent = context.parent&.trace_context
+        parent = @parent unless parent.is_a?(OpenTelemetry::Context)
+        Tracing.within(context, kind: :client, parent:) do
+          context.trace_context = OpenTelemetry::Context.current
+          carrier = {}
+          OpenTelemetry.propagation.inject(carrier)
+          context.metadata.delete("traceparent")
+          context.metadata.delete("tracestate")
+          context.metadata.merge!(carrier.slice("traceparent", "tracestate"))
+          @app.call(context)
+        end
+      end
+    end
+  end
+end

data/lib/gritz/otel/version.rb

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

data/lib/gritz/otel.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "gritz/core"
+require "opentelemetry-api"
+require_relative "otel/version"
+require_relative "otel/tracing"
+require_relative "otel/recorder"
+
+module Gritz
+  module Otel
+    # Configuration-file syntax for this optional integration.
+    module ConfigurationDSL
+      def opentelemetry(&) = Otel.install(@config, &)
+    end
+
+    class << self
+      # Registration is safe before fork; SDK providers/exporters are built in the worker hook.
+      def install(config, &configure)
+        return config if config.middleware.entries.any? { |entry| entry.middleware == ServerTracing }
+        raise Gritz::ConfigurationError, "a metrics recorder is already installed" if config.metrics_recorder_factory
+
+        config.middleware.insert_after(Gritz::Middleware::Context, ServerTracing)
+        unless Gritz::Client.middleware.entries.any? { |entry| entry.middleware == ClientTracing }
+          Gritz::Client.middleware.use(ClientTracing)
+        end
+        config.add_hook(:on_worker_boot) { bootstrap(config, &configure) }
+        config.metrics_recorder_factory = ->(worker:) { Recorder.new(worker:, exporter: @metrics_exporter, timeout: export_timeout(config)) }
+        config
+      end
+
+      # @api private
+      def bootstrap(config, &configure)
+        return if @pid == Process.pid
+
+        @metrics_exporter = @tracer_provider = @meter_provider = nil
+        return if ENV["OTEL_SDK_DISABLED"] == "true"
+
+        require "opentelemetry/sdk"
+        require "opentelemetry/exporter/otlp"
+        if config.metrics_backend == :otlp
+          require "opentelemetry-metrics-sdk"
+          require "opentelemetry-exporter-otlp-metrics"
+          @metrics_exporter = OpenTelemetry::Exporter::OTLP::Metrics::MetricsExporter.new
+        end
+        # SDK.configure swallows boot exceptions; the same official configurator
+        # lets an invalid worker configuration reach Gritz's startup failure path.
+        sdk = OpenTelemetry::SDK::Configurator.new
+        sdk.resource = OpenTelemetry::SDK::Resources::Resource.create("process.pid" => Process.pid, "service.instance.id" => Process.pid.to_s)
+        sdk.add_metric_reader(@metrics_exporter) if @metrics_exporter
+        # The metrics SDK patches the process-wide configurator once it is loaded.
+        # A trace-only worker must not create its default background metric reader.
+        if !@metrics_exporter && sdk.respond_to?(:add_metric_reader)
+          sdk.add_metric_reader(OpenTelemetry::SDK::Metrics::Export::MetricReader.new)
+        end
+        configure&.call(sdk)
+        sdk.configure
+        @tracer_provider = OpenTelemetry.tracer_provider
+        @meter_provider = OpenTelemetry.meter_provider if OpenTelemetry.respond_to?(:meter_provider)
+        if @metrics_exporter
+          { "duration" => Metrics::Recorder::DURATION_BUCKETS, "requests" => Metrics::Recorder::MESSAGE_BUCKETS,
+            "responses" => Metrics::Recorder::MESSAGE_BUCKETS }.each do |name, bounds|
+            aggregation = OpenTelemetry::SDK::Metrics::Aggregation::ExplicitBucketHistogram.new(boundaries: bounds.select(&:finite?))
+            @meter_provider.add_view("gritz.rpc.server.#{name}", aggregation:, type: :histogram, meter_name: "gritz", meter_version: VERSION)
+          end
+        end
+        @pid = Process.pid
+      end
+
+      # @api private
+      def shutdown(timeout:)
+        return unless @pid == Process.pid
+
+        @pid = nil
+        deadline = monotonic + timeout
+        if @metrics_exporter && timeout.positive?
+          shutdown_component { @metrics_exporter.export(@metrics_exporter.collect, timeout: timeout / 2.0) }
+        end
+        shutdown_component { @tracer_provider&.shutdown(timeout: [deadline - monotonic, 0].max) }
+      ensure
+        shutdown_component { @meter_provider&.shutdown(timeout: [deadline - monotonic, 0].max) } if deadline
+        @metrics_exporter = @tracer_provider = @meter_provider = nil if deadline
+      end
+
+      # Keep a slow collector within the worker's heartbeat and shutdown budgets.
+      # @api private
+      def export_timeout(config) = [1.0, config.status_interval / 2.0, config.shutdown_timeout / 4.0].min
+      def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      private
+
+      def shutdown_component
+        yield
+      rescue StandardError => e
+        OpenTelemetry.logger.warn("Gritz telemetry shutdown failed (#{e.class})")
+      end
+    end
+  end
+end
+
+Gritz::DSL.prepend(Gritz::Otel::ConfigurationDSL)

metadata

@@ -0,0 +1,123 @@
+--- !ruby/object:Gem::Specification
+name: gritz-otel
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Yudai Takada
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: gritz-core
+  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
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.35.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.35.0
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-exporter-otlp-metrics
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.13.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.13.0
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-metrics-sdk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.19.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.19.0
+- !ruby/object:Gem::Dependency
+  name: opentelemetry-sdk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.13.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.13.0
+description: Server and client tracing and worker OTLP metrics for Gritz, initialized
+  after fork.
+email:
+- t.yudai92@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/gritz/otel.rb
+- lib/gritz/otel/recorder.rb
+- lib/gritz/otel/tracing.rb
+- lib/gritz/otel/version.rb
+homepage: https://github.com/gritzrpc/gritz-otel
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/gritzrpc/gritz-otel/
+  source_code_uri: https://github.com/gritzrpc/gritz-otel
+  changelog_uri: https://github.com/gritzrpc/gritz-otel/blob/main/CHANGELOG.md
+  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.16
+specification_version: 4
+summary: Fork-safe OpenTelemetry integration for Gritz
+test_files: []