crystil 0.6.0 → 0.7.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 (41) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +110 -72
  3. data/README.md +6 -9
  4. data/lib/crystil/callables.rb +24 -0
  5. data/lib/crystil/client.rb +7 -0
  6. data/lib/crystil/collector.rb +127 -4
  7. data/lib/crystil/sentinel.rb +2 -19
  8. data/lib/crystil/version.rb +1 -1
  9. data/lib/crystil/wrappers/anthropic.rb +37 -36
  10. data/lib/crystil/wrappers/base.rb +25 -28
  11. data/lib/crystil/wrappers/blocked_call.rb +52 -0
  12. data/lib/crystil/wrappers/constants.rb +3 -0
  13. data/lib/crystil/wrappers/deep_copy.rb +52 -0
  14. data/lib/crystil/wrappers/event_stream.rb +21 -26
  15. data/lib/crystil/wrappers/geminiai.rb +57 -36
  16. data/lib/crystil/wrappers/google.rb +18 -18
  17. data/lib/crystil/wrappers/groq.rb +89 -101
  18. data/lib/crystil/wrappers/openai.rb +118 -101
  19. data/lib/crystil/wrappers/ruby_llm.rb +150 -101
  20. data/lib/crystil/wrappers/ruby_llm_query.rb +176 -0
  21. data/lib/crystil/wrappers/ruby_llm_record.rb +105 -0
  22. data/lib/crystil/wrappers/ruby_llm_response.rb +148 -0
  23. data/lib/crystil/wrappers/stopped_call.rb +88 -0
  24. data/lib/crystil.rb +2 -1
  25. data/sig/crystil/callables.rbs +6 -0
  26. data/sig/crystil/client.rbs +2 -0
  27. data/sig/crystil/collector.rbs +33 -1
  28. data/sig/crystil/sentinel.rbs +0 -1
  29. data/sig/crystil/wrappers/base.rbs +7 -5
  30. data/sig/crystil/wrappers/blocked_call.rbs +15 -0
  31. data/sig/crystil/wrappers/constants.rbs +1 -0
  32. data/sig/crystil/wrappers/deep_copy.rbs +12 -0
  33. data/sig/crystil/wrappers/event_stream.rbs +2 -2
  34. data/sig/crystil/wrappers/geminiai.rbs +2 -0
  35. data/sig/crystil/wrappers/openai.rbs +12 -0
  36. data/sig/crystil/wrappers/ruby_llm.rbs +11 -4
  37. data/sig/crystil/wrappers/ruby_llm_query.rbs +35 -0
  38. data/sig/crystil/wrappers/ruby_llm_record.rbs +21 -0
  39. data/sig/crystil/wrappers/ruby_llm_response.rbs +39 -0
  40. data/sig/crystil/wrappers/stopped_call.rbs +26 -0
  41. metadata +16 -2
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 90d050805fee5db26efd12b183842cb70ff4a971bac3d8cc9a8e9a5717f0174e
4
- data.tar.gz: a205e8dd09052a6f686efc427b609b8b6ceebde6c147fd54708d66350f374954
3
+ metadata.gz: e2b7fc9fb8c5b4b506585c88051526f45e438c8630c6c3228db6cbc72d5f4bfe
4
+ data.tar.gz: 32af691f9f4c98f8a44ffce78242f61aab52fcdab49ab7908a0a5eb3c8718e27
5
5
  SHA512:
6
- metadata.gz: 4ed5f37da282a51c97d8262452927ece7cdaaecf02139eeec6c1c8b84d854b435483d776e8d8c49436e3f4ced7e1ca5700b1d42ca1675e24848894531e73c17d
7
- data.tar.gz: 58b439278a99afe07d4c89b63824a0b08a08e6d52b5a2555b8629b6c52afc32251b8251b8e9c3885f0738778d4473c975fa9ace9ec1451d38cdc86a3de42f63c
6
+ metadata.gz: 2ddc5bb4b3af91ec047d8d642f7c74e93b6c6a054c622c68bb69fd6a7066c42debb6158cefacdc5c3e7e7fae1ba8c6ea2aa3835748d2e13db5b04829116f0ee0
7
+ data.tar.gz: 5c48cd2e8af99e47bc7d23c834d0eac6b8b7b3851ba92d4731b5387b6ffd26ca78cdeb597241d20f31e5a573c168a39d94545781bdc7a44d0825a29a7f571aeb
data/CHANGELOG.md CHANGED
@@ -5,108 +5,146 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
- ## [0.0.1] - 2025-10-13
8
+ ## [0.7.0] - 2026-11-18
9
9
 
10
10
  ### Added
11
- - Initial release of Crystil Ruby SDK
12
- - Support for OpenAI client tracking
13
- - Support for Anthropic client tracking
14
- - Support for Google GenAI client tracking
15
- - Attribution tracking (parent/subsidiary hierarchy)
16
- - Transaction management
17
- - Asynchronous analytics collection
18
- - Workflow API client
19
- - Invocation API client
20
- - Streaming response support
21
- - Thread-safe configuration
22
- - Comprehensive error handling
11
+ - Calls Sentinel blocks now appear in Crystil, marked blocked with Sentinel's reason. Before, a
12
+ blocked call left no trace. Your app still gets `CrystilRequestInterceptedError`, and the
13
+ provider is still never called.
14
+ - Calls your app ends early now appear in Crystil as `stopped`, with the content and tokens that
15
+ arrived before the stop: a stream you stop reading (`break`, `throw`, or an error raised in your
16
+ stream callback or block), an Anthropic stream you close before its end, or a signal such as
17
+ Ctrl-C or a job worker shutting down. Before, these calls were missing, or shown as succeeded
18
+ or failed.
19
+ - Scripts, rake tasks and jobs no longer lose their last calls. A process now waits up to
20
+ 5 seconds as it exits for its analytics to send, so you can remove an
21
+ `at_exit { crystil.shutdown }`. `exit!` skips the wait.
22
+ - `Client#flush(timeout = 5)`, for serverless handlers, which are frozen as soon as they return.
23
+ Call it before returning: it waits up to `timeout` seconds for the analytics queued so far,
24
+ returns whether they were sent, and leaves the client working.
25
+ - RubyLLM:
26
+ - Calls made with `say`, or with `add_message` then `complete`, are now checked by Sentinel
27
+ and shown in Crystil, as `ask` calls are.
28
+ - A tool loop now shows every provider call it made, each with its own tokens and cost.
29
+ Before, only the last call was shown, so the earlier calls' cost was missing.
30
+ - Streamed replies now show their content, tokens and cost. Before, they showed none.
31
+ - Calls through RubyLLM's Vertex AI provider (`vertexai`) now appear in Crystil with their
32
+ cost.
33
+ - Register a `RubyLLM::Agent` with `crystil.ruby_llm.register(agent)`.
34
+ - Register a Rails `acts_as_chat` record, and Sentinel checks each prompt before it is saved,
35
+ so a blocked prompt never becomes a row or reaches a page that streams the chat. See
36
+ `EXAMPLES.md`.
37
+ - A blocked message is taken out of the chat's history, so it is not sent with your next
38
+ message.
23
39
 
24
- ## [0.0.2] - 2025-10-25
40
+ ### Changed
41
+ - Crystil supports `ruby_llm` 1.16 and later. If you use an earlier version, upgrade `ruby_llm`
42
+ along with this release.
25
43
 
26
44
  ### Fixed
27
- - Corrected Crystil request payload structure as needed
45
+ - OpenAI Chat and Groq streaming: your callback gets each chunk exactly as the gem sends it.
46
+ Before, Crystil added `nil` keys to each chunk's delta, and the first chunk's `choices` grew
47
+ with every later chunk.
48
+ - OpenAI Chat no longer changes your `parameters` hash, so you can reuse one hash for streamed
49
+ calls, or freeze it. A stream callback can be any object that responds to `call`, as
50
+ ruby-openai allows, and gets only as many arguments as it accepts.
51
+ - OpenAI Responses: a stream that ends in `response.incomplete` (a `max_output_tokens` cap or the
52
+ content filter) or `response.failed` no longer raises `Crystil::StreamError` in your app. It
53
+ returns as ruby-openai does, and Crystil shows its tokens.
54
+ - RubyLLM: an `ask` with only attachments, and a tool that calls `halt`, no longer raise. With
55
+ ActiveSupport loaded, a `with_schema` reply holding `Infinity` no longer makes every later call
56
+ on that chat fail.
57
+
58
+ ## [0.6.0] - 2026-09-24
59
+
60
+ ### Security
61
+ - Anthropic: credentials you pass in `request_options`, such as a gateway key in `extra_headers`,
62
+ are no longer sent to Crystil. Every earlier release sent them with each `messages.create`
63
+ call's analytics and Sentinel check. If you pass a credential this way, rotate it. The options
64
+ still apply to your call as before.
28
65
 
29
- ## [0.0.3] - 2025-10-27
66
+ ### Added
67
+ - Anthropic streaming calls (`messages.stream` and `messages.stream_raw`) now appear in Crystil
68
+ with their content, tokens and cost, and Sentinel checks them. Before, they were not tracked.
69
+ A stream you stop reading early, close, or that fails partway shows what it used up to then.
70
+ A stream you neither read to the end nor `close` is not tracked, so close one you stop using.
30
71
 
31
72
  ### Fixed
32
- - Correct Crystil request payload structure for Google GenAI
73
+ - `gemini-ai`: failed calls now appear in Crystil. Before, Crystil could not tell which model a
74
+ failed call was for, and dropped it. Your parameters and your request to Google are unchanged.
33
75
 
34
- ## [0.0.4] - 2025-10-28
76
+ ## [0.5.0] - 2026-08-12
35
77
 
36
- ### Fixed
37
- - Correct Crystil request payload structure for OpenAI streaming
78
+ ### Changed
79
+ - **BREAKING**: Renamed Payloop to Crystil. Migrating from `payloop` 0.4.0 requires:
80
+ - Install the `crystil` gem in place of `payloop`; `require "payloop"` becomes
81
+ `require "crystil"`.
82
+ - Replace the `Payloop::*` namespace with `Crystil::*` (e.g. `Payloop::Client` →
83
+ `Crystil::Client`).
84
+ - Rename the `PAYLOOP_API_KEY`, `PAYLOOP_API_URL_BASE`, and `PAYLOOP_COLLECTOR_URL_BASE`
85
+ environment variables to `CRYSTIL_API_KEY`, `CRYSTIL_API_URL_BASE`, and
86
+ `CRYSTIL_COLLECTOR_URL_BASE`.
87
+ - Default endpoints now resolve to `api.crystil.com` and `collector.crystil.com`.
38
88
 
39
- ## [0.1.0] - 2026-02-03
89
+ Nothing else changed.
90
+
91
+ ## [0.4.0] - 2026-05-19
40
92
 
41
93
  ### Added
42
- - Support for Sentinel intercept.
43
- - Support for Gemini AI client tracking.
94
+ - Calls through the `groq` gem (drnic/groq-ruby) are tracked, including streaming.
95
+ - RBS type signatures ship with the gem, for Steep and editors that read them.
44
96
 
45
- ## [0.1.1] - 2026-02-11
97
+ ## [0.3.0] - 2026-04-15
46
98
 
47
- ### Fixed
48
- - Stopped sending collector calls for intercepted requests
99
+ ### Added
100
+ - OpenAI Responses API calls (`client.responses.create`) are tracked, including streaming.
49
101
 
50
102
  ## [0.2.0] - 2026-04-08
51
103
 
52
104
  ### Added
53
- - Support for the RubyLLM library
105
+ - RubyLLM chats are tracked.
54
106
 
55
- ## [0.3.0] - 2026-04-15
107
+ ## [0.1.1] - 2026-02-11
56
108
 
57
- ### Added
58
- - Support OpenAI Responses API (responses.create)
109
+ ### Fixed
110
+ - Calls Sentinel blocks are no longer reported to Crystil as failed calls.
59
111
 
60
- ## [0.4.0] - 2026-05-19
112
+ ## [0.1.0] - 2026-02-03
61
113
 
62
114
  ### Added
63
- - Support for the Groq Ruby client (`groq` gem, drnic/groq-ruby), including streaming.
64
- - RBS type signatures shipped with the gem.
115
+ - Sentinel. Turn it on with `sentinel.raise_if_irrelevant`, and it checks each call before it
116
+ reaches the provider: a call that is not relevant to your app raises instead of being sent.
117
+ - Calls through the `gemini-ai` gem are tracked, including streaming.
65
118
 
66
- ## [0.5.0] - 2026-08-12
119
+ ## [0.0.4] - 2025-10-28
67
120
 
68
- ### Changed
69
- - **BREAKING**: Renamed Payloop to Crystil. Migrating from `payloop` 0.4.0 requires:
70
- - Install the `crystil` gem in place of `payloop`; `require "payloop"` becomes `require "crystil"`.
71
- - Replace the `Payloop::*` namespace with `Crystil::*` (e.g. `Payloop::Client` → `Crystil::Client`).
72
- - Rename the `PAYLOOP_API_KEY`, `PAYLOOP_API_URL_BASE`, and `PAYLOOP_COLLECTOR_URL_BASE`
73
- environment variables to `CRYSTIL_API_KEY`, `CRYSTIL_API_URL_BASE`, and
74
- `CRYSTIL_COLLECTOR_URL_BASE`.
75
- - Default endpoints now resolve to `api.crystil.com` and `collector.crystil.com`.
121
+ ### Fixed
122
+ - Streamed OpenAI Chat calls now report their content and token usage.
76
123
 
77
- No API surface, method signature, or request payload changed — this release is a rename only.
124
+ ## [0.0.3] - 2025-10-27
78
125
 
79
- ## [0.6.0] - 2026-09-18
126
+ ### Changed
127
+ - **BREAKING**: `attribution` no longer takes the deprecated `parent_uuid` and `subsidiary_uuid`.
128
+ Use `parent_id` and `subsidiary_id`.
80
129
 
81
- ### Added
82
- - Capture Anthropic streaming calls. `messages.stream` and `messages.stream_raw` are now
83
- wrapped, and their telemetry is submitted once the caller has read the stream, carrying
84
- the events as the unmerged list the backend's streamed extractor reads — so a streamed
85
- call reports its content and token usage instead of nothing at all. Sentinel's relevance
86
- check now runs on these calls too. `messages.create` is unchanged.
130
+ ### Fixed
131
+ - Google GenAI calls now report their response and its token usage. Before, Crystil could not
132
+ read it.
87
133
 
88
- A read that ends early — `break`, or any of `first` / `take` / `find` / `any?` — is
89
- recorded too, carrying the events received so far. So is a read cut short by an error,
90
- which reports as failed but keeps the partial content and token counts rather than
91
- discarding them.
134
+ ## [0.0.2] - 2025-10-25
92
135
 
93
136
  ### Fixed
94
- - Record which model a `gemini-ai` call used. That gem fixes the model on the client and puts
95
- it in the request path rather than the request body, so a failed call — a local raise, a 4xx,
96
- a timeout — carried no model anywhere: not in the query, and not in the response, which is
97
- the error. The backend could not tell which model the call was for and quarantined the record
98
- instead of storing it as the zero-cost failed call it is. The wrapper now reads the model off
99
- the client and records it on the query, so failed `gemini-ai` calls report like every other
100
- provider's. Successful calls are unaffected — their response already named the model.
101
-
102
- The model is added only to the copy Crystil records, for both the analytics payload and the
103
- sentinel relevance check. Your parameters are not modified and the outbound request to Google
104
- is unchanged. A `model` you pass yourself is kept as-is.
105
-
106
- ### Notes
107
- - `messages.create(stream: true)` raises `ArgumentError` in the `anthropic` gem, which is
108
- why the wrapper patches the two streaming methods rather than the create path the
109
- JavaScript and Python SDKs use.
110
- - `google-genai` (v0.1.1) still has no streaming wrapper because the gem exposes no
111
- streaming method. Streamed Gemini calls through the `gemini-ai` gem were already captured.
137
+ - OpenAI, Anthropic and Google calls now show the right provider and call times in Crystil.
112
138
 
139
+ ## [0.0.1] - 2025-10-13
140
+
141
+ ### Added
142
+ - Initial release.
143
+ - Tracks calls made with the OpenAI (`ruby-openai`), Anthropic (`anthropic`) and Google GenAI
144
+ (`google-genai`) clients, sending their usage to Crystil in the background so your calls are
145
+ not slowed down.
146
+ - Attribution: tag calls with a parent and an optional subsidiary, such as a customer and one of
147
+ its users, to see costs for each.
148
+ - Transactions: group related calls with `new_transaction`.
149
+ - Clients for Crystil's workflow and invocation APIs.
150
+ - The client's settings are safe to change while other threads use it.
data/README.md CHANGED
@@ -40,7 +40,8 @@ version number can never be reused on RubyGems once taken.
40
40
  The supported path is the **`/run-release` skill**
41
41
  ([.claude/skills/run-release/SKILL.md](.claude/skills/run-release/SKILL.md)), which walks these
42
42
  steps, runs the same checks CI will run before anything irreversible happens, and stops for
43
- confirmation before merging and before publishing. The manual steps below are the fallback.
43
+ confirmation before committing the changelog, before merging and before publishing. The manual
44
+ steps below are the fallback.
44
45
 
45
46
  To release version `X.Y.Z`:
46
47
 
@@ -52,8 +53,10 @@ To release version `X.Y.Z`:
52
53
  `meta.sdk.version` field on every payload both read from it.
53
54
 
54
55
  2. **Update the CHANGELOG** in [CHANGELOG.md](CHANGELOG.md):
55
- - Add a new section for the version with today's date
56
+ - Add a new section for the version at the top, above the previous release, with today's date
56
57
  - Document all changes under appropriate categories (Added, Changed, Fixed, etc.)
58
+ - Write for customers: what changed for them and what they must do, never deploy order,
59
+ backend changes, tickets or internal test tooling
57
60
  - Follow the [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format
58
61
 
59
62
  3. **Open a PR and merge it to `main`** once CI is green (lint, type-check, and
@@ -72,12 +75,6 @@ To release version `X.Y.Z`:
72
75
  creates the tag it is lightweight, so that flag falls back to the commit
73
76
  message and your notes end up reading "Merge pull request #NN".
74
77
 
75
- Use the `awk` form, not `sed -n '/^## \[X.Y.Z\]/,/^## \[/p' | sed '$d'`.
76
- CHANGELOG.md is oldest-first, so the version you are releasing is the last
77
- section in the file; with no following `## [` to stop at, the `sed` form runs
78
- to EOF and `sed '$d'` then silently eats its final line. `awk` stops at the
79
- next header or EOF and drops nothing.
80
-
81
78
  Or use the GitHub UI: *Releases → Draft a new release*, create the tag
82
79
  `vX.Y.Z` against `main`, then **Publish release**. Saving a draft does not
83
80
  trigger anything; only publishing does.
@@ -87,7 +84,7 @@ To release version `X.Y.Z`:
87
84
  gh run watch
88
85
  ```
89
86
  Before pushing anything, the workflow verifies the tag matches the version,
90
- runs the unit and mocked integration specs, and asserts the packaged gem
87
+ runs the unit specs, and asserts the packaged gem
91
88
  contains what it should. It then waits for the new version to be installable
92
89
  rather than merely uploaded, so a green run means the release is live.
93
90
 
@@ -0,0 +1,24 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Crystil
4
+ # Callbacks in a request, such as OpenAI's `stream:` or Groq's `stream_chunk`,
5
+ # cannot be sent as JSON or copied with Marshal. Sentinel and every recorded
6
+ # query get `true` in their place.
7
+ module Callables
8
+ # A copy of `obj` with every callable (a Proc, a lambda, a Method, or any
9
+ # object that responds to `call`) replaced by `true`, at any depth inside
10
+ # Hashes and Arrays. `obj` itself is never changed.
11
+ def self.replace_with_true(obj)
12
+ return true if obj.respond_to?(:call)
13
+
14
+ case obj
15
+ when Hash
16
+ obj.transform_values { |value| replace_with_true(value) }
17
+ when Array
18
+ obj.map { |value| replace_with_true(value) }
19
+ else
20
+ obj
21
+ end
22
+ end
23
+ end
24
+ end
@@ -87,6 +87,13 @@ module Crystil
87
87
  )
88
88
  end
89
89
 
90
+ # Waits, for at most `timeout` seconds, until every payload queued before the call has
91
+ # been sent. True when none of them is left. For a serverless handler, frozen once it
92
+ # returns, so no exit hook runs; unlike `shutdown`, the client keeps working after.
93
+ def flush(timeout = Collector::EXIT_WAIT_SECONDS)
94
+ @collector.flush(timeout)
95
+ end
96
+
90
97
  # Gracefully shutdown the client
91
98
  def shutdown
92
99
  @collector.shutdown
@@ -10,6 +10,61 @@ module Crystil
10
10
  class Collector
11
11
  DEFAULT_MAX_RETRIES = 3
12
12
  RETRY_DELAY = 1 # seconds
13
+ # How long a process waits, as it exits, for payloads still being sent.
14
+ EXIT_WAIT_SECONDS = 5
15
+
16
+ # Every collector that has sent something, held weakly, so the exit wait can find them.
17
+ @collectors = ObjectSpace::WeakMap.new
18
+ @lock = Mutex.new
19
+ @exit_wait_added = false
20
+ # Seconds the exit waits have used so far, out of the `EXIT_WAIT_SECONDS` they share.
21
+ @exit_wait_used = 0.0
22
+
23
+ class << self
24
+ # Adds the collector to those the exit wait covers.
25
+ def track(collector)
26
+ @lock.synchronize { @collectors[collector] = true }
27
+ end
28
+
29
+ # Makes sure an exit hook will wait for this send, since Ruby kills the pool's threads
30
+ # at exit. Ruby runs hooks newest first, so each wait clears the flag: a send from an
31
+ # older hook then adds a new one, which Ruby runs next.
32
+ def add_exit_wait
33
+ return if @exit_wait_added
34
+
35
+ @lock.synchronize do
36
+ next if @exit_wait_added
37
+
38
+ @exit_wait_added = true
39
+ at_exit { wait_at_exit }
40
+ end
41
+ end
42
+
43
+ # Waits for every collector within what is left of the shared budget. It never shuts
44
+ # a pool down, so a payload sent from a later exit hook still goes out.
45
+ def wait_at_exit
46
+ started = now
47
+ # Cleared before the wait looks, so a send it does not see adds a new hook.
48
+ @lock.synchronize { @exit_wait_added = false }
49
+ flush_all(EXIT_WAIT_SECONDS - @exit_wait_used)
50
+ ensure
51
+ @lock.synchronize { @exit_wait_used += now - started }
52
+ end
53
+
54
+ # Waits until every collector has nothing left to send, sharing one deadline of
55
+ # `seconds`. True when all of them finished in time.
56
+ def flush_all(seconds)
57
+ deadline = now + seconds
58
+ collectors = @lock.synchronize { @collectors.keys }
59
+ collectors.all? { |collector| collector.wait_until_idle(deadline - now) }
60
+ rescue StandardError
61
+ false
62
+ end
63
+
64
+ def now
65
+ Process.clock_gettime(Process::CLOCK_MONOTONIC)
66
+ end
67
+ end
13
68
 
14
69
  def initialize(config)
15
70
  @config = config
@@ -19,15 +74,39 @@ module Crystil
19
74
  max_queue: 100,
20
75
  fallback_policy: :discard
21
76
  )
77
+ # Each payload gets the next number, so `flush` can wait for those queued before it.
78
+ @last_number = Concurrent::AtomicFixnum.new(0)
79
+ # The numbers of the payloads queued and not yet sent or failed. Not the pool's own task
80
+ # counts: tasks finish out of order, so a count cannot say which payloads are done.
81
+ @unsent = Concurrent::Map.new
82
+ # The process that made the first send; nil until then.
83
+ @pid = nil
84
+ @start_lock = Mutex.new
22
85
  end
23
86
 
24
87
  # Submit analytics payload asynchronously
25
88
  def submit_async(payload)
26
- @executor.post do
27
- submit_with_retry(payload)
28
- rescue StandardError => e
29
- warn "Crystil: Failed to submit analytics: #{e.message}"
89
+ start_in_this_process unless @pid == Process.pid
90
+ # The task removes its number from the map it was added to, even if a fork replaces it.
91
+ unsent = @unsent
92
+ number = @last_number.increment
93
+ queued = false
94
+ begin
95
+ unsent[number] = true
96
+ # After the number is added, so an exit wait that finds every collector idle has not missed it.
97
+ Collector.add_exit_wait
98
+ queued = @executor.post do
99
+ submit_with_retry(payload)
100
+ rescue StandardError => e
101
+ warn "Crystil: Failed to submit analytics: #{e.message}"
102
+ ensure
103
+ unsent.delete(number)
104
+ end
105
+ ensure
106
+ # A payload the pool did not queue (a full queue, a shut-down pool, a timeout first) is not waited for.
107
+ unsent.delete(number) unless queued
30
108
  end
109
+ queued
31
110
  end
32
111
 
33
112
  # Submit analytics payload synchronously (for testing)
@@ -35,6 +114,26 @@ module Crystil
35
114
  submit_with_retry(payload)
36
115
  end
37
116
 
117
+ # Waits until every payload queued before the call has been sent, or has failed, for
118
+ # at most `timeout` seconds; one queued during the wait is not waited for. True when
119
+ # none of them is left. Unlike `shutdown`, the collector keeps working afterwards.
120
+ def flush(timeout = EXIT_WAIT_SECONDS)
121
+ last = @last_number.value
122
+ wait_until(timeout) { idle_up_to?(last) }
123
+ end
124
+
125
+ # Waits until nothing is left to send, a payload queued during the wait included, for
126
+ # at most `timeout` seconds. True when nothing is left. The exit wait uses it.
127
+ def wait_until_idle(timeout)
128
+ wait_until(timeout) { idle? }
129
+ end
130
+
131
+ # True when nothing this process queued is still waiting to be sent. A forked
132
+ # child inherits the numbers but not the queue, so in the child they mean nothing.
133
+ def idle?
134
+ @pid != Process.pid || @unsent.empty?
135
+ end
136
+
38
137
  # Gracefully shutdown the collector
39
138
  def shutdown
40
139
  @executor.shutdown
@@ -43,6 +142,30 @@ module Crystil
43
142
 
44
143
  private
45
144
 
145
+ # True when no payload numbered `last` or lower is still waiting to be sent.
146
+ def idle_up_to?(last)
147
+ @pid != Process.pid || @unsent.keys.none? { |number| number <= last }
148
+ end
149
+
150
+ def wait_until(timeout)
151
+ deadline = self.class.now + timeout
152
+ sleep(0.01) until yield || self.class.now >= deadline
153
+ yield
154
+ end
155
+
156
+ # Runs once per process: a forked child inherits the parent's unsent numbers but not
157
+ # its queue, so it starts a new map and joins the exit wait. `@pid` is set last, so
158
+ # no other thread skips this step before the new map is in place.
159
+ def start_in_this_process
160
+ @start_lock.synchronize do
161
+ next if @pid == Process.pid
162
+
163
+ @unsent = Concurrent::Map.new
164
+ Collector.track(self)
165
+ @pid = Process.pid
166
+ end
167
+ end
168
+
46
169
  def submit_with_retry(payload, attempt = 1)
47
170
  response = post_to_collector(payload)
48
171
 
@@ -72,29 +72,12 @@ module Crystil
72
72
  end
73
73
 
74
74
  def normalize_request(request)
75
- # Remove Procs before JSON creation since the
76
- # procs or methods will fail for normalization.
77
- # We know that OpenAI sends a proc on their
78
- # request, so this is mostly for that.
79
- cleaned = remove_procs(request)
75
+ # Callbacks, such as OpenAI's `stream:` Proc, would fail the JSON round trip.
76
+ cleaned = Callables.replace_with_true(request)
80
77
  json_obj = JSON.generate(cleaned)
81
78
  JSON.parse(json_obj)
82
79
  rescue StandardError
83
80
  request
84
81
  end
85
-
86
- def remove_procs(obj)
87
- case obj
88
- when Hash
89
- obj.transform_values { |v| remove_procs(v) }
90
- when Array
91
- obj.map { |v| remove_procs(v) }
92
- when Proc, Method
93
- true
94
- else
95
- # Return true object for any callable object; otherwise return obj.
96
- obj.respond_to?(:call) || obj
97
- end
98
- end
99
82
  end
100
83
  end
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Crystil
4
- VERSION = "0.6.0"
4
+ VERSION = "0.7.0"
5
5
  end
@@ -124,12 +124,13 @@ module Crystil
124
124
 
125
125
  # Extract parameters for sentinel and analytics
126
126
  params = Crystil::Wrappers::Anthropic.recorded_params(kwargs.any? ? kwargs : (args.first || {}))
127
- sentinel = instance_variable_get(:@crystil_sentinel)
128
- sentinel&.raise_if_irrelevant!(
127
+ crystil_raise_if_irrelevant!(
129
128
  title: ANTHROPIC_CLIENT_TITLE,
130
129
  request: params,
130
+ start_time: start_time,
131
131
  version: version
132
132
  )
133
+ passed_sentinel = true
133
134
 
134
135
  # Call original method
135
136
  response = if kwargs.any?
@@ -139,6 +140,7 @@ module Crystil
139
140
  end
140
141
 
141
142
  # Submit analytics
143
+ recorded = true
142
144
  crystil_submit_analytics(
143
145
  method: :create,
144
146
  args: args,
@@ -151,24 +153,21 @@ module Crystil
151
153
  )
152
154
 
153
155
  response
154
- rescue CrystilRequestInterceptedError => e
155
- # We don't want to send intercepts to collector
156
- raise e
157
- rescue StandardError => e
158
- params = Crystil::Wrappers::Anthropic.recorded_params(kwargs.any? ? kwargs : (args.first || {}))
159
-
160
- crystil_submit_error_analytics(
161
- method: :create,
162
- args: args,
163
- kwargs: params,
164
- error: e,
165
- start_time: start_time,
166
- end_time: Time.now,
167
- title: ANTHROPIC_CLIENT_TITLE,
168
- version: version
169
- )
156
+ rescue SignalException, StandardError => e
157
+ # Recorded as blocked where Sentinel answers (crystil_raise_if_irrelevant!), never as a failure.
158
+ raise e if crystil_block_already_recorded?(e, passed_sentinel)
170
159
 
160
+ error = e
171
161
  raise e
162
+ ensure
163
+ # Recorded here, not in the rescue: a timeout or a killed thread skips the rescue.
164
+ # A signal is recorded as stopped, anything else as failed; a call that never passed Sentinel is not.
165
+ if !recorded && passed_sentinel
166
+ crystil_submit_unfinished_analytics(
167
+ error, nil,
168
+ method: :create, kwargs: params, start_time: start_time, title: ANTHROPIC_CLIENT_TITLE, version: version
169
+ )
170
+ end
172
171
  end
173
172
  end
174
173
 
@@ -191,12 +190,14 @@ module Crystil
191
190
 
192
191
  # Extract parameters for sentinel and analytics
193
192
  params = Crystil::Wrappers::Anthropic.recorded_params(kwargs.any? ? kwargs : (args.first || {}))
194
- sentinel = instance_variable_get(:@crystil_sentinel)
195
- sentinel&.raise_if_irrelevant!(
193
+ crystil_raise_if_irrelevant!(
196
194
  title: ANTHROPIC_CLIENT_TITLE,
197
195
  request: params,
196
+ query: Crystil::Wrappers::Anthropic.streamed_query(params),
197
+ start_time: start_time,
198
198
  version: version
199
199
  )
200
+ passed_sentinel = true
200
201
 
201
202
  # Call original method
202
203
  stream = if kwargs.any?
@@ -220,27 +221,27 @@ module Crystil
220
221
  )
221
222
  end
222
223
 
224
+ # From here the stream's reads and `close` report the call.
225
+ recorded = true
223
226
  # The caller's own object, so `accumulated_message`, `text`,
224
227
  # `until_done` and the rest of its surface keep working.
225
228
  stream
226
- rescue CrystilRequestInterceptedError => e
227
- # We don't want to send intercepts to collector
228
- raise e
229
- rescue StandardError => e
230
- params = Crystil::Wrappers::Anthropic.recorded_params(kwargs.any? ? kwargs : (args.first || {}))
231
-
232
- crystil_submit_error_analytics(
233
- method: method_name,
234
- args: [],
235
- kwargs: Crystil::Wrappers::Anthropic.streamed_query(params),
236
- error: e,
237
- start_time: start_time,
238
- end_time: Time.now,
239
- title: ANTHROPIC_CLIENT_TITLE,
240
- version: version
241
- )
229
+ rescue SignalException, StandardError => e
230
+ # Recorded as blocked where Sentinel answers (crystil_raise_if_irrelevant!), never as a failure.
231
+ raise e if crystil_block_already_recorded?(e, passed_sentinel)
242
232
 
233
+ error = e
243
234
  raise e
235
+ ensure
236
+ # Recorded here, not in the rescue: a timeout or a killed thread skips the rescue.
237
+ # A signal is recorded as stopped, anything else as failed; a call that never passed Sentinel is not.
238
+ if !recorded && passed_sentinel
239
+ crystil_submit_unfinished_analytics(
240
+ error, nil,
241
+ method: method_name, kwargs: Crystil::Wrappers::Anthropic.streamed_query(params),
242
+ start_time: start_time, title: ANTHROPIC_CLIENT_TITLE, version: version
243
+ )
244
+ end
244
245
  end
245
246
  end
246
247
  end