connectrpc-yabeda 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml ADDED
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA256:
3
+ metadata.gz: a706ddfb0b4f4fbc30355b99bdb15c9e9c2da5aa2bd1fc8ff50cb662b9e96b49
4
+ data.tar.gz: 4f3ccdda1030965c36c9825e8b574c9106eff4e8310db0d008171f1aed8c6f6e
5
+ SHA512:
6
+ metadata.gz: ce8785f5aa085e397cf93686d7ba7adc28480d427f27efc1c906395967a68eba90fd21ba9bf9b53669e6185db8091c9bf45f59a72ee535cfef36378541f80865
7
+ data.tar.gz: c939917965433e3b1433a5126e9c4f265c0d7ca6af159c6ecaa8ec2ac4ddf506824bb30f6df4214ea96bc769cbebda4a7ab903a092fa23f213e6b8ff7f7b5a6a
data/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Jim Myhrberg
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
data/README.md ADDED
@@ -0,0 +1,137 @@
1
+ <div align="center">
2
+
3
+ <img height="128px" width="128px" src="../../img/connectrpc-ruby.svg" alt="connectrpc-ruby logo">
4
+
5
+ # connectrpc-yabeda
6
+
7
+ **Yabeda metrics for ConnectRPC clients and servers.**
8
+
9
+ [![RubyGems](https://img.shields.io/gem/v/connectrpc-yabeda?logo=rubygems&logoColor=white&label=RubyGems)](https://rubygems.org/gems/connectrpc-yabeda)
10
+ [![CI](https://img.shields.io/github/actions/workflow/status/jimeh/connectrpc-ruby/ci.yml?branch=main&logo=github&label=CI)](https://github.com/jimeh/connectrpc-ruby/actions/workflows/ci.yml)
11
+ [![Docs](https://img.shields.io/badge/Docs-guides-0969da?logo=markdown&logoColor=white)](https://github.com/jimeh/connectrpc-ruby/tree/main/docs)
12
+ [![License](https://img.shields.io/github/license/jimeh/connectrpc-ruby?label=License)](https://github.com/jimeh/connectrpc-ruby/blob/main/LICENSE)
13
+
14
+ </div>
15
+
16
+ `connectrpc-yabeda` declares the same RPC, message, rejection and Async
17
+ connection metrics as [connectrpc-prometheus](../connectrpc-prometheus/README.md)
18
+ through [Yabeda](https://github.com/yabeda-rb/yabeda), so any Yabeda adapter
19
+ (Prometheus, Datadog, StatsD and others) receives them. Use it when your
20
+ application already records metrics through Yabeda.
21
+
22
+ The package is experimental. See the [supported 0.x contract](../../docs/support.md)
23
+ for the target support profile, matched package versions, compatibility policy
24
+ and adoption gates.
25
+
26
+ ## Installation
27
+
28
+ ```ruby
29
+ gem "connectrpc-yabeda", "~> 0.1.0"
30
+ gem "yabeda-prometheus" # or another Yabeda adapter
31
+ ```
32
+
33
+ The only runtime dependencies are `connectrpc ~> 0.1.0` and
34
+ `yabeda >= 0.16, < 1`. This package does not depend on `prometheus-client` or
35
+ any adapter; the application chooses and configures its adapters. Core and the
36
+ HTTP/framework packages do not depend on Yabeda.
37
+
38
+ ## Usage
39
+
40
+ ```ruby
41
+ require "connectrpc/yabeda"
42
+
43
+ metrics = ConnectRPC::Yabeda::Metrics.new(group: :grpc)
44
+ instrumentation = ConnectRPC::Instrumentation.new(
45
+ subscribers: [metrics.subscriber], on_error: ->(error) { application_logger.warn(error.class.name) }
46
+ )
47
+ # Pass instrumentation: instrumentation to ConnectRPC::Server.new and ConnectRPC::Client.new.
48
+ ```
49
+
50
+ `Metrics.new` declares its metrics through `Yabeda.configure`. Before
51
+ `Yabeda.configure!` the declaration is deferred, as for any Yabeda plugin;
52
+ after it, the metrics are declared immediately. Construct one `Metrics` per
53
+ group, typically in an initializer. Recording before `Yabeda.configure!` fails
54
+ inside the subscriber and is reported through the instrumentation's `on_error`
55
+ without changing the RPC; yabeda-rails and similar integrations call
56
+ `configure!` during boot.
57
+
58
+ `group:` (default `:grpc`, matching `/\A[a-z_][a-z0-9_]*\z/`) is the Yabeda group.
59
+ `duration_buckets:` and `size_buckets:` override the histogram buckets. For the
60
+ Async HTTP/2 client transport:
61
+
62
+ ```ruby
63
+ transport = ConnectRPC::Async::Transport.new(
64
+ origin: "https://billing.internal:8443",
65
+ connection_observer: metrics.connection_observer(transport: "billing")
66
+ )
67
+ ```
68
+
69
+ Transport names match `/\A[a-z0-9_]{1,64}\z/` and must be unique per process;
70
+ asking one `Metrics` for a repeated name raises `ArgumentError`. An observer
71
+ built after `Yabeda.configure!` publishes `idle` 1 and 0 for the other states
72
+ immediately. One built before it registers a Yabeda collector that publishes
73
+ its current state on each `Yabeda.collect!`, such as a yabeda-prometheus scrape;
74
+ until then its state series appear only as state changes record them. Async swallows connection observer
75
+ `StandardError`s, including recording before `configure!`, so those failures
76
+ are not reported through `on_error`. Callbacks may run from separate threads and fibers; Yabeda
77
+ stores values in concurrent structures, and adapters own their own safety.
78
+
79
+ ## Metrics and names
80
+
81
+ Each metric is declared with a group, name, optional unit, `comment`, `tags`
82
+ and, for histograms, `buckets`. The state gauge declares `aggregation: :sum`.
83
+ yabeda-prometheus exports `group_name_unit`, which produces exactly the
84
+ connectrpc-prometheus names, for example `grpc_server_handled_total`,
85
+ `grpc_server_handling_seconds` and `grpc_client_msg_sent_bytes`. Yabeda metric
86
+ keys omit the unit: `Yabeda.grpc_server_handling` is the latency histogram.
87
+
88
+ The [connectrpc-prometheus README](../connectrpc-prometheus/README.md#metrics)
89
+ is the reference for metrics, labels (tags), completion classification, message
90
+ size semantics, buckets and the `rpc_protocol` compatibility note. Both packages
91
+ record through the core `ConnectRPC::Metrics` layer, so values are identical.
92
+
93
+ ## Prometheus export and multi-process
94
+
95
+ With yabeda-prometheus, follow its exporter setup (`Yabeda::Prometheus::Exporter`
96
+ or yabeda-rails). The connectrpc-prometheus
97
+ [multi-process guidance](../connectrpc-prometheus/README.md#multi-process)
98
+ applies: the default store is correct for one process with any number of
99
+ threads; use `DirectFileStore` only for forked workers that share one
100
+ `/metrics` endpoint. Under `DirectFileStore`, build connection observers per
101
+ worker after fork. An observer built in the Puma or Unicorn master before fork,
102
+ including one passed to a `ThreadedTransport` created there, writes the
103
+ master's `idle` 1 to the store, and the summed state gauge keeps counting that
104
+ entry.
105
+
106
+ yabeda-prometheus 0.9.1 pins `prometheus-client >= 3, < 5`. prometheus-client
107
+ 4.x `DirectFileStore` calls `CGI.parse`, which Ruby 4.0 removed from the
108
+ default `cgi` library. On Ruby 4.0 with `DirectFileStore`, add the `cgi` gem to
109
+ the application's Gemfile. The default in-memory store does not need it.
110
+
111
+ ## Development
112
+
113
+ From the repository root use `mise run yabeda:setup`, `yabeda:test`,
114
+ `yabeda:check`, `yabeda:build`, `yabeda:package`, `yabeda:example`, and
115
+ `yabeda:verify`. Specs record through the `yabeda/testing` adapter. The
116
+ development bundle resolves the newest allowed versions and deliberately
117
+ excludes yabeda-prometheus: its `prometheus-client < 5` is below the range
118
+ connectrpc-prometheus supports. Name equality is structural through the shared definitions and checked
119
+ against yabeda-prometheus's `group_name_unit` rule. Caches and archives are in
120
+ `vendor/yabeda`, and coverage is in `coverage/yabeda/<Ruby>/`. Both pinned Ruby
121
+ 3.4.12 and 4.0.9 CI leaves run `yabeda:verify`.
122
+
123
+ `floors:yabeda` repeats specs and package checks with every runtime dependency
124
+ at its gemspec floor, including yabeda 0.16.0.
125
+
126
+ ## Static signatures
127
+
128
+ This package owns `sig/` and its discovery manifest. Add
129
+ `library "connectrpc-yabeda"` to a strict Steep target with this gem installed.
130
+ See the [RBS guide](../../docs/rbs.md) for supported APIs and extension
131
+ contracts.
132
+
133
+ ## License
134
+
135
+ Original project work is [MIT licensed](LICENSE), copyright 2026 Jim Myhrberg.
136
+ All package archives pin `allowed_push_host=https://rubygems.org`; these checks
137
+ never publish or release a gem.
@@ -0,0 +1,75 @@
1
+ # frozen_string_literal: true
2
+
3
+ module ConnectRPC
4
+ module Yabeda
5
+ # Declares the fixed ConnectRPC metric set through Yabeda.configure. Group,
6
+ # name and unit come from the shared definitions, so yabeda-prometheus
7
+ # exports the same names as connectrpc-prometheus.
8
+ class Metrics
9
+ attr_reader :definitions, :group, :subscriber
10
+
11
+ def initialize(group: :grpc, duration_buckets: ::ConnectRPC::Metrics::Definitions::DURATION_BUCKETS,
12
+ size_buckets: ::ConnectRPC::Metrics::Definitions::SIZE_BUCKETS)
13
+ @definitions = ::ConnectRPC::Metrics::Definitions.new(namespace: group, duration_buckets: duration_buckets,
14
+ size_buckets: size_buckets)
15
+ @group = @definitions.namespace.to_sym
16
+ Metrics.declare(@group, @definitions.instruments.values)
17
+ @recorder = Recorder.new(@definitions.instruments.keys.to_h do |key|
18
+ [key, "#{@group}_#{@definitions.fetch(key).name}"]
19
+ end)
20
+ @subscriber = ::ConnectRPC::Metrics::Subscriber.new(recorder: @recorder, definitions: @definitions)
21
+ @transports = {}
22
+ @mutex = Mutex.new
23
+ end
24
+
25
+ # One observer per transport name; a repeated name would merge two transports' states.
26
+ # Before Yabeda.configure! the metrics do not exist, and configure blocks run
27
+ # before adapters register them, so a collector publishes the state instead.
28
+ def connection_observer(transport:)
29
+ @mutex.synchronize do
30
+ raise ArgumentError, "transport #{transport.inspect} already has an observer" if @transports.key?(transport)
31
+
32
+ observer = ::ConnectRPC::Metrics::ConnectionObserver.new(recorder: @recorder, definitions: @definitions,
33
+ transport: transport)
34
+ ::Yabeda.configured? ? observer.publish_state : ::Yabeda.collect { observer.publish_state }
35
+ @transports[transport] = observer
36
+ end
37
+ end
38
+
39
+ # Runs now when Yabeda is already configured, otherwise at Yabeda.configure!.
40
+ def self.declare(group_name, instruments)
41
+ declarations = instruments.map { |instrument| declaration(instrument) }
42
+ ::Yabeda.configure do
43
+ group(group_name) { declarations.each { |kind, name, options| public_send(kind, name, **options) } }
44
+ end
45
+ end
46
+
47
+ # The Yabeda DSL method, metric name and options for one instrument.
48
+ def self.declaration(instrument)
49
+ options = { comment: instrument.help, tags: instrument.labels }
50
+ case instrument.kind
51
+ when :histogram then options.merge!(unit: instrument.unit, buckets: instrument.buckets)
52
+ when :gauge then options[:aggregation] = :sum
53
+ end
54
+ [instrument.kind, instrument.name.to_sym, options]
55
+ end
56
+
57
+ # The neutral recorder SPI over Yabeda metrics, resolved at record time so
58
+ # declaration may precede Yabeda.configure!.
59
+ class Recorder
60
+ def initialize(names)
61
+ @names = names.freeze
62
+ end
63
+
64
+ def increment(key, labels, by) = metric(key).increment(labels, by: by)
65
+ def observe(key, labels, value) = metric(key).measure(labels, value)
66
+ def set(key, labels, value) = metric(key).set(labels, value)
67
+
68
+ private
69
+
70
+ def metric(key) = ::Yabeda.metrics.fetch(@names.fetch(key))
71
+ end
72
+ private_constant :Recorder
73
+ end
74
+ end
75
+ end
@@ -0,0 +1,7 @@
1
+ # frozen_string_literal: true
2
+
3
+ module ConnectRPC
4
+ module Yabeda
5
+ VERSION = "0.1.1" # x-release-please-version
6
+ end
7
+ end
@@ -0,0 +1,6 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "connectrpc/metrics"
4
+ require_relative "yabeda/version"
5
+ require "yabeda"
6
+ require_relative "yabeda/metrics"
@@ -0,0 +1,14 @@
1
+ module ConnectRPC
2
+ module Yabeda
3
+ VERSION: String
4
+ class Metrics
5
+ # Declares through Yabeda.configure: immediately when Yabeda is configured, otherwise at Yabeda.configure!.
6
+ def initialize: (?group: String | Symbol, ?duration_buckets: Array[Numeric], ?size_buckets: Array[Numeric]) -> void
7
+ attr_reader definitions: ::ConnectRPC::Metrics::Definitions
8
+ attr_reader group: Symbol
9
+ attr_reader subscriber: ::ConnectRPC::Metrics::Subscriber
10
+ # Raises ArgumentError when this Metrics already has an observer for the transport name.
11
+ def connection_observer: (transport: String) -> ::ConnectRPC::Metrics::ConnectionObserver
12
+ end
13
+ end
14
+ end
data/sig/manifest.yaml ADDED
@@ -0,0 +1,2 @@
1
+ dependencies:
2
+ - name: connectrpc
metadata ADDED
@@ -0,0 +1,83 @@
1
+ --- !ruby/object:Gem::Specification
2
+ name: connectrpc-yabeda
3
+ version: !ruby/object:Gem::Version
4
+ version: 0.1.1
5
+ platform: ruby
6
+ authors:
7
+ - jimeh
8
+ bindir: bin
9
+ cert_chain: []
10
+ date: 2026-11-16 00:00:00.000000000 Z
11
+ dependencies:
12
+ - !ruby/object:Gem::Dependency
13
+ name: connectrpc
14
+ requirement: !ruby/object:Gem::Requirement
15
+ requirements:
16
+ - - "~>"
17
+ - !ruby/object:Gem::Version
18
+ version: 0.1.0
19
+ type: :runtime
20
+ prerelease: false
21
+ version_requirements: !ruby/object:Gem::Requirement
22
+ requirements:
23
+ - - "~>"
24
+ - !ruby/object:Gem::Version
25
+ version: 0.1.0
26
+ - !ruby/object:Gem::Dependency
27
+ name: yabeda
28
+ requirement: !ruby/object:Gem::Requirement
29
+ requirements:
30
+ - - ">="
31
+ - !ruby/object:Gem::Version
32
+ version: '0.16'
33
+ - - "<"
34
+ - !ruby/object:Gem::Version
35
+ version: '1'
36
+ type: :runtime
37
+ prerelease: false
38
+ version_requirements: !ruby/object:Gem::Requirement
39
+ requirements:
40
+ - - ">="
41
+ - !ruby/object:Gem::Version
42
+ version: '0.16'
43
+ - - "<"
44
+ - !ruby/object:Gem::Version
45
+ version: '1'
46
+ description: ConnectRPC RPC and connection metrics declared through Yabeda for any
47
+ Yabeda adapter. Experimental.
48
+ executables: []
49
+ extensions: []
50
+ extra_rdoc_files: []
51
+ files:
52
+ - LICENSE
53
+ - README.md
54
+ - lib/connectrpc/yabeda.rb
55
+ - lib/connectrpc/yabeda/metrics.rb
56
+ - lib/connectrpc/yabeda/version.rb
57
+ - sig/connectrpc-yabeda.rbs
58
+ - sig/manifest.yaml
59
+ homepage: https://github.com/jimeh/connectrpc-ruby
60
+ licenses:
61
+ - MIT
62
+ metadata:
63
+ allowed_push_host: https://rubygems.org
64
+ rubygems_mfa_required: 'true'
65
+ source_code_uri: https://github.com/jimeh/connectrpc-ruby
66
+ rdoc_options: []
67
+ require_paths:
68
+ - lib
69
+ required_ruby_version: !ruby/object:Gem::Requirement
70
+ requirements:
71
+ - - ">="
72
+ - !ruby/object:Gem::Version
73
+ version: '3.4'
74
+ required_rubygems_version: !ruby/object:Gem::Requirement
75
+ requirements:
76
+ - - ">="
77
+ - !ruby/object:Gem::Version
78
+ version: '0'
79
+ requirements: []
80
+ rubygems_version: 3.6.9
81
+ specification_version: 4
82
+ summary: Optional Yabeda metrics for ConnectRPC servers and clients
83
+ test_files: []