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.
- checksums.yaml +4 -4
- data/CHANGELOG.md +19 -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 +538 -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/encryption.rb +11 -1
- data/lib/turbopuffer/models/full_text_search.rb +1 -0
- data/lib/turbopuffer/models/id.rb +1 -1
- data/lib/turbopuffer/models/namespace_explain_query_params.rb +50 -24
- 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 +51 -24
- data/lib/turbopuffer/models/namespace_multi_query_response.rb +19 -2
- data/lib/turbopuffer/models/namespace_query_params.rb +50 -24
- 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 +4 -4
- 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 +315 -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/encryption.rbi +29 -2
- data/rbi/turbopuffer/models/namespace_explain_query_params.rbi +84 -71
- 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_params.rbi +86 -71
- data/rbi/turbopuffer/models/namespace_multi_query_response.rbi +17 -1
- data/rbi/turbopuffer/models/namespace_query_params.rbi +88 -71
- 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 +15 -4
- data/sig/turbopuffer/client.rbs +1 -0
- data/sig/turbopuffer/internal/telemetry.rbs +142 -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
- data/sig/turbopuffer/models/encryption.rbs +22 -3
- data/sig/turbopuffer/models/namespace_explain_query_params.rbs +30 -28
- data/sig/turbopuffer/models/namespace_multi_query_params.rbs +30 -28
- data/sig/turbopuffer/models/namespace_query_params.rbs +30 -26
- data/sig/turbopuffer/resources/namespaces.rbs +3 -3
- metadata +9 -3
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: b2a36dd806fc7e21775b4a0edc355e2d22a0414bbf8e9069324514177f082031
|
|
4
|
+
data.tar.gz: '099d6f2b73a34fe9485a2b36501cc26b4c9a74f4369f69d61b193b423b82e9d2'
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
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.
|
|
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
|
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,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
|