turbopuffer 2.8.0 → 2.9.0
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 +4 -4
- data/CHANGELOG.md +9 -0
- data/README.md +15 -1
- data/lib/turbopuffer/client.rb +7 -0
- data/lib/turbopuffer/internal/respond_async.rb +1 -1
- data/lib/turbopuffer/internal/telemetry.rb +462 -0
- data/lib/turbopuffer/internal/transport/base_client.rb +50 -21
- data/lib/turbopuffer/internal/transport/pooled_net_requester.rb +77 -2
- data/lib/turbopuffer/internal/transport/request_observer.rb +377 -0
- data/lib/turbopuffer/models/attribute_schema_config.rb +1 -0
- data/lib/turbopuffer/models/branch_from_namespace_params.rb +3 -0
- data/lib/turbopuffer/models/copy_from_namespace_operation.rb +8 -1
- data/lib/turbopuffer/models/copy_from_namespace_operation_result.rb +5 -3
- data/lib/turbopuffer/models/copy_from_namespace_params.rb +3 -0
- data/lib/turbopuffer/models/full_text_search.rb +1 -0
- data/lib/turbopuffer/models/id.rb +1 -1
- data/lib/turbopuffer/models/namespace_hint_cache_warm_response.rb +2 -1
- data/lib/turbopuffer/models/namespace_metadata.rb +10 -1
- data/lib/turbopuffer/models/namespace_metadata_patch.rb +1 -0
- data/lib/turbopuffer/models/namespace_multi_query_params.rb +1 -0
- data/lib/turbopuffer/models/namespace_multi_query_response.rb +19 -2
- data/lib/turbopuffer/models/namespace_query_response.rb +10 -2
- data/lib/turbopuffer/models/namespace_recall_response.rb +5 -0
- data/lib/turbopuffer/models/namespace_start_copy_from_response.rb +2 -0
- data/lib/turbopuffer/models/namespace_write_params.rb +3 -3
- data/lib/turbopuffer/models/operation_error.rb +2 -0
- data/lib/turbopuffer/models/write_result.rb +1 -1
- data/lib/turbopuffer/resources/namespaces.rb +1 -1
- data/lib/turbopuffer/version.rb +1 -1
- data/lib/turbopuffer.rb +2 -0
- data/rbi/turbopuffer/client.rbi +5 -0
- data/rbi/turbopuffer/internal/telemetry.rbi +275 -0
- data/rbi/turbopuffer/internal/transport/base_client.rbi +13 -2
- data/rbi/turbopuffer/internal/transport/pooled_net_requester.rbi +47 -1
- data/rbi/turbopuffer/internal/transport/request_observer.rbi +340 -0
- data/rbi/turbopuffer/models/branch_from_namespace_params.rbi +1 -0
- data/rbi/turbopuffer/models/copy_from_namespace_operation.rbi +4 -0
- data/rbi/turbopuffer/models/copy_from_namespace_operation_result.rbi +8 -3
- data/rbi/turbopuffer/models/copy_from_namespace_params.rbi +1 -0
- data/rbi/turbopuffer/models/namespace_hint_cache_warm_response.rbi +2 -0
- data/rbi/turbopuffer/models/namespace_metadata.rbi +5 -0
- data/rbi/turbopuffer/models/namespace_multi_query_response.rbi +17 -1
- data/rbi/turbopuffer/models/namespace_query_response.rbi +8 -1
- data/rbi/turbopuffer/models/namespace_recall_response.rbi +4 -0
- data/rbi/turbopuffer/models/namespace_start_copy_from_response.rbi +1 -0
- data/rbi/turbopuffer/models/namespace_write_params.rbi +3 -3
- data/rbi/turbopuffer/models/operation_error.rbi +1 -0
- data/rbi/turbopuffer/models/write_result.rbi +1 -1
- data/rbi/turbopuffer/resources/namespaces.rbi +2 -1
- data/sig/turbopuffer/client.rbs +1 -0
- data/sig/turbopuffer/internal/telemetry.rbs +129 -0
- data/sig/turbopuffer/internal/transport/base_client.rbs +5 -1
- data/sig/turbopuffer/internal/transport/pooled_net_requester.rbs +15 -1
- data/sig/turbopuffer/internal/transport/request_observer.rbs +153 -0
- metadata +8 -2
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 9787f889c45e5fc5892d8a76e508413d80f5af373c6c04ed8a91a87ad5abe0c0
|
|
4
|
+
data.tar.gz: 400686f51741d20a8dd15c0f58ad8054d6d1b5ed41afe06e8db1849ade2ab5c9
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 2e063904070bd100a6bc86eb9dfc0cba61e9b6ae9d5c148390e358f3cd25d2d33be0937910b6da7428c7e8e5cd7aea32de85d92a98827064ef74fa363b7e5e6e
|
|
7
|
+
data.tar.gz: d8931336b1455bcde03bf1fcbafe73409c5e13a537e71e8f5397b4703b5299757f60d266da9a4806f6889c68aacee47f9da9a2bfc33d1484f419cbbc4ff50df7
|
data/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,14 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## [2.9.0](https://github.com/turbopuffer/turbopuffer-ruby/compare/v2.8.0...v2.9.0) (2026-10-20)
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
### Features
|
|
7
|
+
|
|
8
|
+
* Bound document IDs to 0 so they become `u64` in Rust ([b5b3f8d](https://github.com/turbopuffer/turbopuffer-ruby/commit/b5b3f8d237cd8a488634cbc83a2bc67e0318e7da))
|
|
9
|
+
* Listen via request observer and send client telemetry ([ac17f80](https://github.com/turbopuffer/turbopuffer-ruby/commit/ac17f80196e631bd114270ba75b2b34a244f8e5f))
|
|
10
|
+
* OpenAPI: Add missing descriptions to prettify docblocks in output SDKs ([712aef9](https://github.com/turbopuffer/turbopuffer-ruby/commit/712aef9d7f7b21807a7aef09509a158a6317611c))
|
|
11
|
+
|
|
3
12
|
## [2.8.0](https://github.com/turbopuffer/turbopuffer-ruby/compare/v2.7.0...v2.8.0) (2026-10-13)
|
|
4
13
|
|
|
5
14
|
|
data/README.md
CHANGED
|
@@ -17,7 +17,7 @@ To use this gem, install via Bundler by adding the following to your application
|
|
|
17
17
|
<!-- x-release-please-start-version -->
|
|
18
18
|
|
|
19
19
|
```ruby
|
|
20
|
-
gem "turbopuffer", "~> 2.
|
|
20
|
+
gem "turbopuffer", "~> 2.9.0"
|
|
21
21
|
```
|
|
22
22
|
|
|
23
23
|
<!-- x-release-please-end -->
|
|
@@ -173,6 +173,20 @@ turbopuffer = Turbopuffer::Client.new(
|
|
|
173
173
|
turbopuffer.namespaces(prefix: "foo", request_options: {compression: true})
|
|
174
174
|
```
|
|
175
175
|
|
|
176
|
+
### Client telemetry
|
|
177
|
+
|
|
178
|
+
The client can report its own request timings to turbopuffer to help diagnose latency between your application and the API. Telemetry is disabled by default. To enable it, set the `TURBOPUFFER_TELEMETRY` environment variable to `1`, or pass `telemetry: true`:
|
|
179
|
+
|
|
180
|
+
```ruby
|
|
181
|
+
turbopuffer = Turbopuffer::Client.new(
|
|
182
|
+
telemetry: true
|
|
183
|
+
)
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
An explicit `telemetry: false` disables telemetry even when the environment variable is set.
|
|
187
|
+
|
|
188
|
+
When enabled, timings for completed requests are attached to subsequent requests in the `X-turbopuffer-Client-Telemetry` header, so no additional requests are made. Each record contains the request's method and path with the namespace name removed, its status code, retry count, whether it reused an existing connection, and client-side durations (serialization, waiting for a free connection, connecting, sending, waiting for the response, reading the response body, and deserialization). Request and response bodies and API keys are never included. turbopuffer may ask the client to record only a sample of requests.
|
|
189
|
+
|
|
176
190
|
## Advanced concepts
|
|
177
191
|
|
|
178
192
|
### BaseModel
|
data/lib/turbopuffer/client.rb
CHANGED
|
@@ -85,6 +85,9 @@ module Turbopuffer
|
|
|
85
85
|
#
|
|
86
86
|
# @param compression [Boolean] Whether to request compressed responses. Defaults to false.
|
|
87
87
|
#
|
|
88
|
+
# @param telemetry [Boolean, nil] Whether to report client-side request timings to turbopuffer on
|
|
89
|
+
# subsequent requests. Defaults to `ENV["TURBOPUFFER_TELEMETRY"]`, and is off when that's unset.
|
|
90
|
+
#
|
|
88
91
|
# @param max_retries [Integer] Max number of retries to attempt after a failed retryable request.
|
|
89
92
|
#
|
|
90
93
|
# @param timeout [Float]
|
|
@@ -98,6 +101,7 @@ module Turbopuffer
|
|
|
98
101
|
default_namespace: nil,
|
|
99
102
|
base_url: ENV["TURBOPUFFER_BASE_URL"],
|
|
100
103
|
compression: false,
|
|
104
|
+
telemetry: nil,
|
|
101
105
|
max_retries: self.class::DEFAULT_MAX_RETRIES,
|
|
102
106
|
timeout: self.class::DEFAULT_TIMEOUT_IN_SECONDS,
|
|
103
107
|
initial_retry_delay: self.class::DEFAULT_INITIAL_RETRY_DELAY,
|
|
@@ -143,6 +147,9 @@ module Turbopuffer
|
|
|
143
147
|
max_retry_delay: max_retry_delay,
|
|
144
148
|
headers: headers
|
|
145
149
|
)
|
|
150
|
+
|
|
151
|
+
buffer = Turbopuffer::Internal::Telemetry.buffer_for(telemetry, @api_key, @base_url.to_s)
|
|
152
|
+
self.request_observer = Turbopuffer::Internal::Telemetry::Observer.new(buffer) if buffer
|
|
146
153
|
end
|
|
147
154
|
end
|
|
148
155
|
end
|
|
@@ -157,7 +157,7 @@ module Turbopuffer
|
|
|
157
157
|
sleep(timeout.sleep_duration)
|
|
158
158
|
nil
|
|
159
159
|
in {status: "finished", result: {success: success}}
|
|
160
|
-
response = Net::HTTPOK.new("1.1", 200, "OK")
|
|
160
|
+
response = Net::HTTPOK.new("1.1", "200", "OK")
|
|
161
161
|
response["content-type"] = "application/json"
|
|
162
162
|
[200, response, [JSON.generate(success)]]
|
|
163
163
|
in {status: "finished", result: {error: {status_code: Integer => err_status, **rest}}}
|
|
@@ -0,0 +1,462 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module Turbopuffer
|
|
4
|
+
module Internal
|
|
5
|
+
# Client telemetry reported to turbopuffer on subsequent requests.
|
|
6
|
+
#
|
|
7
|
+
# When enabled, the client buffers a small timing record for each request and
|
|
8
|
+
# attaches buffered records to a later request in the `X-turbopuffer-Client-Telemetry`
|
|
9
|
+
# header. The server controls how many requests are recorded by advertising a
|
|
10
|
+
# sample rate in the `X-turbopuffer-Client-Telemetry-Sample-Rate` response header.
|
|
11
|
+
#
|
|
12
|
+
# @api private
|
|
13
|
+
module Telemetry
|
|
14
|
+
ENV_VAR = "TURBOPUFFER_TELEMETRY"
|
|
15
|
+
HEADER = "x-turbopuffer-client-telemetry"
|
|
16
|
+
SAMPLE_RATE_HEADER = "x-turbopuffer-client-telemetry-sample-rate"
|
|
17
|
+
|
|
18
|
+
ENVELOPE_VERSION = 1
|
|
19
|
+
|
|
20
|
+
# Keeps the header well under the 8 KB per-line limit of common proxies.
|
|
21
|
+
MAX_RECORDS_PER_HEADER = 20
|
|
22
|
+
MAX_BUFFERED_RECORDS = 1000
|
|
23
|
+
|
|
24
|
+
TRUE_VALUES = %w[1 true yes on].freeze
|
|
25
|
+
FALSE_VALUES = ["", "0", "false", "no", "off"].freeze
|
|
26
|
+
|
|
27
|
+
NAMESPACE_RE = %r{\A(/v\d+/namespaces/)[^/?]+}
|
|
28
|
+
OPERATION_RE = %r{(/operations/)[^/?]+}
|
|
29
|
+
SCHEME_AND_HOST_RE = %r{\A[a-z][a-z\d+\-.]*://[^/?#]*}i
|
|
30
|
+
|
|
31
|
+
class << self
|
|
32
|
+
# @api private
|
|
33
|
+
#
|
|
34
|
+
# Resolves whether telemetry is enabled, preferring an explicit value over the environment.
|
|
35
|
+
#
|
|
36
|
+
# @param value [Boolean, nil]
|
|
37
|
+
#
|
|
38
|
+
# @return [Boolean]
|
|
39
|
+
def resolve_enabled(value)
|
|
40
|
+
return value unless value.nil?
|
|
41
|
+
|
|
42
|
+
raw = ENV.fetch(ENV_VAR, "")
|
|
43
|
+
env = raw.strip.downcase
|
|
44
|
+
return true if TRUE_VALUES.include?(env)
|
|
45
|
+
unless FALSE_VALUES.include?(env)
|
|
46
|
+
warn("Turbopuffer: ignoring invalid #{ENV_VAR}=#{raw.inspect}, expected 1 or 0")
|
|
47
|
+
end
|
|
48
|
+
false
|
|
49
|
+
end
|
|
50
|
+
|
|
51
|
+
# @api private
|
|
52
|
+
#
|
|
53
|
+
# Returns the method and path of a request with identifiers like the namespace replaced.
|
|
54
|
+
#
|
|
55
|
+
# @param method [Symbol, String]
|
|
56
|
+
# @param url [URI::Generic, String]
|
|
57
|
+
#
|
|
58
|
+
# @return [String]
|
|
59
|
+
def route_template(method, url)
|
|
60
|
+
path = url.to_s.sub(SCHEME_AND_HOST_RE, "")
|
|
61
|
+
path = path.sub(NAMESPACE_RE, '\1{ns}').gsub(OPERATION_RE, '\1{token}')
|
|
62
|
+
"#{method.to_s.upcase} #{path}"
|
|
63
|
+
end
|
|
64
|
+
|
|
65
|
+
# @api private
|
|
66
|
+
#
|
|
67
|
+
# Returns the duration in nanoseconds of each client-side phase of an attempt ending at
|
|
68
|
+
# `end_at`. Phases that weren't observed are left out.
|
|
69
|
+
#
|
|
70
|
+
# @param timings [Turbopuffer::Internal::Transport::RequestObserver::Timings]
|
|
71
|
+
# @param end_at [Integer]
|
|
72
|
+
#
|
|
73
|
+
# @return [Hash{Symbol=>Integer}]
|
|
74
|
+
def compute_durations(timings, end_at)
|
|
75
|
+
durations = {}
|
|
76
|
+
return durations if timings.attempt_begin.nil?
|
|
77
|
+
durations[:total] = end_at - timings.attempt_begin
|
|
78
|
+
|
|
79
|
+
if timings.serialize_begin && timings.serialize_end
|
|
80
|
+
durations[:serialize] = timings.serialize_end - timings.serialize_begin
|
|
81
|
+
end
|
|
82
|
+
|
|
83
|
+
# Set by transports that compress request bodies.
|
|
84
|
+
compress_begin, compress_end = timings.extra.values_at(:compress_begin, :compress_end)
|
|
85
|
+
if compress_begin && compress_end
|
|
86
|
+
durations[:compress] = compress_end - compress_begin
|
|
87
|
+
end
|
|
88
|
+
|
|
89
|
+
# Waiting for a free connection, until connecting a new one or sending on a reused one.
|
|
90
|
+
pool_begin = compress_end || timings.request_ready
|
|
91
|
+
connection_ready = timings.connect_begin || timings.send_begin
|
|
92
|
+
if pool_begin && connection_ready
|
|
93
|
+
durations[:pool] = [connection_ready - pool_begin, 0].max
|
|
94
|
+
end
|
|
95
|
+
|
|
96
|
+
if timings.connect_begin && timings.connect_end
|
|
97
|
+
durations[:connect] = timings.connect_end - timings.connect_begin
|
|
98
|
+
end
|
|
99
|
+
|
|
100
|
+
if timings.send_begin && timings.send_end
|
|
101
|
+
durations[:send] = timings.send_end - timings.send_begin
|
|
102
|
+
end
|
|
103
|
+
|
|
104
|
+
# Covers the network round trip and the server.
|
|
105
|
+
if timings.send_end && timings.response_headers
|
|
106
|
+
durations[:wait] = [timings.response_headers - timings.send_end, 0].max
|
|
107
|
+
end
|
|
108
|
+
|
|
109
|
+
if timings.body_end && timings.response_headers
|
|
110
|
+
durations[:body_read] = timings.body_end - timings.response_headers
|
|
111
|
+
end
|
|
112
|
+
|
|
113
|
+
if timings.deserialize_begin && timings.deserialize_end
|
|
114
|
+
durations[:deserialize] = timings.deserialize_end - timings.deserialize_begin
|
|
115
|
+
end
|
|
116
|
+
|
|
117
|
+
durations
|
|
118
|
+
end
|
|
119
|
+
|
|
120
|
+
# @api private
|
|
121
|
+
#
|
|
122
|
+
# Indirection so tests can control sampling.
|
|
123
|
+
#
|
|
124
|
+
# @return [Float]
|
|
125
|
+
def random = Kernel.rand
|
|
126
|
+
|
|
127
|
+
# @api private
|
|
128
|
+
#
|
|
129
|
+
# Returns the buffer shared by clients with the same API key and base URL, or nil if
|
|
130
|
+
# telemetry is disabled. Sharing lets records ride on any client's requests, but never
|
|
131
|
+
# to another org or region.
|
|
132
|
+
#
|
|
133
|
+
# @param enabled [Boolean, nil]
|
|
134
|
+
# @param api_key [String]
|
|
135
|
+
# @param base_url [String]
|
|
136
|
+
#
|
|
137
|
+
# @return [Turbopuffer::Internal::Telemetry::Buffer, nil]
|
|
138
|
+
def buffer_for(enabled, api_key, base_url)
|
|
139
|
+
return nil unless resolve_enabled(enabled)
|
|
140
|
+
|
|
141
|
+
key = [api_key, base_url]
|
|
142
|
+
@lock.synchronize do
|
|
143
|
+
holder = @shared[key]
|
|
144
|
+
buffer = holder && @buffers[holder]
|
|
145
|
+
unless buffer
|
|
146
|
+
# Drops the keys of freed buffers.
|
|
147
|
+
@shared.delete_if { !@buffers.key?(_2) }
|
|
148
|
+
buffer = Buffer.new
|
|
149
|
+
holder = Object.new
|
|
150
|
+
@buffers[holder] = buffer
|
|
151
|
+
@shared[key] = holder
|
|
152
|
+
install_fork_hook
|
|
153
|
+
end
|
|
154
|
+
buffer
|
|
155
|
+
end
|
|
156
|
+
end
|
|
157
|
+
|
|
158
|
+
# @api private
|
|
159
|
+
def after_fork_in_child
|
|
160
|
+
@lock = Mutex.new
|
|
161
|
+
@buffers.each_value(&:reset_after_fork)
|
|
162
|
+
end
|
|
163
|
+
|
|
164
|
+
private
|
|
165
|
+
|
|
166
|
+
def install_fork_hook
|
|
167
|
+
return if @fork_hook_installed
|
|
168
|
+
Process.singleton_class.prepend(ForkHook)
|
|
169
|
+
@fork_hook_installed = true
|
|
170
|
+
end
|
|
171
|
+
end
|
|
172
|
+
|
|
173
|
+
# @api private
|
|
174
|
+
#
|
|
175
|
+
# Records taken from a buffer, encoded as a header value.
|
|
176
|
+
class Batch
|
|
177
|
+
# @return [Array<Array(Integer, Hash{Symbol=>Object})>]
|
|
178
|
+
attr_reader :records
|
|
179
|
+
|
|
180
|
+
# @return [Integer]
|
|
181
|
+
attr_reader :dropped
|
|
182
|
+
|
|
183
|
+
# @return [String]
|
|
184
|
+
attr_reader :header
|
|
185
|
+
|
|
186
|
+
# @api private
|
|
187
|
+
#
|
|
188
|
+
# @param records [Array<Array(Integer, Hash{Symbol=>Object})>]
|
|
189
|
+
# @param dropped [Integer]
|
|
190
|
+
def initialize(records, dropped)
|
|
191
|
+
@records = records
|
|
192
|
+
@dropped = dropped
|
|
193
|
+
|
|
194
|
+
now = Transport::RequestObserver.now
|
|
195
|
+
envelope = {
|
|
196
|
+
version: ENVELOPE_VERSION,
|
|
197
|
+
records: records.map do |recorded_at, rec|
|
|
198
|
+
{**rec, age_ms: ((now - recorded_at) / 1_000_000.0).round}
|
|
199
|
+
end
|
|
200
|
+
}
|
|
201
|
+
envelope[:dropped] = dropped if dropped.positive?
|
|
202
|
+
@header = JSON.generate(envelope)
|
|
203
|
+
end
|
|
204
|
+
end
|
|
205
|
+
|
|
206
|
+
# @api private
|
|
207
|
+
#
|
|
208
|
+
# Buffers per-request telemetry records until a later request can carry them.
|
|
209
|
+
class Buffer
|
|
210
|
+
# @return [Float]
|
|
211
|
+
attr_reader :sample_rate
|
|
212
|
+
|
|
213
|
+
# @api private
|
|
214
|
+
def initialize
|
|
215
|
+
@lock = Mutex.new
|
|
216
|
+
@records = []
|
|
217
|
+
@dropped = 0
|
|
218
|
+
# Used until the server advertises a rate.
|
|
219
|
+
@sample_rate = 1.0
|
|
220
|
+
end
|
|
221
|
+
|
|
222
|
+
# @api private
|
|
223
|
+
#
|
|
224
|
+
# Adopts the sample rate advertised by the server, ignoring invalid values.
|
|
225
|
+
#
|
|
226
|
+
# @param response [Net::HTTPResponse]
|
|
227
|
+
def observe_response(response)
|
|
228
|
+
value = response[SAMPLE_RATE_HEADER]
|
|
229
|
+
return if value.nil?
|
|
230
|
+
|
|
231
|
+
rate = Float(value, exception: false)
|
|
232
|
+
@sample_rate = rate if rate&.between?(0.0, 1.0)
|
|
233
|
+
end
|
|
234
|
+
|
|
235
|
+
# @api private
|
|
236
|
+
#
|
|
237
|
+
# Samples and buffers a record for one request.
|
|
238
|
+
#
|
|
239
|
+
# @param method [Symbol, String]
|
|
240
|
+
# @param url [URI::Generic, String]
|
|
241
|
+
# @param status [Integer]
|
|
242
|
+
# @param retries [Integer]
|
|
243
|
+
# @param durations [Hash{Symbol=>Integer}] in nanoseconds
|
|
244
|
+
# @param server_total_ms [Numeric, nil]
|
|
245
|
+
# @param error [String, nil]
|
|
246
|
+
# @param reused [Boolean, nil]
|
|
247
|
+
def record(
|
|
248
|
+
method:,
|
|
249
|
+
url:,
|
|
250
|
+
status:,
|
|
251
|
+
retries:,
|
|
252
|
+
durations:,
|
|
253
|
+
server_total_ms: nil,
|
|
254
|
+
error: nil,
|
|
255
|
+
reused: nil
|
|
256
|
+
)
|
|
257
|
+
rate = @sample_rate
|
|
258
|
+
return if rate <= 0.0 || (rate < 1.0 && Telemetry.random >= rate)
|
|
259
|
+
|
|
260
|
+
rec = {route: Telemetry.route_template(method, url), status: status}
|
|
261
|
+
rec[:error] = error unless error.nil?
|
|
262
|
+
rec[:retries] = retries unless retries.zero?
|
|
263
|
+
rec[:sample_rate] = rate if rate < 1.0
|
|
264
|
+
durations.each do |name, duration|
|
|
265
|
+
# A zero compress duration means the body wasn't compressed.
|
|
266
|
+
next if name == :compress && duration.zero?
|
|
267
|
+
rec[:"#{name}_us"] = duration / 1000
|
|
268
|
+
end
|
|
269
|
+
rec[:server_total_us] = (server_total_ms * 1000).round unless server_total_ms.nil?
|
|
270
|
+
rec[:reused] = reused unless reused.nil?
|
|
271
|
+
|
|
272
|
+
@lock.synchronize do
|
|
273
|
+
if @records.length >= MAX_BUFFERED_RECORDS
|
|
274
|
+
@records.shift
|
|
275
|
+
@dropped += 1
|
|
276
|
+
end
|
|
277
|
+
@records << [Transport::RequestObserver.now, rec]
|
|
278
|
+
end
|
|
279
|
+
end
|
|
280
|
+
|
|
281
|
+
# @api private
|
|
282
|
+
#
|
|
283
|
+
# Removes up to `MAX_RECORDS_PER_HEADER` of the oldest records.
|
|
284
|
+
#
|
|
285
|
+
# @return [Turbopuffer::Internal::Telemetry::Batch, nil]
|
|
286
|
+
def take
|
|
287
|
+
records, dropped = @lock.synchronize do
|
|
288
|
+
return nil if @records.empty?
|
|
289
|
+
taken = @records.shift(MAX_RECORDS_PER_HEADER)
|
|
290
|
+
dropped = @dropped
|
|
291
|
+
@dropped = 0
|
|
292
|
+
[taken, dropped]
|
|
293
|
+
end
|
|
294
|
+
Batch.new(records, dropped)
|
|
295
|
+
end
|
|
296
|
+
|
|
297
|
+
# @api private
|
|
298
|
+
#
|
|
299
|
+
# Returns a batch that never reached the server to the front of the buffer.
|
|
300
|
+
#
|
|
301
|
+
# @param batch [Turbopuffer::Internal::Telemetry::Batch]
|
|
302
|
+
def restore(batch)
|
|
303
|
+
@lock.synchronize do
|
|
304
|
+
room = [MAX_BUFFERED_RECORDS - @records.length, 0].max
|
|
305
|
+
# The batch holds the oldest records, so they're the ones to drop when full.
|
|
306
|
+
kept = batch.records.last(room)
|
|
307
|
+
@dropped += batch.dropped + batch.records.length - kept.length
|
|
308
|
+
@records.unshift(*kept)
|
|
309
|
+
end
|
|
310
|
+
end
|
|
311
|
+
|
|
312
|
+
# @api private
|
|
313
|
+
def reset_after_fork
|
|
314
|
+
# Another thread may have held the lock at fork time, and buffered records belong to the parent.
|
|
315
|
+
@lock = Mutex.new
|
|
316
|
+
@records = []
|
|
317
|
+
@dropped = 0
|
|
318
|
+
end
|
|
319
|
+
end
|
|
320
|
+
|
|
321
|
+
# @api private
|
|
322
|
+
#
|
|
323
|
+
# Installs the request observer that records telemetry for a client.
|
|
324
|
+
class Observer < Transport::RequestObserver
|
|
325
|
+
# @return [Turbopuffer::Internal::Telemetry::Buffer]
|
|
326
|
+
attr_reader :buffer
|
|
327
|
+
|
|
328
|
+
# @api private
|
|
329
|
+
#
|
|
330
|
+
# @param buffer [Turbopuffer::Internal::Telemetry::Buffer]
|
|
331
|
+
def initialize(buffer)
|
|
332
|
+
super()
|
|
333
|
+
@buffer = buffer
|
|
334
|
+
end
|
|
335
|
+
|
|
336
|
+
# @api private
|
|
337
|
+
#
|
|
338
|
+
# @param info [Turbopuffer::Internal::Transport::RequestObserver::RequestInfo]
|
|
339
|
+
#
|
|
340
|
+
# @return [Turbopuffer::Internal::Telemetry::Scope]
|
|
341
|
+
def start(info) = Scope.new(@buffer, info)
|
|
342
|
+
end
|
|
343
|
+
|
|
344
|
+
# @api private
|
|
345
|
+
class Scope < Transport::RequestObserver::RequestScope
|
|
346
|
+
# @api private
|
|
347
|
+
#
|
|
348
|
+
# @param buffer [Turbopuffer::Internal::Telemetry::Buffer]
|
|
349
|
+
# @param info [Turbopuffer::Internal::Transport::RequestObserver::RequestInfo]
|
|
350
|
+
def initialize(buffer, info)
|
|
351
|
+
super()
|
|
352
|
+
@buffer = buffer
|
|
353
|
+
@info = info
|
|
354
|
+
# Kept for later attempts until one of them may have reached the server.
|
|
355
|
+
@batch = nil
|
|
356
|
+
end
|
|
357
|
+
|
|
358
|
+
# @api private
|
|
359
|
+
#
|
|
360
|
+
# @param attempt [Integer]
|
|
361
|
+
# @param request [Hash{Symbol=>Object}]
|
|
362
|
+
def attempt_begin(attempt, request)
|
|
363
|
+
# Taken only once a request is about to be sent, so one that fails before then can't lose it.
|
|
364
|
+
@batch = @buffer.take if attempt.zero?
|
|
365
|
+
request.fetch(:headers)[HEADER] = @batch.header if @batch
|
|
366
|
+
end
|
|
367
|
+
|
|
368
|
+
# @api private
|
|
369
|
+
#
|
|
370
|
+
# @param result [Turbopuffer::Internal::Transport::RequestObserver::AttemptResult]
|
|
371
|
+
def attempt_end(result)
|
|
372
|
+
@batch = nil unless result.reached_server == false
|
|
373
|
+
@buffer.observe_response(result.response) if result.response
|
|
374
|
+
end
|
|
375
|
+
|
|
376
|
+
# @api private
|
|
377
|
+
#
|
|
378
|
+
# @param result [Turbopuffer::Internal::Transport::RequestObserver::RequestResult]
|
|
379
|
+
def finish(result)
|
|
380
|
+
timings = result.timings
|
|
381
|
+
durations = Telemetry.compute_durations(
|
|
382
|
+
timings,
|
|
383
|
+
timings.deserialize_end || Transport::RequestObserver.now
|
|
384
|
+
)
|
|
385
|
+
|
|
386
|
+
# A batch that never reached the server goes back for a later request.
|
|
387
|
+
if @batch
|
|
388
|
+
@buffer.restore(@batch)
|
|
389
|
+
@batch = nil
|
|
390
|
+
end
|
|
391
|
+
|
|
392
|
+
@buffer.record(
|
|
393
|
+
method: @info.method,
|
|
394
|
+
url: @info.url,
|
|
395
|
+
status: status(result),
|
|
396
|
+
retries: result.retries,
|
|
397
|
+
durations: durations,
|
|
398
|
+
server_total_ms: server_total_ms(result.parsed),
|
|
399
|
+
error: error_name(result.error_kind),
|
|
400
|
+
reused: timings.reused
|
|
401
|
+
)
|
|
402
|
+
end
|
|
403
|
+
|
|
404
|
+
private
|
|
405
|
+
|
|
406
|
+
# A failed respond-async operation has no response of its own, only the error's status.
|
|
407
|
+
def status(result)
|
|
408
|
+
error = result.error
|
|
409
|
+
return error.status if error.is_a?(Turbopuffer::Errors::APIStatusError) && error.status
|
|
410
|
+
result.response ? result.response.code.to_i : 0
|
|
411
|
+
end
|
|
412
|
+
|
|
413
|
+
def error_name(kind)
|
|
414
|
+
if kind.nil?
|
|
415
|
+
nil
|
|
416
|
+
elsif kind == :canceled || kind == :other
|
|
417
|
+
kind.to_s
|
|
418
|
+
elsif kind.end_with?("timeout")
|
|
419
|
+
"timeout"
|
|
420
|
+
else
|
|
421
|
+
"connect"
|
|
422
|
+
end
|
|
423
|
+
end
|
|
424
|
+
|
|
425
|
+
def server_total_ms(parsed)
|
|
426
|
+
value = field(field(parsed, :performance), :server_total_ms)
|
|
427
|
+
value if value.is_a?(Numeric) && value.finite?
|
|
428
|
+
end
|
|
429
|
+
|
|
430
|
+
def field(value, name)
|
|
431
|
+
case value
|
|
432
|
+
in Turbopuffer::Internal::Type::BaseModel | Hash
|
|
433
|
+
value[name]
|
|
434
|
+
else
|
|
435
|
+
nil
|
|
436
|
+
end
|
|
437
|
+
end
|
|
438
|
+
end
|
|
439
|
+
|
|
440
|
+
# @api private
|
|
441
|
+
#
|
|
442
|
+
# Resets telemetry in forked children.
|
|
443
|
+
module ForkHook
|
|
444
|
+
# @api private
|
|
445
|
+
#
|
|
446
|
+
# @return [Integer]
|
|
447
|
+
def _fork
|
|
448
|
+
pid = super
|
|
449
|
+
Telemetry.after_fork_in_child if pid.zero?
|
|
450
|
+
pid
|
|
451
|
+
end
|
|
452
|
+
end
|
|
453
|
+
|
|
454
|
+
@lock = Mutex.new
|
|
455
|
+
# Maps API key and base URL to a holder, since weak maps compare keys by identity.
|
|
456
|
+
@shared = {}
|
|
457
|
+
# Maps holders to buffers weakly, so a buffer is freed with the last client using it.
|
|
458
|
+
@buffers = ObjectSpace::WeakMap.new
|
|
459
|
+
@fork_hook_installed = false
|
|
460
|
+
end
|
|
461
|
+
end
|
|
462
|
+
end
|