agentcat 0.0.1 → 1.1.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/LICENSE +2 -11
- data/README.md +265 -20
- data/lib/agentcat/adapters/base.rb +98 -0
- data/lib/agentcat/adapters/official.rb +277 -0
- data/lib/agentcat/client.rb +189 -0
- data/lib/agentcat/clock.rb +16 -0
- data/lib/agentcat/custom_event.rb +215 -0
- data/lib/agentcat/delivery.rb +58 -0
- data/lib/agentcat/diagnostics.rb +434 -0
- data/lib/agentcat/error_capture.rb +117 -0
- data/lib/agentcat/event_id.rb +19 -0
- data/lib/agentcat/event_pipeline.rb +82 -0
- data/lib/agentcat/event_queue.rb +151 -0
- data/lib/agentcat/exporters/base.rb +135 -0
- data/lib/agentcat/exporters/datadog.rb +137 -0
- data/lib/agentcat/exporters/otlp.rb +157 -0
- data/lib/agentcat/exporters/posthog.rb +185 -0
- data/lib/agentcat/exporters/sentry.rb +242 -0
- data/lib/agentcat/exporters/trace_context.rb +79 -0
- data/lib/agentcat/exporters.rb +108 -0
- data/lib/agentcat/fork_safety.rb +30 -0
- data/lib/agentcat/hooks.rb +190 -0
- data/lib/agentcat/http_post.rb +61 -0
- data/lib/agentcat/interceptor.rb +728 -0
- data/lib/agentcat/log.rb +80 -0
- data/lib/agentcat/options.rb +313 -0
- data/lib/agentcat/payload_limits.rb +71 -0
- data/lib/agentcat/private_members.rb +286 -0
- data/lib/agentcat/redaction.rb +176 -0
- data/lib/agentcat/rejected_calls.rb +147 -0
- data/lib/agentcat/request_context.rb +266 -0
- data/lib/agentcat/sanitization.rb +191 -0
- data/lib/agentcat/schema/prompts.rb +44 -0
- data/lib/agentcat/server_info.rb +280 -0
- data/lib/agentcat/session_manager.rb +83 -0
- data/lib/agentcat/tags.rb +61 -0
- data/lib/agentcat/test_mode.rb +86 -0
- data/lib/agentcat/testing.rb +153 -0
- data/lib/agentcat/text.rb +68 -0
- data/lib/agentcat/token_estimate.rb +98 -0
- data/lib/agentcat/tool_call.rb +129 -0
- data/lib/agentcat/tool_handle.rb +289 -0
- data/lib/agentcat/tracker.rb +204 -0
- data/lib/agentcat/truncation.rb +265 -0
- data/lib/agentcat/unredacted_event.rb +155 -0
- data/lib/agentcat/user_identity.rb +11 -0
- data/lib/agentcat/version.rb +2 -2
- data/lib/agentcat.rb +393 -21
- metadata +194 -16
- 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
|