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 +7 -0
- data/LICENSE +21 -0
- data/README.md +137 -0
- data/lib/connectrpc/yabeda/metrics.rb +75 -0
- data/lib/connectrpc/yabeda/version.rb +7 -0
- data/lib/connectrpc/yabeda.rb +6 -0
- data/sig/connectrpc-yabeda.rbs +14 -0
- data/sig/manifest.yaml +2 -0
- metadata +83 -0
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
|
+
[](https://rubygems.org/gems/connectrpc-yabeda)
|
|
10
|
+
[](https://github.com/jimeh/connectrpc-ruby/actions/workflows/ci.yml)
|
|
11
|
+
[](https://github.com/jimeh/connectrpc-ruby/tree/main/docs)
|
|
12
|
+
[](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,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
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: []
|