turbopuffer 2.8.0 → 2.10.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.
Files changed (67) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +19 -0
  3. data/README.md +15 -1
  4. data/lib/turbopuffer/client.rb +7 -0
  5. data/lib/turbopuffer/internal/respond_async.rb +1 -1
  6. data/lib/turbopuffer/internal/telemetry.rb +538 -0
  7. data/lib/turbopuffer/internal/transport/base_client.rb +50 -21
  8. data/lib/turbopuffer/internal/transport/pooled_net_requester.rb +77 -2
  9. data/lib/turbopuffer/internal/transport/request_observer.rb +377 -0
  10. data/lib/turbopuffer/models/attribute_schema_config.rb +1 -0
  11. data/lib/turbopuffer/models/branch_from_namespace_params.rb +3 -0
  12. data/lib/turbopuffer/models/copy_from_namespace_operation.rb +8 -1
  13. data/lib/turbopuffer/models/copy_from_namespace_operation_result.rb +5 -3
  14. data/lib/turbopuffer/models/copy_from_namespace_params.rb +3 -0
  15. data/lib/turbopuffer/models/encryption.rb +11 -1
  16. data/lib/turbopuffer/models/full_text_search.rb +1 -0
  17. data/lib/turbopuffer/models/id.rb +1 -1
  18. data/lib/turbopuffer/models/namespace_explain_query_params.rb +50 -24
  19. data/lib/turbopuffer/models/namespace_hint_cache_warm_response.rb +2 -1
  20. data/lib/turbopuffer/models/namespace_metadata.rb +10 -1
  21. data/lib/turbopuffer/models/namespace_metadata_patch.rb +1 -0
  22. data/lib/turbopuffer/models/namespace_multi_query_params.rb +51 -24
  23. data/lib/turbopuffer/models/namespace_multi_query_response.rb +19 -2
  24. data/lib/turbopuffer/models/namespace_query_params.rb +50 -24
  25. data/lib/turbopuffer/models/namespace_query_response.rb +10 -2
  26. data/lib/turbopuffer/models/namespace_recall_response.rb +5 -0
  27. data/lib/turbopuffer/models/namespace_start_copy_from_response.rb +2 -0
  28. data/lib/turbopuffer/models/namespace_write_params.rb +3 -3
  29. data/lib/turbopuffer/models/operation_error.rb +2 -0
  30. data/lib/turbopuffer/models/write_result.rb +1 -1
  31. data/lib/turbopuffer/resources/namespaces.rb +4 -4
  32. data/lib/turbopuffer/version.rb +1 -1
  33. data/lib/turbopuffer.rb +2 -0
  34. data/rbi/turbopuffer/client.rbi +5 -0
  35. data/rbi/turbopuffer/internal/telemetry.rbi +315 -0
  36. data/rbi/turbopuffer/internal/transport/base_client.rbi +13 -2
  37. data/rbi/turbopuffer/internal/transport/pooled_net_requester.rbi +47 -1
  38. data/rbi/turbopuffer/internal/transport/request_observer.rbi +340 -0
  39. data/rbi/turbopuffer/models/branch_from_namespace_params.rbi +1 -0
  40. data/rbi/turbopuffer/models/copy_from_namespace_operation.rbi +4 -0
  41. data/rbi/turbopuffer/models/copy_from_namespace_operation_result.rbi +8 -3
  42. data/rbi/turbopuffer/models/copy_from_namespace_params.rbi +1 -0
  43. data/rbi/turbopuffer/models/encryption.rbi +29 -2
  44. data/rbi/turbopuffer/models/namespace_explain_query_params.rbi +84 -71
  45. data/rbi/turbopuffer/models/namespace_hint_cache_warm_response.rbi +2 -0
  46. data/rbi/turbopuffer/models/namespace_metadata.rbi +5 -0
  47. data/rbi/turbopuffer/models/namespace_multi_query_params.rbi +86 -71
  48. data/rbi/turbopuffer/models/namespace_multi_query_response.rbi +17 -1
  49. data/rbi/turbopuffer/models/namespace_query_params.rbi +88 -71
  50. data/rbi/turbopuffer/models/namespace_query_response.rbi +8 -1
  51. data/rbi/turbopuffer/models/namespace_recall_response.rbi +4 -0
  52. data/rbi/turbopuffer/models/namespace_start_copy_from_response.rbi +1 -0
  53. data/rbi/turbopuffer/models/namespace_write_params.rbi +3 -3
  54. data/rbi/turbopuffer/models/operation_error.rbi +1 -0
  55. data/rbi/turbopuffer/models/write_result.rbi +1 -1
  56. data/rbi/turbopuffer/resources/namespaces.rbi +15 -4
  57. data/sig/turbopuffer/client.rbs +1 -0
  58. data/sig/turbopuffer/internal/telemetry.rbs +142 -0
  59. data/sig/turbopuffer/internal/transport/base_client.rbs +5 -1
  60. data/sig/turbopuffer/internal/transport/pooled_net_requester.rbs +15 -1
  61. data/sig/turbopuffer/internal/transport/request_observer.rbs +153 -0
  62. data/sig/turbopuffer/models/encryption.rbs +22 -3
  63. data/sig/turbopuffer/models/namespace_explain_query_params.rbs +30 -28
  64. data/sig/turbopuffer/models/namespace_multi_query_params.rbs +30 -28
  65. data/sig/turbopuffer/models/namespace_query_params.rbs +30 -26
  66. data/sig/turbopuffer/resources/namespaces.rbs +3 -3
  67. metadata +9 -3
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: a9ea10142f4e8c684cf18f5657f30b47bfa9f6e3abdae0473e720ac63ac82e7a
4
- data.tar.gz: cb8e5b3806055824b02f4d135c6687c93a9b9f4cc22f239c1dc03c5e22782b04
3
+ metadata.gz: b2a36dd806fc7e21775b4a0edc355e2d22a0414bbf8e9069324514177f082031
4
+ data.tar.gz: '099d6f2b73a34fe9485a2b36501cc26b4c9a74f4369f69d61b193b423b82e9d2'
5
5
  SHA512:
6
- metadata.gz: 04f840dc0dd750b28b63a46e1b363abb277508d3a25dbc216d5095fd89a408b2093b944a7421f044bab242b2457298ccfe5471c9ea42df2975a5b7b310ad9856
7
- data.tar.gz: b8b809ed55838462235995bb2ab0f7e20aafdf96273e3dfff1e71086bc777bbe0d5d5583c1e6e858b97bc3f064b4d1682c60cc48cbe28232436c5d8598659c0b
6
+ metadata.gz: 3a2e126a3c4ae82652aebeaa7a58ecf06207780366faa8e913a598bcc49d8c6c8be90d47bfdb9059206ba03be5b8ed2425cca5004673b0914201d8e87ce9c317
7
+ data.tar.gz: 584446333353eced6da9ebc066231a892d6ef5a40b58d5e5c4bb260b3b4da73a6e57fe33610af6d34bcee40365024f645df5fb1a6d5caaf9f33777b6bd006742
data/CHANGELOG.md CHANGED
@@ -1,5 +1,24 @@
1
1
  # Changelog
2
2
 
3
+ ## [2.10.0](https://github.com/turbopuffer/turbopuffer-ruby/compare/v2.9.0...v2.10.0) (2026-10-29)
4
+
5
+
6
+ ### Features
7
+
8
+ * openapi: add encryption_context to customer-managed encryption ([1df756b](https://github.com/turbopuffer/turbopuffer-ruby/commit/1df756b4a97d526ced288201f8d7a5193bfd5c8b))
9
+ * Send client-generated request IDs ([#77](https://github.com/turbopuffer/turbopuffer-ruby/issues/77)) ([3812a2f](https://github.com/turbopuffer/turbopuffer-ruby/commit/3812a2fc924254f1c5c8b67a6f8dd6892b02e7aa))
10
+ * spec: split query consistency into strong and eventual variants ([2e12e6c](https://github.com/turbopuffer/turbopuffer-ruby/commit/2e12e6c36b4bb9ba8dcba9ecddfb243d4bda1dd7))
11
+ * tpuf-engine: add max_staleness_seconds to eventual consistency ([e77b67d](https://github.com/turbopuffer/turbopuffer-ruby/commit/e77b67dc350327860e1f2f75702b162d06cb222e))
12
+
13
+ ## [2.9.0](https://github.com/turbopuffer/turbopuffer-ruby/compare/v2.8.0...v2.9.0) (2026-10-20)
14
+
15
+
16
+ ### Features
17
+
18
+ * Bound document IDs to 0 so they become `u64` in Rust ([b5b3f8d](https://github.com/turbopuffer/turbopuffer-ruby/commit/b5b3f8d237cd8a488634cbc83a2bc67e0318e7da))
19
+ * Listen via request observer and send client telemetry ([ac17f80](https://github.com/turbopuffer/turbopuffer-ruby/commit/ac17f80196e631bd114270ba75b2b34a244f8e5f))
20
+ * OpenAPI: Add missing descriptions to prettify docblocks in output SDKs ([712aef9](https://github.com/turbopuffer/turbopuffer-ruby/commit/712aef9d7f7b21807a7aef09509a158a6317611c))
21
+
3
22
  ## [2.8.0](https://github.com/turbopuffer/turbopuffer-ruby/compare/v2.7.0...v2.8.0) (2026-10-13)
4
23
 
5
24
 
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.8.0"
20
+ gem "turbopuffer", "~> 2.10.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
@@ -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,538 @@
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
+ # Each recorded request is sent with an `X-Request-Id` that its record repeats, so the
13
+ # server can show the client's timings in the same trace as its own.
14
+ #
15
+ # @api private
16
+ module Telemetry
17
+ ENV_VAR = "TURBOPUFFER_TELEMETRY"
18
+ HEADER = "x-turbopuffer-client-telemetry"
19
+ SAMPLE_RATE_HEADER = "x-turbopuffer-client-telemetry-sample-rate"
20
+ # Sorted by ASCII value, so that encoded IDs sort like their bytes.
21
+ REQUEST_ID_ALPHABET = "234567abcdefghijklmnopqrstuvwxyz"
22
+ # The bytes in a request ID before it's encoded. The first `REQUEST_ID_RANDOM_BYTES` are
23
+ # random, and the rest hold the time it was generated.
24
+ REQUEST_ID_BYTES = 18
25
+ # The request header that carries the IDs of recorded requests.
26
+ REQUEST_ID_HEADER = "x-request-id"
27
+ # The prefix of generated request IDs.
28
+ REQUEST_ID_PREFIX = "tpreq_"
29
+ # The random bytes at the start of a request ID.
30
+ REQUEST_ID_RANDOM_BYTES = 12
31
+
32
+ ENVELOPE_VERSION = 1
33
+
34
+ # Keeps the header well under the 8 KB per-line limit of common proxies.
35
+ MAX_RECORDS_PER_HEADER = 16
36
+ MAX_BUFFERED_RECORDS = 1000
37
+
38
+ TRUE_VALUES = %w[1 true yes on].freeze
39
+ FALSE_VALUES = ["", "0", "false", "no", "off"].freeze
40
+
41
+ NAMESPACE_RE = %r{\A(/v\d+/namespaces/)[^/?]+}
42
+ OPERATION_RE = %r{(/operations/)[^/?]+}
43
+ SCHEME_AND_HOST_RE = %r{\A[a-z][a-z\d+\-.]*://[^/?#]*}i
44
+
45
+ class << self
46
+ # @api private
47
+ #
48
+ # Resolves whether telemetry is enabled, preferring an explicit value over the environment.
49
+ #
50
+ # @param value [Boolean, nil]
51
+ #
52
+ # @return [Boolean]
53
+ def resolve_enabled(value)
54
+ return value unless value.nil?
55
+
56
+ raw = ENV.fetch(ENV_VAR, "")
57
+ env = raw.strip.downcase
58
+ return true if TRUE_VALUES.include?(env)
59
+ unless FALSE_VALUES.include?(env)
60
+ warn("Turbopuffer: ignoring invalid #{ENV_VAR}=#{raw.inspect}, expected 1 or 0")
61
+ end
62
+ false
63
+ end
64
+
65
+ # @api private
66
+ #
67
+ # Returns the method and path of a request with identifiers like the namespace replaced.
68
+ #
69
+ # @param method [Symbol, String]
70
+ # @param url [URI::Generic, String]
71
+ #
72
+ # @return [String]
73
+ def route_template(method, url)
74
+ path = url.to_s.sub(SCHEME_AND_HOST_RE, "")
75
+ path = path.sub(NAMESPACE_RE, '\1{ns}').gsub(OPERATION_RE, '\1{token}')
76
+ "#{method.to_s.upcase} #{path}"
77
+ end
78
+
79
+ # @api private
80
+ #
81
+ # Returns the duration in nanoseconds of each client-side phase of an attempt ending at
82
+ # `end_at`. Phases that weren't observed are left out.
83
+ #
84
+ # @param timings [Turbopuffer::Internal::Transport::RequestObserver::Timings]
85
+ # @param end_at [Integer]
86
+ #
87
+ # @return [Hash{Symbol=>Integer}]
88
+ def compute_durations(timings, end_at)
89
+ durations = {}
90
+ return durations if timings.attempt_begin.nil?
91
+ durations[:total] = end_at - timings.attempt_begin
92
+
93
+ if timings.serialize_begin && timings.serialize_end
94
+ durations[:serialize] = timings.serialize_end - timings.serialize_begin
95
+ end
96
+
97
+ # Set by transports that compress request bodies.
98
+ compress_begin, compress_end = timings.extra.values_at(:compress_begin, :compress_end)
99
+ if compress_begin && compress_end
100
+ durations[:compress] = compress_end - compress_begin
101
+ end
102
+
103
+ # Waiting for a free connection, until connecting a new one or sending on a reused one.
104
+ pool_begin = compress_end || timings.request_ready
105
+ connection_ready = timings.connect_begin || timings.send_begin
106
+ if pool_begin && connection_ready
107
+ durations[:pool] = [connection_ready - pool_begin, 0].max
108
+ end
109
+
110
+ if timings.connect_begin && timings.connect_end
111
+ durations[:connect] = timings.connect_end - timings.connect_begin
112
+ end
113
+
114
+ if timings.send_begin && timings.send_end
115
+ durations[:send] = timings.send_end - timings.send_begin
116
+ end
117
+
118
+ # Covers the network round trip and the server.
119
+ if timings.send_end && timings.response_headers
120
+ durations[:wait] = [timings.response_headers - timings.send_end, 0].max
121
+ end
122
+
123
+ if timings.body_end && timings.response_headers
124
+ durations[:body_read] = timings.body_end - timings.response_headers
125
+ end
126
+
127
+ if timings.deserialize_begin && timings.deserialize_end
128
+ durations[:deserialize] = timings.deserialize_end - timings.deserialize_begin
129
+ end
130
+
131
+ durations
132
+ end
133
+
134
+ # @api private
135
+ #
136
+ # Indirection so tests can control sampling.
137
+ #
138
+ # @return [Float]
139
+ def random = Kernel.rand
140
+
141
+ # @api private
142
+ #
143
+ # Encodes `bytes` in base32 with `REQUEST_ID_ALPHABET`, in RFC 4648's bit order without
144
+ # padding.
145
+ #
146
+ # @param bytes [String]
147
+ #
148
+ # @return [String]
149
+ def encode_base32(bytes)
150
+ bytes.unpack1("B*").scan(/.{1,5}/).map { REQUEST_ID_ALPHABET[_1.ljust(5, "0").to_i(2)] }.join
151
+ end
152
+
153
+ # @api private
154
+ #
155
+ # Generates the ID of a request that will be recorded. Its format is private to turbopuffer,
156
+ # which only links IDs in the format it expects: 12 random bytes, then the 48-bit
157
+ # millisecond time they were generated XORed with the first 6 random bytes, in base32
158
+ # after a prefix.
159
+ #
160
+ # @param now [Time]
161
+ # @param random [String] overridden by tests
162
+ #
163
+ # @return [String]
164
+ def new_request_id(now, random: SecureRandom.random_bytes(REQUEST_ID_RANDOM_BYTES))
165
+ millis = (now.to_r * 1000).floor
166
+ # The low bytes of the big-endian time.
167
+ time = [millis].pack("Q>").bytes.last(REQUEST_ID_BYTES - REQUEST_ID_RANDOM_BYTES)
168
+ masked = time.zip(random.bytes).map { _1 ^ _2 }.pack("C*")
169
+ REQUEST_ID_PREFIX + encode_base32(random + masked)
170
+ end
171
+
172
+ # @api private
173
+ #
174
+ # Returns the buffer shared by clients with the same API key and base URL, or nil if
175
+ # telemetry is disabled. Sharing lets records ride on any client's requests, but never
176
+ # to another org or region.
177
+ #
178
+ # @param enabled [Boolean, nil]
179
+ # @param api_key [String]
180
+ # @param base_url [String]
181
+ #
182
+ # @return [Turbopuffer::Internal::Telemetry::Buffer, nil]
183
+ def buffer_for(enabled, api_key, base_url)
184
+ return nil unless resolve_enabled(enabled)
185
+
186
+ key = [api_key, base_url]
187
+ @lock.synchronize do
188
+ holder = @shared[key]
189
+ buffer = holder && @buffers[holder]
190
+ unless buffer
191
+ # Drops the keys of freed buffers.
192
+ @shared.delete_if { !@buffers.key?(_2) }
193
+ buffer = Buffer.new
194
+ holder = Object.new
195
+ @buffers[holder] = buffer
196
+ @shared[key] = holder
197
+ install_fork_hook
198
+ end
199
+ buffer
200
+ end
201
+ end
202
+
203
+ # @api private
204
+ def after_fork_in_child
205
+ @lock = Mutex.new
206
+ @buffers.each_value(&:reset_after_fork)
207
+ end
208
+
209
+ private
210
+
211
+ def install_fork_hook
212
+ return if @fork_hook_installed
213
+ Process.singleton_class.prepend(ForkHook)
214
+ @fork_hook_installed = true
215
+ end
216
+ end
217
+
218
+ # @api private
219
+ #
220
+ # Records taken from a buffer, encoded as a header value.
221
+ class Batch
222
+ # @return [Array<Array(Integer, Hash{Symbol=>Object})>]
223
+ attr_reader :records
224
+
225
+ # @return [Integer]
226
+ attr_reader :dropped
227
+
228
+ # @return [String]
229
+ attr_reader :header
230
+
231
+ # @api private
232
+ #
233
+ # @param records [Array<Array(Integer, Hash{Symbol=>Object})>]
234
+ # @param dropped [Integer]
235
+ def initialize(records, dropped)
236
+ @records = records
237
+ @dropped = dropped
238
+
239
+ now = Transport::RequestObserver.now
240
+ envelope = {
241
+ version: ENVELOPE_VERSION,
242
+ records: records.map do |recorded_at, rec|
243
+ {**rec, age_ms: ((now - recorded_at) / 1_000_000.0).round}
244
+ end
245
+ }
246
+ envelope[:dropped] = dropped if dropped.positive?
247
+ @header = JSON.generate(envelope)
248
+ end
249
+ end
250
+
251
+ # @api private
252
+ #
253
+ # Buffers per-request telemetry records until a later request can carry them.
254
+ class Buffer
255
+ # @return [Float]
256
+ attr_reader :sample_rate
257
+
258
+ # @api private
259
+ def initialize
260
+ @lock = Mutex.new
261
+ @records = []
262
+ @dropped = 0
263
+ # Used until the server advertises a rate.
264
+ @sample_rate = 1.0
265
+ end
266
+
267
+ # @api private
268
+ #
269
+ # Adopts the sample rate advertised by the server, ignoring invalid values.
270
+ #
271
+ # @param response [Net::HTTPResponse]
272
+ def observe_response(response)
273
+ value = response[SAMPLE_RATE_HEADER]
274
+ return if value.nil?
275
+
276
+ rate = Float(value, exception: false)
277
+ @sample_rate = rate if rate&.between?(0.0, 1.0)
278
+ end
279
+
280
+ # @api private
281
+ #
282
+ # Decides whether to record a request that's starting, returning the sample rate it was
283
+ # recorded at.
284
+ #
285
+ # @return [Float, nil]
286
+ def sample
287
+ rate = @sample_rate
288
+ return nil if rate <= 0.0 || (rate < 1.0 && Telemetry.random >= rate)
289
+ rate
290
+ end
291
+
292
+ # @api private
293
+ #
294
+ # Buffers the record of a request sampled at `sample_rate`.
295
+ #
296
+ # @param method [Symbol, String]
297
+ # @param url [URI::Generic, String]
298
+ # @param status [Integer]
299
+ # @param retries [Integer]
300
+ # @param durations [Hash{Symbol=>Integer}] in nanoseconds
301
+ # @param sample_rate [Float]
302
+ # @param server_total_ms [Numeric, nil]
303
+ # @param error [String, nil]
304
+ # @param reused [Boolean, nil]
305
+ # @param request_id [String, nil] the `X-Request-Id` the request was sent with, when the
306
+ # client generated it
307
+ def record(
308
+ method:,
309
+ url:,
310
+ status:,
311
+ retries:,
312
+ durations:,
313
+ sample_rate:,
314
+ server_total_ms: nil,
315
+ error: nil,
316
+ reused: nil,
317
+ request_id: nil
318
+ )
319
+ rec = {route: Telemetry.route_template(method, url), status: status}
320
+ rec[:error] = error unless error.nil?
321
+ rec[:retries] = retries unless retries.zero?
322
+ rec[:request_id] = request_id unless request_id.nil?
323
+ rec[:sample_rate] = sample_rate if sample_rate < 1.0
324
+ durations.each do |name, duration|
325
+ # A zero compress duration means the body wasn't compressed.
326
+ next if name == :compress && duration.zero?
327
+ rec[:"#{name}_us"] = duration / 1000
328
+ end
329
+ rec[:server_total_us] = (server_total_ms * 1000).round unless server_total_ms.nil?
330
+ rec[:reused] = reused unless reused.nil?
331
+
332
+ @lock.synchronize do
333
+ if @records.length >= MAX_BUFFERED_RECORDS
334
+ @records.shift
335
+ @dropped += 1
336
+ end
337
+ @records << [Transport::RequestObserver.now, rec]
338
+ end
339
+ end
340
+
341
+ # @api private
342
+ #
343
+ # Removes up to `MAX_RECORDS_PER_HEADER` of the oldest records.
344
+ #
345
+ # @return [Turbopuffer::Internal::Telemetry::Batch, nil]
346
+ def take
347
+ records, dropped = @lock.synchronize do
348
+ return nil if @records.empty?
349
+ taken = @records.shift(MAX_RECORDS_PER_HEADER)
350
+ dropped = @dropped
351
+ @dropped = 0
352
+ [taken, dropped]
353
+ end
354
+ Batch.new(records, dropped)
355
+ end
356
+
357
+ # @api private
358
+ #
359
+ # Returns a batch that never reached the server to the front of the buffer.
360
+ #
361
+ # @param batch [Turbopuffer::Internal::Telemetry::Batch]
362
+ def restore(batch)
363
+ @lock.synchronize do
364
+ room = [MAX_BUFFERED_RECORDS - @records.length, 0].max
365
+ # The batch holds the oldest records, so they're the ones to drop when full.
366
+ kept = batch.records.last(room)
367
+ @dropped += batch.dropped + batch.records.length - kept.length
368
+ @records.unshift(*kept)
369
+ end
370
+ end
371
+
372
+ # @api private
373
+ def reset_after_fork
374
+ # Another thread may have held the lock at fork time, and buffered records belong to the parent.
375
+ @lock = Mutex.new
376
+ @records = []
377
+ @dropped = 0
378
+ end
379
+ end
380
+
381
+ # @api private
382
+ #
383
+ # Installs the request observer that records telemetry for a client.
384
+ class Observer < Transport::RequestObserver
385
+ # @return [Turbopuffer::Internal::Telemetry::Buffer]
386
+ attr_reader :buffer
387
+
388
+ # @api private
389
+ #
390
+ # @param buffer [Turbopuffer::Internal::Telemetry::Buffer]
391
+ def initialize(buffer)
392
+ super()
393
+ @buffer = buffer
394
+ end
395
+
396
+ # @api private
397
+ #
398
+ # @param info [Turbopuffer::Internal::Transport::RequestObserver::RequestInfo]
399
+ #
400
+ # @return [Turbopuffer::Internal::Telemetry::Scope]
401
+ def start(info) = Scope.new(@buffer, info)
402
+ end
403
+
404
+ # @api private
405
+ class Scope < Transport::RequestObserver::RequestScope
406
+ # @api private
407
+ #
408
+ # @param buffer [Turbopuffer::Internal::Telemetry::Buffer]
409
+ # @param info [Turbopuffer::Internal::Transport::RequestObserver::RequestInfo]
410
+ def initialize(buffer, info)
411
+ super()
412
+ @buffer = buffer
413
+ @info = info
414
+ # Kept for later attempts until one of them may have reached the server.
415
+ @batch = nil
416
+ # The rate the request was recorded at, or nil if it isn't recorded. Sampled up front, so
417
+ # that only requests whose records the server will get are sent with request IDs.
418
+ @sample_rate = buffer.sample
419
+ # Sent with every attempt, so retries share the request's trace.
420
+ @request_id = @sample_rate && Telemetry.new_request_id(Time.now)
421
+ end
422
+
423
+ # @api private
424
+ #
425
+ # @param attempt [Integer]
426
+ # @param request [Hash{Symbol=>Object}]
427
+ def attempt_begin(attempt, request)
428
+ headers = request.fetch(:headers)
429
+ # Taken only once a request is about to be sent, so one that fails before then can't lose it.
430
+ if attempt.zero?
431
+ @batch = @buffer.take
432
+ # An ID set by the caller is theirs to use, so the request keeps it and isn't linked.
433
+ @request_id = nil if headers.key?(REQUEST_ID_HEADER)
434
+ end
435
+ headers[HEADER] = @batch.header if @batch
436
+ headers[REQUEST_ID_HEADER] = @request_id if @request_id
437
+ end
438
+
439
+ # @api private
440
+ #
441
+ # @param result [Turbopuffer::Internal::Transport::RequestObserver::AttemptResult]
442
+ def attempt_end(result)
443
+ @batch = nil unless result.reached_server == false
444
+ @buffer.observe_response(result.response) if result.response
445
+ end
446
+
447
+ # @api private
448
+ #
449
+ # @param result [Turbopuffer::Internal::Transport::RequestObserver::RequestResult]
450
+ def finish(result)
451
+ timings = result.timings
452
+ durations = Telemetry.compute_durations(
453
+ timings,
454
+ timings.deserialize_end || Transport::RequestObserver.now
455
+ )
456
+
457
+ # A batch that never reached the server goes back for a later request.
458
+ if @batch
459
+ @buffer.restore(@batch)
460
+ @batch = nil
461
+ end
462
+ return if @sample_rate.nil?
463
+ # A rate of zero asks clients to stop recording, even requests that were already sampled.
464
+ return if @buffer.sample_rate <= 0.0
465
+
466
+ @buffer.record(
467
+ method: @info.method,
468
+ url: @info.url,
469
+ status: status(result),
470
+ retries: result.retries,
471
+ durations: durations,
472
+ sample_rate: @sample_rate,
473
+ server_total_ms: server_total_ms(result.parsed),
474
+ error: error_name(result.error_kind),
475
+ reused: timings.reused,
476
+ request_id: @request_id
477
+ )
478
+ end
479
+
480
+ private
481
+
482
+ # A failed respond-async operation has no response of its own, only the error's status.
483
+ def status(result)
484
+ error = result.error
485
+ return error.status if error.is_a?(Turbopuffer::Errors::APIStatusError) && error.status
486
+ result.response ? result.response.code.to_i : 0
487
+ end
488
+
489
+ def error_name(kind)
490
+ if kind.nil?
491
+ nil
492
+ elsif kind == :canceled || kind == :other
493
+ kind.to_s
494
+ elsif kind.end_with?("timeout")
495
+ "timeout"
496
+ else
497
+ "connect"
498
+ end
499
+ end
500
+
501
+ def server_total_ms(parsed)
502
+ value = field(field(parsed, :performance), :server_total_ms)
503
+ value if value.is_a?(Numeric) && value.finite?
504
+ end
505
+
506
+ def field(value, name)
507
+ case value
508
+ in Turbopuffer::Internal::Type::BaseModel | Hash
509
+ value[name]
510
+ else
511
+ nil
512
+ end
513
+ end
514
+ end
515
+
516
+ # @api private
517
+ #
518
+ # Resets telemetry in forked children.
519
+ module ForkHook
520
+ # @api private
521
+ #
522
+ # @return [Integer]
523
+ def _fork
524
+ pid = super
525
+ Telemetry.after_fork_in_child if pid.zero?
526
+ pid
527
+ end
528
+ end
529
+
530
+ @lock = Mutex.new
531
+ # Maps API key and base URL to a holder, since weak maps compare keys by identity.
532
+ @shared = {}
533
+ # Maps holders to buffers weakly, so a buffer is freed with the last client using it.
534
+ @buffers = ObjectSpace::WeakMap.new
535
+ @fork_hook_installed = false
536
+ end
537
+ end
538
+ end