agentcat 0.0.1 → 1.0.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 (50) hide show
  1. checksums.yaml +4 -4
  2. data/LICENSE +2 -11
  3. data/README.md +265 -20
  4. data/lib/agentcat/adapters/base.rb +73 -0
  5. data/lib/agentcat/adapters/official.rb +194 -0
  6. data/lib/agentcat/client.rb +171 -0
  7. data/lib/agentcat/clock.rb +16 -0
  8. data/lib/agentcat/custom_event.rb +215 -0
  9. data/lib/agentcat/delivery.rb +58 -0
  10. data/lib/agentcat/diagnostics.rb +434 -0
  11. data/lib/agentcat/error_capture.rb +117 -0
  12. data/lib/agentcat/event_id.rb +19 -0
  13. data/lib/agentcat/event_pipeline.rb +82 -0
  14. data/lib/agentcat/event_queue.rb +151 -0
  15. data/lib/agentcat/exporters/base.rb +135 -0
  16. data/lib/agentcat/exporters/datadog.rb +137 -0
  17. data/lib/agentcat/exporters/otlp.rb +157 -0
  18. data/lib/agentcat/exporters/posthog.rb +185 -0
  19. data/lib/agentcat/exporters/sentry.rb +242 -0
  20. data/lib/agentcat/exporters/trace_context.rb +79 -0
  21. data/lib/agentcat/exporters.rb +108 -0
  22. data/lib/agentcat/fork_safety.rb +30 -0
  23. data/lib/agentcat/hooks.rb +190 -0
  24. data/lib/agentcat/http_post.rb +61 -0
  25. data/lib/agentcat/interceptor.rb +711 -0
  26. data/lib/agentcat/log.rb +80 -0
  27. data/lib/agentcat/options.rb +313 -0
  28. data/lib/agentcat/payload_limits.rb +71 -0
  29. data/lib/agentcat/private_members.rb +271 -0
  30. data/lib/agentcat/redaction.rb +115 -0
  31. data/lib/agentcat/rejected_calls.rb +147 -0
  32. data/lib/agentcat/request_context.rb +266 -0
  33. data/lib/agentcat/sanitization.rb +191 -0
  34. data/lib/agentcat/schema/prompts.rb +44 -0
  35. data/lib/agentcat/session_manager.rb +83 -0
  36. data/lib/agentcat/tags.rb +61 -0
  37. data/lib/agentcat/test_mode.rb +86 -0
  38. data/lib/agentcat/testing.rb +153 -0
  39. data/lib/agentcat/text.rb +68 -0
  40. data/lib/agentcat/token_estimate.rb +98 -0
  41. data/lib/agentcat/tool_call.rb +129 -0
  42. data/lib/agentcat/tool_handle.rb +289 -0
  43. data/lib/agentcat/tracker.rb +201 -0
  44. data/lib/agentcat/truncation.rb +265 -0
  45. data/lib/agentcat/unredacted_event.rb +155 -0
  46. data/lib/agentcat/user_identity.rb +11 -0
  47. data/lib/agentcat/version.rb +2 -2
  48. data/lib/agentcat.rb +391 -21
  49. metadata +193 -16
  50. data/agentcat.gemspec +0 -30
@@ -0,0 +1,185 @@
1
+ # typed: true
2
+
3
+ module AgentCat
4
+ module Exporters
5
+ # Sends each event to PostHog's batch endpoint, like TS's
6
+ # src/modules/exporters/posthog.ts: one capture event, a `$exception` event for an
7
+ # error, and with enable_ai_tracing a `$ai_span` event for each tool call.
8
+ #
9
+ # AgentCat.track(server, project_id, AgentCat::Options.new(
10
+ # exporters: [AgentCat::Exporters::PostHog.new(api_key: ENV["POSTHOG_PROJECT_API_KEY"])]
11
+ # ))
12
+ #
13
+ # Keys (TS names in snake_case): api_key (required), host (default
14
+ # "https://us.i.posthog.com"; self-hosted and EU too) and enable_ai_tracing
15
+ # (default false). Ruby only: http_post.
16
+ class PostHog < Base
17
+ extend T::Sig
18
+
19
+ DEFAULT_HOST = "https://us.i.posthog.com"
20
+
21
+ CONFIG_KEYS = {
22
+ "api_key" => :api_key, "apiKey" => :api_key, "host" => :host,
23
+ "enable_ai_tracing" => :enable_ai_tracing, "enableAITracing" => :enable_ai_tracing,
24
+ "http_post" => :http_post
25
+ }.freeze
26
+
27
+ # TS posthog.ts:327-343.
28
+ EVENT_NAMES = {
29
+ "mcp:tools/call" => "mcp_tool_call",
30
+ "mcp:tools/list" => "mcp_tools_list",
31
+ "mcp:initialize" => "mcp_initialize",
32
+ "mcp:resources/read" => "mcp_resource_read",
33
+ "mcp:resources/list" => "mcp_resources_list",
34
+ "mcp:prompts/get" => "mcp_prompt_get",
35
+ "mcp:prompts/list" => "mcp_prompts_list"
36
+ }.freeze
37
+
38
+ sig { returns(T.nilable(String)) }
39
+ attr_reader :batch_url
40
+
41
+ sig do
42
+ params(
43
+ api_key: T.nilable(String),
44
+ host: T.nilable(String),
45
+ enable_ai_tracing: T::Boolean,
46
+ http_post: T.untyped
47
+ ).void
48
+ end
49
+ def initialize(api_key: nil, host: nil, enable_ai_tracing: false, http_post: nil)
50
+ if blank?(api_key)
51
+ setup_failed!("PostHog exporter needs an api_key (project API key)")
52
+ return
53
+ end
54
+
55
+ @api_key = T.must(api_key)
56
+ @enable_ai_tracing = enable_ai_tracing
57
+ @batch_url = T.let("#{base_url(host)}/batch", T.nilable(String))
58
+ @http_post = resolve_http_post(http_post)
59
+ end
60
+
61
+ sig { params(event: UnredactedEvent).void }
62
+ def export!(event)
63
+ batch = [capture_event(event)]
64
+ batch << exception_event(event) if event.is_error && event.error
65
+ batch << ai_span_event(event) if @enable_ai_tracing && event.event_type == TOOLS_CALL
66
+ post_json!("PostHog", T.must(@batch_url), {"Content-Type" => "application/json"}, {api_key: @api_key, batch: batch})
67
+ end
68
+
69
+ private
70
+
71
+ # TS posthog.ts:101 takes host as a URL, scheme included, and drops one trailing
72
+ # slash. Ruby only: a bare host ("eu.i.posthog.com")
73
+ # gets https://, instead of making a URL with no scheme.
74
+ sig { params(host: T.nilable(String)).returns(String) }
75
+ def base_url(host)
76
+ url = blank?(host) ? DEFAULT_HOST : T.must(host)
77
+ url = "https://#{url}" unless %r{\A[a-z][a-z0-9+.-]*://}i.match?(url)
78
+ url.sub(%r{/\z}, "")
79
+ end
80
+
81
+ sig { params(event: UnredactedEvent).returns(String) }
82
+ def distinct_id(event)
83
+ [event.identify_actor_given_id, event.session_id].find { |id| truthy?(id) } || "anonymous"
84
+ end
85
+
86
+ sig { params(event: UnredactedEvent, name: String, properties: T::Hash[String, T.untyped]).returns(T::Hash[Symbol, T.untyped]) }
87
+ def capture(event, name, properties)
88
+ {event: name, distinct_id: distinct_id(event), properties: properties, timestamp: iso_millis(event_millis(event)), type: "capture"}
89
+ end
90
+
91
+ sig { params(event: UnredactedEvent, properties: T::Hash[String, T.untyped]).void }
92
+ def add_resource(event, properties)
93
+ return unless truthy?(event.resource_name)
94
+
95
+ properties["resource_name"] = event.resource_name
96
+ properties["tool_name"] = event.resource_name if event.event_type == TOOLS_CALL
97
+ end
98
+
99
+ sig { params(properties: T::Hash[String, T.untyped], values: T::Hash[String, T.untyped]).void }
100
+ def add_truthy(properties, values)
101
+ values.each { |key, value| properties[key] = value if truthy?(value) }
102
+ end
103
+
104
+ # Customer tags, then customer properties, spread on top: they can override
105
+ # AgentCat's own keys, like TS.
106
+ sig { params(event: UnredactedEvent, properties: T::Hash[String, T.untyped]).void }
107
+ def spread_customer_data(event, properties)
108
+ properties.merge!(wire_tags(event) || {})
109
+ properties.merge!(wire_properties(event) || {})
110
+ end
111
+
112
+ # TS posthog.ts:156-225.
113
+ sig { params(event: UnredactedEvent).returns(T::Hash[Symbol, T.untyped]) }
114
+ def capture_event(event)
115
+ properties = {"source" => SOURCE}
116
+ properties["$session_id"] = TraceContext.uuid_v7(T.must(session_id(event))) if session_id(event)
117
+ add_resource(event, properties)
118
+ properties["duration_ms"] = event.duration
119
+ add_truthy(properties, {
120
+ "server_name" => event.server_name, "server_version" => event.server_version,
121
+ "client_name" => event.client_name, "client_version" => event.client_version,
122
+ "project_id" => event.project_id, "user_intent" => event.user_intent
123
+ })
124
+ properties["is_error"] = event.is_error
125
+ properties["parameters"] = event.parameters
126
+ properties["response"] = event.response unless event.response.nil?
127
+
128
+ set = {}
129
+ set["name"] = event.identify_actor_name if truthy?(event.identify_actor_name)
130
+ set.merge!(event.identify_data.to_h) if event.identify_data
131
+ properties["$set"] = set unless set.empty?
132
+
133
+ spread_customer_data(event, properties)
134
+ capture(event, event_name(event.event_type), properties)
135
+ end
136
+
137
+ # TS posthog.ts:227-269.
138
+ sig { params(event: UnredactedEvent).returns(T::Hash[Symbol, T.untyped]) }
139
+ def exception_event(event)
140
+ properties = {"$exception_source" => "backend"}
141
+ properties["$session_id"] = TraceContext.uuid_v7(T.must(session_id(event))) if session_id(event)
142
+ error = event.error || {}
143
+ add_truthy(properties, {
144
+ "$exception_message" => error["message"], "$exception_type" => error["type"],
145
+ "$exception_stacktrace" => error["stack"]
146
+ })
147
+ add_resource(event, properties)
148
+ add_truthy(properties, {
149
+ "server_name" => event.server_name, "server_version" => event.server_version,
150
+ "client_name" => event.client_name, "client_version" => event.client_version
151
+ })
152
+ capture(event, "$exception", properties)
153
+ end
154
+
155
+ # TS posthog.ts:271-325.
156
+ sig { params(event: UnredactedEvent).returns(T::Hash[Symbol, T.untyped]) }
157
+ def ai_span_event(event)
158
+ session = session_id(event)
159
+ properties = {
160
+ "$ai_trace_id" => TraceContext.uuid_v7(session || event.id),
161
+ "$ai_span_id" => TraceContext.uuid_v7(event.id),
162
+ "$ai_span_name" => truthy?(event.resource_name) ? event.resource_name : "unknown_tool",
163
+ "$ai_is_error" => event.is_error,
164
+ "source" => SOURCE
165
+ }
166
+ if session
167
+ properties["$ai_session_id"] = "agentcat_#{session}"
168
+ properties["$session_id"] = TraceContext.uuid_v7(session)
169
+ end
170
+ properties["$ai_latency"] = js_number(event.duration / 1000.0)
171
+ properties["$ai_error"] = event.error if event.is_error && event.error
172
+ properties["$ai_input_state"] = event.parameters
173
+ properties["$ai_output_state"] = event.response unless event.response.nil?
174
+ add_truthy(properties, {"server_name" => event.server_name, "client_name" => event.client_name})
175
+ spread_customer_data(event, properties)
176
+ capture(event, "$ai_span", properties)
177
+ end
178
+
179
+ sig { params(event_type: String).returns(String) }
180
+ def event_name(event_type)
181
+ EVENT_NAMES[event_type] || "mcp_#{event_type.sub(/\Amcp:/, "").tr("/", "_")}"
182
+ end
183
+ end
184
+ end
185
+ end
@@ -0,0 +1,242 @@
1
+ # typed: true
2
+
3
+ require "json"
4
+ require "time"
5
+
6
+ module AgentCat
7
+ module Exporters
8
+ # Sends events to Sentry's envelope endpoint, built from your DSN, like TS's
9
+ # src/modules/exporters/sentry.ts: a log for every event, a transaction for every
10
+ # event with enable_tracing, and an error event (an Issue) for every failed call.
11
+ # It uses only its own dsn:, never the sentry-ruby gem or your app's Sentry.init.
12
+ #
13
+ # AgentCat.track(server, project_id, AgentCat::Options.new(
14
+ # exporters: [AgentCat::Exporters::Sentry.new(dsn: ENV["SENTRY_DSN"], environment: "production")]
15
+ # ))
16
+ #
17
+ # Keys (TS names in snake_case): dsn (required), environment, release and
18
+ # enable_tracing (default false). Like TS, environment and release go out as tags.
19
+ # Ruby only: http_post.
20
+ class Sentry < Base
21
+ extend T::Sig
22
+
23
+ CONFIG_KEYS = {
24
+ "dsn" => :dsn, "environment" => :environment, "release" => :release,
25
+ "enable_tracing" => :enable_tracing, "enableTracing" => :enable_tracing,
26
+ "http_post" => :http_post
27
+ }.freeze
28
+
29
+ # protocol://public_key@host[:port][/path]/project_id, TS sentry.ts:350.
30
+ DSN_PATTERN = %r{\A(https?)://([a-f0-9]+)@([\w.-]+)(:\d+)?(/.*)?/(\d+)\z}
31
+ # TS sentry.ts:343, word for word: the client name is TS's, not a Ruby one.
32
+ AUTH_HEADER = "Sentry sentry_version=7, sentry_client=agentcat/1.0.0, sentry_key=%s"
33
+ CONTENT_TYPE = "application/x-sentry-envelope"
34
+
35
+ sig { returns(T.nilable(String)) }
36
+ attr_reader :endpoint
37
+
38
+ sig do
39
+ params(
40
+ dsn: T.nilable(String),
41
+ environment: T.nilable(String),
42
+ release: T.nilable(String),
43
+ enable_tracing: T::Boolean,
44
+ http_post: T.untyped
45
+ ).void
46
+ end
47
+ def initialize(dsn: nil, environment: nil, release: nil, enable_tracing: false, http_post: nil)
48
+ if blank?(dsn)
49
+ setup_failed!("Sentry exporter needs a dsn")
50
+ return
51
+ end
52
+ match = DSN_PATTERN.match(T.must(dsn))
53
+ if match.nil?
54
+ # The DSN itself stays out of the line: it carries the project's key.
55
+ setup_failed!("Sentry exporter got an invalid dsn (expected https://<public_key>@<host>/<project_id>)")
56
+ return
57
+ end
58
+
59
+ @endpoint = T.let("#{match[1]}://#{match[3]}#{match[4]}#{match[5]}/api/#{match[6]}/envelope/", T.nilable(String))
60
+ @headers = {"X-Sentry-Auth" => format(AUTH_HEADER, match[2]), "Content-Type" => CONTENT_TYPE}
61
+ @environment = environment
62
+ @release = release
63
+ @enable_tracing = enable_tracing
64
+ @http_post = resolve_http_post(http_post)
65
+ end
66
+
67
+ # Every envelope goes out even when one fails, like TS; a failure then raises so
68
+ # Exporters.dispatch logs it.
69
+ sig { params(event: UnredactedEvent).void }
70
+ def export!(event)
71
+ envelopes = [log_envelope(event)]
72
+ transaction = transaction(event) if @enable_tracing
73
+ envelopes << envelope(transaction[:event_id], {type: "transaction"}, transaction) if transaction
74
+ if event.is_error
75
+ error_event = error_event(event, transaction)
76
+ envelopes << envelope(error_event[:event_id], {type: "event", content_type: "application/json"}, error_event)
77
+ end
78
+
79
+ failures = T.let([], T::Array[StandardError])
80
+ envelopes.each do |body|
81
+ post!("Sentry", T.must(@endpoint), @headers, body)
82
+ rescue => e
83
+ failures << e
84
+ end
85
+ raise T.must(failures.first) unless failures.empty?
86
+ end
87
+
88
+ private
89
+
90
+ sig { params(event_id: String, item_header: T::Hash[Symbol, T.untyped], item: T.untyped).returns(String) }
91
+ def envelope(event_id, item_header, item)
92
+ [{event_id: event_id, sent_at: Time.now.utc.iso8601(3)}.to_json, item_header.to_json, item.to_json].join("\n")
93
+ end
94
+
95
+ sig { params(event: UnredactedEvent).returns(Numeric) }
96
+ def seconds(event)
97
+ js_number(event_millis(event) / 1000.0)
98
+ end
99
+
100
+ # TS sentry.ts:456-480 and 539-566. The log envelope alone ends in a newline.
101
+ sig { params(event: UnredactedEvent).returns(String) }
102
+ def log_envelope(event)
103
+ event_id = TraceContext.span_id(event.id) * 2
104
+ type = truthy?(event.event_type) ? event.event_type : "event"
105
+ log = {
106
+ timestamp: seconds(event),
107
+ trace_id: TraceContext.trace_id(session_id(event)),
108
+ event_id: event_id,
109
+ level: event.is_error ? "error" : "info",
110
+ body: truthy?(event.resource_name) ? "MCP #{type}: #{event.resource_name}" : "MCP #{type}",
111
+ attributes: log_attributes(event)
112
+ }
113
+ item_header = {type: "log", item_count: 1, content_type: "application/vnd.sentry.items.log+json"}
114
+ envelope(event_id, item_header, {items: [log]}) + "\n"
115
+ end
116
+
117
+ # TS sentry.ts:482-537.
118
+ sig { params(event: UnredactedEvent).returns(T::Hash[String, T.untyped]) }
119
+ def log_attributes(event)
120
+ attributes = {}
121
+ {
122
+ "eventType" => event.event_type, "resourceName" => event.resource_name,
123
+ "serverName" => event.server_name, "clientName" => event.client_name,
124
+ "sessionId" => event.session_id, "projectId" => event.project_id
125
+ }.each { |key, value| attributes[key] = {value: value, type: "string"} if truthy?(value) }
126
+ attributes["duration_ms"] = {value: event.duration, type: "double"}
127
+ {
128
+ "actorId" => event.identify_actor_given_id, "actorName" => event.identify_actor_name,
129
+ "userIntent" => event.user_intent, "serverVersion" => event.server_version,
130
+ "clientVersion" => event.client_version
131
+ }.each { |key, value| attributes[key] = {value: value, type: "string"} if truthy?(value) }
132
+ attributes["isError"] = {value: event.is_error, type: "boolean"}
133
+ attributes
134
+ end
135
+
136
+ sig { params(event: UnredactedEvent).returns(String) }
137
+ def transaction_name(event)
138
+ if truthy?(event.resource_name)
139
+ "#{truthy?(event.event_type) ? event.event_type : "mcp"} - #{event.resource_name}"
140
+ else
141
+ truthy?(event.event_type) ? event.event_type : "mcp.event"
142
+ end
143
+ end
144
+
145
+ sig { params(event: UnredactedEvent).returns(String) }
146
+ def op(event)
147
+ truthy?(event.event_type) ? event.event_type : "mcp.event"
148
+ end
149
+
150
+ # TS sentry.ts:568-603. The event time is the end of the span.
151
+ sig { params(event: UnredactedEvent).returns(T::Hash[Symbol, T.untyped]) }
152
+ def transaction(event)
153
+ finish = seconds(event)
154
+ start = truthy?(event.duration) ? js_number(finish - (event.duration / 1000.0)) : finish
155
+ trace = {
156
+ trace_id: TraceContext.trace_id(session_id(event)),
157
+ span_id: TraceContext.span_id(event.id),
158
+ op: op(event),
159
+ status: event.is_error ? "internal_error" : "ok"
160
+ }
161
+ {
162
+ type: "transaction",
163
+ event_id: TraceContext.span_id(event.id) + TraceContext.span_id,
164
+ timestamp: finish,
165
+ start_timestamp: start,
166
+ transaction: transaction_name(event),
167
+ contexts: contexts(event, trace),
168
+ tags: tags(event),
169
+ extra: extra(event)
170
+ }
171
+ end
172
+
173
+ # TS sentry.ts:659-735.
174
+ sig { params(event: UnredactedEvent, transaction: T.nilable(T::Hash[Symbol, T.untyped])).returns(T::Hash[Symbol, T.untyped]) }
175
+ def error_event(event, transaction)
176
+ message = "Unknown error"
177
+ type = "ToolCallError"
178
+ if (error = event.error)
179
+ message = error.key?("message") ? error["message"].to_s : error.to_json
180
+ type = error["type"].to_s if error.key?("type")
181
+ end
182
+ trace = {
183
+ trace_id: transaction ? transaction[:contexts][:trace][:trace_id] : TraceContext.trace_id(session_id(event)),
184
+ span_id: TraceContext.span_id(event.id),
185
+ parent_span_id: transaction&.dig(:contexts, :trace, :span_id),
186
+ op: transaction ? transaction[:contexts][:trace][:op] : op(event)
187
+ }.compact
188
+ mcp = {
189
+ resource_name: event.resource_name, session_id: event.session_id,
190
+ event_type: event.event_type, user_intent: event.user_intent
191
+ }.compact
192
+ {
193
+ type: "event",
194
+ event_id: TraceContext.span_id(event.id) + TraceContext.span_id,
195
+ timestamp: transaction ? transaction[:timestamp] : seconds(event),
196
+ level: "error",
197
+ exception: {values: [{type: type, value: message, mechanism: {type: "mcp_tool_call", handled: false}}]},
198
+ contexts: contexts(event, trace).merge(mcp: mcp),
199
+ tags: tags(event),
200
+ extra: extra(event),
201
+ transaction: transaction ? transaction[:transaction] : transaction_name(event)
202
+ }
203
+ end
204
+
205
+ # TS sentry.ts:605-626.
206
+ sig { params(event: UnredactedEvent).returns(T::Hash[String, String]) }
207
+ def tags(event)
208
+ tags = {"source" => SOURCE}
209
+ {
210
+ "environment" => @environment, "release" => @release, "event_type" => event.event_type,
211
+ "resource" => event.resource_name, "server_name" => event.server_name,
212
+ "client_name" => event.client_name, "actor_id" => event.identify_actor_given_id
213
+ }.each { |key, value| tags[key] = value if truthy?(value) }
214
+ wire_tags(event)&.each { |key, value| tags["agentcat.#{key}"] = value }
215
+ tags
216
+ end
217
+
218
+ # TS sentry.ts:628-641.
219
+ sig { params(event: UnredactedEvent).returns(T::Hash[String, T.untyped]) }
220
+ def extra(event)
221
+ extra = {}
222
+ {
223
+ "session_id" => event.session_id, "project_id" => event.project_id,
224
+ "user_intent" => event.user_intent, "actor_name" => event.identify_actor_name,
225
+ "server_version" => event.server_version, "client_version" => event.client_version
226
+ }.each { |key, value| extra[key] = value if truthy?(value) }
227
+ extra["duration_ms"] = event.duration
228
+ extra["error"] = event.error if event.error
229
+ extra
230
+ end
231
+
232
+ # TS sentry.ts:643-657.
233
+ sig { params(event: UnredactedEvent, trace: T::Hash[Symbol, T.untyped]).returns(T::Hash[Symbol, T.untyped]) }
234
+ def contexts(event, trace)
235
+ contexts = {trace: trace}
236
+ properties = wire_properties(event)
237
+ contexts[:agentcat] = properties if properties
238
+ contexts
239
+ end
240
+ end
241
+ end
242
+ end
@@ -0,0 +1,79 @@
1
+ # typed: true
2
+
3
+ require "digest"
4
+ require "securerandom"
5
+
6
+ module AgentCat
7
+ module Exporters
8
+ # Trace, span and UUIDv7 ids the exporters derive from AgentCat ids, byte for byte
9
+ # the TS SDK's (src/modules/exporters/trace-context.ts and `toUUIDv7` in
10
+ # src/modules/exporters/posthog.ts). The same session always lands in the same
11
+ # trace, in every vendor and in every SDK language.
12
+ module TraceContext
13
+ KSUID_EPOCH = 1_400_000_000
14
+ KSUID_BODY = /\A[0-9A-Za-z]{27}\z/
15
+ BASE62 = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
16
+
17
+ class << self
18
+ extend T::Sig
19
+
20
+ # 32 hex digits: SHA-256 of the session id, or random when there is none.
21
+ sig { params(session_id: T.nilable(String)).returns(String) }
22
+ def trace_id(session_id)
23
+ return SecureRandom.hex(16) if session_id.nil? || session_id.empty?
24
+
25
+ T.must(Digest::SHA256.hexdigest(session_id)[0, 32])
26
+ end
27
+
28
+ # 16 hex digits: SHA-256 of the event id, or random when there is none.
29
+ sig { params(event_id: T.nilable(String)).returns(String) }
30
+ def span_id(event_id = nil)
31
+ return SecureRandom.hex(8) if event_id.nil? || event_id.empty?
32
+
33
+ T.must(Digest::SHA256.hexdigest(event_id)[0, 16])
34
+ end
35
+
36
+ # Datadog wants 64-bit decimal ids: the low half of the trace id.
37
+ sig { params(session_id: T.nilable(String)).returns(String) }
38
+ def datadog_trace_id(session_id)
39
+ T.must(trace_id(session_id)[16, 16]).to_i(16).to_s
40
+ end
41
+
42
+ sig { params(event_id: T.nilable(String)).returns(String) }
43
+ def datadog_span_id(event_id)
44
+ span_id(event_id).to_i(16).to_s
45
+ end
46
+
47
+ # A deterministic UUIDv7 for a prefixed KSUID (ses_..., evt_...): the KSUID's
48
+ # own time, then SHA-256 bits of the whole id. An id that is not a KSUID takes
49
+ # its time from the hash too, so the same input always gives the same UUID.
50
+ sig { params(prefixed_id: String).returns(String) }
51
+ def uuid_v7(prefixed_id)
52
+ hash = Digest::SHA256.digest(prefixed_id).bytes
53
+ millis = ksuid_millis(prefixed_id.sub(/\A[a-z]+_/, "")) ||
54
+ T.must(hash[10, 6]).inject(0) { |sum, byte| (sum << 8) | byte }
55
+
56
+ bytes = [millis].pack("Q>").bytes.drop(2)
57
+ bytes << (0x70 | (T.must(hash[0]) & 0x0f)) << T.must(hash[1])
58
+ bytes << (0x80 | (T.must(hash[2]) & 0x3f))
59
+ bytes.concat(T.must(hash[3, 7]))
60
+ hex = bytes.pack("C*").unpack1("H*")
61
+ [hex[0, 8], hex[8, 4], hex[12, 4], hex[16, 4], hex[20, 12]].join("-")
62
+ end
63
+
64
+ private
65
+
66
+ # The KSUID's time in Unix milliseconds, or nil where TS's `KSUID.parse` throws.
67
+ sig { params(body: String).returns(T.nilable(Integer)) }
68
+ def ksuid_millis(body)
69
+ return nil unless KSUID_BODY.match?(body)
70
+
71
+ value = body.each_char.inject(0) { |sum, char| (sum * 62) + T.must(BASE62.index(char)) }
72
+ return nil if value >= (1 << 160)
73
+
74
+ ((value >> 128) + KSUID_EPOCH) * 1000
75
+ end
76
+ end
77
+ end
78
+ end
79
+ end
@@ -0,0 +1,108 @@
1
+ # typed: true
2
+
3
+ require_relative "log"
4
+ require_relative "exporters/base"
5
+ require_relative "exporters/datadog"
6
+ require_relative "exporters/otlp"
7
+ require_relative "exporters/posthog"
8
+ require_relative "exporters/sentry"
9
+
10
+ module AgentCat
11
+ # Optional telemetry forwarding, configured via Options#exporters. Runs on the
12
+ # queue's worker thread so an exporter never blocks a tool call, and one raising
13
+ # doesn't stop the rest from running.
14
+ #
15
+ # Works fine with project_id: nil — that's the case where you just want telemetry
16
+ # forwarded somewhere and don't want AgentCat's own API involved at all.
17
+ module Exporters
18
+ extend T::Sig
19
+
20
+ TYPES = T.let({"otlp" => Otlp, "datadog" => Datadog, "sentry" => Sentry, "posthog" => PostHog}.freeze, T::Hash[String, T.untyped])
21
+
22
+ # Turns Options#exporters into exporter objects. An entry is an object responding
23
+ # to #export(event) or #call(event), or TS's hash form,
24
+ # `{type: "datadog", api_key: "..."}`: symbol or string keys, snake_case or TS's
25
+ # camelCase (`apiKey`). An unknown type or a hash the exporter can't take logs one
26
+ # ERROR line and is skipped; anything else logs one WARN line and is skipped.
27
+ sig { params(entries: T::Array[T.untyped]).returns(T::Array[T.untyped]) }
28
+ def self.resolve(entries)
29
+ entries.each_with_index.filter_map do |entry, index|
30
+ if entry.is_a?(Hash)
31
+ from_hash(entry, index)
32
+ elsif exporter?(entry)
33
+ entry
34
+ else
35
+ Log.warn("Options#exporters[#{index}] must respond to #export or #call, or be a Hash with a type, got #{entry.class}; it is ignored")
36
+ nil
37
+ end
38
+ end
39
+ end
40
+
41
+ # Anything responding to #export(event) or #call(event). event is fully redacted.
42
+ sig { params(exporters: T::Array[T.untyped], event: UnredactedEvent).void }
43
+ def self.dispatch(exporters, event)
44
+ exporters.each do |exporter|
45
+ dispatch_one(exporter, event)
46
+ end
47
+ end
48
+
49
+ sig { params(entry: T.untyped).returns(T::Boolean) }
50
+ def self.exporter?(entry)
51
+ entry.respond_to?(:export) || entry.respond_to?(:call)
52
+ end
53
+ private_class_method :exporter?
54
+
55
+ sig { params(hash: T::Hash[T.untyped, T.untyped], index: Integer).returns(T.untyped) }
56
+ def self.from_hash(hash, index)
57
+ config = hash.transform_keys(&:to_s)
58
+ type = config.delete("type")
59
+ klass = TYPES[type.to_s] if type.is_a?(String) || type.is_a?(Symbol)
60
+ if klass.nil?
61
+ shown = if type.is_a?(String) || type.is_a?(Symbol)
62
+ type.to_s.inspect
63
+ else
64
+ (type.nil? ? "none" : type.class.to_s)
65
+ end
66
+ Log.error("Unknown exporter type: #{shown} in Options#exporters[#{index}] (expected #{TYPES.keys.join(", ")}); it is ignored")
67
+ return nil
68
+ end
69
+
70
+ keywords = {}
71
+ config.each do |key, value|
72
+ name = klass.const_get(:CONFIG_KEYS)[key]
73
+ if name
74
+ keywords[name] = value
75
+ else
76
+ Log.warn("Unknown AgentCat option exporters[#{index}].#{key} ignored")
77
+ end
78
+ end
79
+ klass.new(**keywords)
80
+ rescue => e
81
+ # A value of the wrong type fails the Sorbet sig. Its message can carry the value.
82
+ Log.error("Failed to initialize exporter Options#exporters[#{index}] (#{type}) with #{e.class}; it is ignored")
83
+ AgentCat.logger.debug { "exporter Options#exporters[#{index}] failed: #{e.class}: #{e.message}" }
84
+ nil
85
+ end
86
+ private_class_method :from_hash
87
+
88
+ sig { params(exporter: T.untyped, event: UnredactedEvent).void }
89
+ def self.dispatch_one(exporter, event)
90
+ method = if exporter.respond_to?(:export)
91
+ :export
92
+ elsif exporter.respond_to?(:call)
93
+ :call
94
+ end
95
+ if method.nil?
96
+ Log.warn("exporter #{exporter.class} does not respond to #export or #call; it is ignored")
97
+ return
98
+ end
99
+
100
+ exporter.public_send(method, event)
101
+ rescue => e
102
+ # The message can carry the event or the vendor's response: debug only.
103
+ Log.error("exporter #{exporter.class} failed with #{e.class}; the event was not exported")
104
+ AgentCat.logger.debug { "exporter #{exporter.class} failed: #{e.class}: #{e.message}" }
105
+ end
106
+ private_class_method :dispatch_one
107
+ end
108
+ end
@@ -0,0 +1,30 @@
1
+ # typed: true
2
+
3
+ module AgentCat
4
+ # Puma cluster mode, Unicorn, Passenger, Spring — they all fork, and the event queue's
5
+ # worker threads don't survive it. Without this a forked child just piles up events
6
+ # nobody's draining. Hooks Process._fork (3.1+) instead of monkey-patching Kernel#fork.
7
+ module ForkSafety
8
+ extend T::Sig
9
+
10
+ module Patch
11
+ def _fork
12
+ pid = super
13
+ AgentCat.reset_event_queue_after_fork! if pid == 0
14
+ pid
15
+ end
16
+ end
17
+
18
+ class << self
19
+ extend T::Sig
20
+
21
+ sig { void }
22
+ def install!
23
+ return if @installed
24
+
25
+ @installed = true
26
+ Process.singleton_class.prepend(Patch)
27
+ end
28
+ end
29
+ end
30
+ end