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,82 @@
|
|
|
1
|
+
# typed: true
|
|
2
|
+
|
|
3
|
+
require_relative "redaction"
|
|
4
|
+
require_relative "sanitization"
|
|
5
|
+
require_relative "truncation"
|
|
6
|
+
require_relative "delivery"
|
|
7
|
+
require_relative "exporters"
|
|
8
|
+
|
|
9
|
+
module AgentCat
|
|
10
|
+
# What happens to an event once it's on the queue's worker thread: redact, sanitize,
|
|
11
|
+
# truncate, deliver, export. Shared by tool calls and tracked custom events so the two
|
|
12
|
+
# can't drift apart.
|
|
13
|
+
module EventPipeline
|
|
14
|
+
extend T::Sig
|
|
15
|
+
|
|
16
|
+
# `label` only goes into debug logs, to say which event failed. `redact_strings:
|
|
17
|
+
# false` skips `redact_sensitive_information`: custom events hold only what the
|
|
18
|
+
# customer chose to send, so TS never runs the string hook on them.
|
|
19
|
+
# `redact_event` still runs, as in TS.
|
|
20
|
+
sig { params(event: UnredactedEvent, tracker: Tracker, epoch: Integer, label: String, redact_strings: T::Boolean).void }
|
|
21
|
+
def self.run(event, tracker, epoch:, label:, redact_strings: true)
|
|
22
|
+
options = tracker.options
|
|
23
|
+
|
|
24
|
+
# The hooks get valid UTF-8, so a regex in them can't raise on a binary string.
|
|
25
|
+
Sanitization.scrub_event(event)
|
|
26
|
+
|
|
27
|
+
# Runs here, not before enqueue: matching Go/TS/Python, a slow or uncached redact
|
|
28
|
+
# hook must never add latency to the caller.
|
|
29
|
+
redacted = Redaction.apply_redact_event(event, options)
|
|
30
|
+
return if redacted.nil?
|
|
31
|
+
|
|
32
|
+
event = redact_strings ? Redaction.apply_sensitive_redaction(redacted, options) : redacted
|
|
33
|
+
return if event.nil?
|
|
34
|
+
|
|
35
|
+
normalize(event, label: label)
|
|
36
|
+
return if record_in_fake(event, epoch)
|
|
37
|
+
|
|
38
|
+
# No project id = export-only, skip AgentCat's own API entirely.
|
|
39
|
+
if tracker.project_id
|
|
40
|
+
Delivery.publish(
|
|
41
|
+
options.client,
|
|
42
|
+
event.to_wire_hash,
|
|
43
|
+
max_retries: options.max_retries,
|
|
44
|
+
base_delay: options.retry_base_delay,
|
|
45
|
+
epoch: epoch
|
|
46
|
+
)
|
|
47
|
+
end
|
|
48
|
+
Exporters.dispatch(options.exporters, event)
|
|
49
|
+
end
|
|
50
|
+
|
|
51
|
+
# `AgentCat.fake`: the event goes to the fake (as it would be sent) instead of
|
|
52
|
+
# AgentCat and the exporters. Returns whether it did. An event from before a
|
|
53
|
+
# `reset!` is dropped, like Delivery does.
|
|
54
|
+
sig { params(event: UnredactedEvent, epoch: Integer).returns(T::Boolean) }
|
|
55
|
+
def self.record_in_fake(event, epoch)
|
|
56
|
+
fake = AgentCat.active_fake
|
|
57
|
+
return false if fake.nil?
|
|
58
|
+
|
|
59
|
+
fake.record(event.to_wire_hash) if epoch == AgentCat.event_epoch
|
|
60
|
+
true
|
|
61
|
+
end
|
|
62
|
+
|
|
63
|
+
# Fail open like Go/Python: a bug in either step delivers the event as-is rather
|
|
64
|
+
# than dropping it. The UTF-8 scrub runs first and on its own (it never raises), so
|
|
65
|
+
# even then every string encodes as JSON. It runs again here because a hook can put
|
|
66
|
+
# new strings on the event, and untracked custom events come here without `run`.
|
|
67
|
+
sig { params(event: UnredactedEvent, label: String).void }
|
|
68
|
+
def self.normalize(event, label:)
|
|
69
|
+
Sanitization.scrub_event(event)
|
|
70
|
+
sanitize_and_truncate(event, label: label)
|
|
71
|
+
end
|
|
72
|
+
|
|
73
|
+
sig { params(event: UnredactedEvent, label: String).void }
|
|
74
|
+
def self.sanitize_and_truncate(event, label:)
|
|
75
|
+
Sanitization.sanitize_event(event)
|
|
76
|
+
Truncation.truncate_event(event)
|
|
77
|
+
rescue => e
|
|
78
|
+
Log.warn("sanitizing or truncating #{label} failed with #{e.class}; the event goes out as it is")
|
|
79
|
+
AgentCat.logger.debug { "sanitization/truncation failed for #{label}: #{e.class}: #{e.message}" }
|
|
80
|
+
end
|
|
81
|
+
end
|
|
82
|
+
end
|
|
@@ -0,0 +1,151 @@
|
|
|
1
|
+
# typed: strict
|
|
2
|
+
|
|
3
|
+
module AgentCat
|
|
4
|
+
# Bounded, drop-oldest job queue with a small lazily-spawned worker pool. Plain Array
|
|
5
|
+
# + Mutex instead of SizedQueue on purpose: SizedQueue blocks the caller once full,
|
|
6
|
+
# and we'd rather drop the oldest job than stall whoever's enqueueing.
|
|
7
|
+
class EventQueue
|
|
8
|
+
extend T::Sig
|
|
9
|
+
|
|
10
|
+
DEFAULT_MAX_SIZE = 10_000
|
|
11
|
+
DEFAULT_WORKER_COUNT = 1
|
|
12
|
+
|
|
13
|
+
sig { params(max_size: Integer, worker_count: Integer).void }
|
|
14
|
+
def initialize(max_size: DEFAULT_MAX_SIZE, worker_count: DEFAULT_WORKER_COUNT)
|
|
15
|
+
@max_size = max_size
|
|
16
|
+
@worker_count = worker_count
|
|
17
|
+
@mutex = T.let(Mutex.new, Mutex)
|
|
18
|
+
@not_empty = T.let(ConditionVariable.new, ConditionVariable)
|
|
19
|
+
@buffer = T.let([], T::Array[T.proc.void])
|
|
20
|
+
@workers = T.let([], T::Array[Thread])
|
|
21
|
+
@in_flight = T.let(0, Integer)
|
|
22
|
+
@stopped = T.let(false, T::Boolean)
|
|
23
|
+
@pid = T.let(Process.pid, Integer)
|
|
24
|
+
end
|
|
25
|
+
|
|
26
|
+
# Used by AgentCat.reset! so a stale queue can't deliver into post-reset state.
|
|
27
|
+
# A job already in flight keeps running — Delivery checks the reset epoch itself.
|
|
28
|
+
sig { void }
|
|
29
|
+
def shutdown
|
|
30
|
+
@mutex.synchronize do
|
|
31
|
+
@stopped = true
|
|
32
|
+
@buffer.clear
|
|
33
|
+
@not_empty.broadcast
|
|
34
|
+
@workers = []
|
|
35
|
+
end
|
|
36
|
+
end
|
|
37
|
+
|
|
38
|
+
# Runs `job` on a worker thread later. Never raises into the caller. A no-op after
|
|
39
|
+
# `shutdown` - without this check, a worker spawned here would see `@stopped` already
|
|
40
|
+
# true and exit immediately, leaving the job buffered forever with nothing left alive
|
|
41
|
+
# to drain it.
|
|
42
|
+
sig { params(job: T.proc.void).void }
|
|
43
|
+
def enqueue(&job)
|
|
44
|
+
return if stopped?
|
|
45
|
+
|
|
46
|
+
spawn_workers_if_needed
|
|
47
|
+
dropped = @mutex.synchronize do
|
|
48
|
+
return if @stopped
|
|
49
|
+
|
|
50
|
+
count = 0
|
|
51
|
+
while @buffer.size >= @max_size
|
|
52
|
+
@buffer.shift
|
|
53
|
+
count += 1
|
|
54
|
+
end
|
|
55
|
+
@buffer.push(job)
|
|
56
|
+
@not_empty.signal
|
|
57
|
+
count
|
|
58
|
+
end
|
|
59
|
+
Log.error("event queue is full (#{@max_size} events); dropped the oldest event") if dropped.positive?
|
|
60
|
+
end
|
|
61
|
+
|
|
62
|
+
sig { returns(Integer) }
|
|
63
|
+
def size
|
|
64
|
+
@mutex.synchronize { @buffer.size }
|
|
65
|
+
end
|
|
66
|
+
|
|
67
|
+
# Waits up to `timeout` seconds for the queue to drain. Returns whether it did.
|
|
68
|
+
sig { params(timeout: Numeric).returns(T::Boolean) }
|
|
69
|
+
def flush(timeout: 5)
|
|
70
|
+
deadline = Clock.monotonic_now + timeout.to_f
|
|
71
|
+
loop do
|
|
72
|
+
return true if idle?
|
|
73
|
+
return false if Clock.monotonic_now >= deadline
|
|
74
|
+
|
|
75
|
+
sleep 0.01
|
|
76
|
+
end
|
|
77
|
+
end
|
|
78
|
+
|
|
79
|
+
# A forked child doesn't inherit the parent's worker threads, so anything queued
|
|
80
|
+
# would just sit there. Called from the Process._fork hook — see ForkSafety.
|
|
81
|
+
sig { void }
|
|
82
|
+
def reset_after_fork!
|
|
83
|
+
@mutex.synchronize do
|
|
84
|
+
@buffer = []
|
|
85
|
+
@workers = []
|
|
86
|
+
@in_flight = 0
|
|
87
|
+
@stopped = false
|
|
88
|
+
@pid = Process.pid
|
|
89
|
+
end
|
|
90
|
+
end
|
|
91
|
+
|
|
92
|
+
private
|
|
93
|
+
|
|
94
|
+
sig { returns(T::Boolean) }
|
|
95
|
+
def idle?
|
|
96
|
+
@mutex.synchronize { @buffer.empty? && @in_flight.zero? }
|
|
97
|
+
end
|
|
98
|
+
|
|
99
|
+
sig { void }
|
|
100
|
+
def spawn_workers_if_needed
|
|
101
|
+
reset_after_fork! if @pid != Process.pid
|
|
102
|
+
return if workers_alive?
|
|
103
|
+
|
|
104
|
+
@mutex.synchronize do
|
|
105
|
+
next if workers_alive?
|
|
106
|
+
|
|
107
|
+
@workers = Array.new(@worker_count) { spawn_worker }
|
|
108
|
+
end
|
|
109
|
+
end
|
|
110
|
+
|
|
111
|
+
sig { returns(T::Boolean) }
|
|
112
|
+
def workers_alive?
|
|
113
|
+
@workers.any? { |worker| worker.alive? }
|
|
114
|
+
end
|
|
115
|
+
|
|
116
|
+
sig { returns(Thread) }
|
|
117
|
+
def spawn_worker
|
|
118
|
+
Thread.new do
|
|
119
|
+
until stopped?
|
|
120
|
+
job = take_job
|
|
121
|
+
next unless job
|
|
122
|
+
|
|
123
|
+
begin
|
|
124
|
+
job.call
|
|
125
|
+
rescue => e
|
|
126
|
+
Log.error("queued event job raised #{e.class}; its event is lost")
|
|
127
|
+
AgentCat.logger.debug { "queued job raised: #{e.class}: #{e.message}" }
|
|
128
|
+
ensure
|
|
129
|
+
@mutex.synchronize { @in_flight -= 1 }
|
|
130
|
+
end
|
|
131
|
+
end
|
|
132
|
+
end
|
|
133
|
+
end
|
|
134
|
+
|
|
135
|
+
sig { returns(T.nilable(T.proc.void)) }
|
|
136
|
+
def take_job
|
|
137
|
+
@mutex.synchronize do
|
|
138
|
+
@not_empty.wait(@mutex) while @buffer.empty? && !@stopped
|
|
139
|
+
return nil if @stopped
|
|
140
|
+
|
|
141
|
+
@in_flight += 1
|
|
142
|
+
@buffer.shift
|
|
143
|
+
end
|
|
144
|
+
end
|
|
145
|
+
|
|
146
|
+
sig { returns(T::Boolean) }
|
|
147
|
+
def stopped?
|
|
148
|
+
@mutex.synchronize { @stopped }
|
|
149
|
+
end
|
|
150
|
+
end
|
|
151
|
+
end
|
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
# typed: true
|
|
2
|
+
|
|
3
|
+
require "json"
|
|
4
|
+
require "time"
|
|
5
|
+
require_relative "../http_post"
|
|
6
|
+
require_relative "trace_context"
|
|
7
|
+
|
|
8
|
+
module AgentCat
|
|
9
|
+
module Exporters
|
|
10
|
+
# Base class for forwarding events to a third-party telemetry store. Subclass and
|
|
11
|
+
# implement #export!. By the time you get the event it's already redacted — it
|
|
12
|
+
# carries exactly what's allowed to leave the process. If your exporter raises,
|
|
13
|
+
# Exporters.dispatch catches and logs it; it costs you this event, not the call.
|
|
14
|
+
#
|
|
15
|
+
# #http_post is the default sender for HTTP-based exporters. Swap it out (override,
|
|
16
|
+
# or pass http_post: to the initializer) for tests or to route through a proxy.
|
|
17
|
+
#
|
|
18
|
+
# An exporter that can't work (no api_key, a DSN it can't parse) doesn't raise from
|
|
19
|
+
# its initializer: it logs one ERROR line, keeps the reason in
|
|
20
|
+
# #setup_error and exports nothing.
|
|
21
|
+
class Base
|
|
22
|
+
extend T::Sig
|
|
23
|
+
|
|
24
|
+
# TS's fetch has no timeout at all. These timeouts are shorter: a
|
|
25
|
+
# dead vendor holds the queue's worker at most this long per request.
|
|
26
|
+
OPEN_TIMEOUT = 2
|
|
27
|
+
TOTAL_TIMEOUT = 10
|
|
28
|
+
|
|
29
|
+
# TS's `AGENTCAT_SOURCE` (src/modules/constants.ts).
|
|
30
|
+
SOURCE = "agentcat"
|
|
31
|
+
TOOLS_CALL = "mcp:tools/call"
|
|
32
|
+
|
|
33
|
+
# Why this exporter is off, or nil when it works.
|
|
34
|
+
sig { returns(T.nilable(String)) }
|
|
35
|
+
attr_reader :setup_error
|
|
36
|
+
|
|
37
|
+
sig { params(event: UnredactedEvent).void }
|
|
38
|
+
def export(event)
|
|
39
|
+
return if @setup_error
|
|
40
|
+
|
|
41
|
+
export!(event)
|
|
42
|
+
end
|
|
43
|
+
|
|
44
|
+
# Implement in subclasses. `event` is an already-redacted UnredactedEvent.
|
|
45
|
+
sig { params(event: UnredactedEvent).void }
|
|
46
|
+
def export!(event)
|
|
47
|
+
raise NotImplementedError, "#{self.class} must implement #export!"
|
|
48
|
+
end
|
|
49
|
+
|
|
50
|
+
# Returns [status, response_body]. A non-2xx status isn't an exception here —
|
|
51
|
+
# that's the caller's call. No User-Agent of our own: TS sets none either.
|
|
52
|
+
sig { params(url: String, headers: T::Hash[String, String], body: String).returns([Integer, String]) }
|
|
53
|
+
def http_post(url, headers, body)
|
|
54
|
+
HttpPost.call(url, headers, body, open_timeout: OPEN_TIMEOUT, read_timeout: TOTAL_TIMEOUT, deadline: TOTAL_TIMEOUT)
|
|
55
|
+
end
|
|
56
|
+
|
|
57
|
+
private
|
|
58
|
+
|
|
59
|
+
# Every HTTP exporter's initializer takes http_post: for this reason.
|
|
60
|
+
sig { params(http_post: T.untyped).returns(T.untyped) }
|
|
61
|
+
def resolve_http_post(http_post)
|
|
62
|
+
http_post || method(:http_post)
|
|
63
|
+
end
|
|
64
|
+
|
|
65
|
+
sig { params(exporter_name: String, url: String, headers: T::Hash[String, String], payload: T.untyped).void }
|
|
66
|
+
def post_json!(exporter_name, url, headers, payload)
|
|
67
|
+
post!(exporter_name, url, headers, payload.to_json)
|
|
68
|
+
end
|
|
69
|
+
|
|
70
|
+
sig { params(exporter_name: String, url: String, headers: T::Hash[String, String], body: String).void }
|
|
71
|
+
def post!(exporter_name, url, headers, body)
|
|
72
|
+
status, response = T.unsafe(@http_post).call(url, headers, body)
|
|
73
|
+
raise "#{exporter_name} returned HTTP #{status}: #{response}" unless status.between?(200, 299)
|
|
74
|
+
end
|
|
75
|
+
|
|
76
|
+
# Turns the exporter off. Call it from the initializer, instead of raising.
|
|
77
|
+
sig { params(reason: String).void }
|
|
78
|
+
def setup_failed!(reason)
|
|
79
|
+
@setup_error = T.let(reason, T.nilable(String))
|
|
80
|
+
AgentCat.logger.error("#{reason}. This exporter is off and exports nothing.")
|
|
81
|
+
end
|
|
82
|
+
|
|
83
|
+
sig { params(value: T.untyped).returns(T::Boolean) }
|
|
84
|
+
def blank?(value)
|
|
85
|
+
value.nil? || (value.is_a?(String) && value.strip.empty?)
|
|
86
|
+
end
|
|
87
|
+
|
|
88
|
+
# JavaScript truthiness, for the many `if (event.x)` checks the TS exporters make:
|
|
89
|
+
# nil, false, "" and 0 are false.
|
|
90
|
+
sig { params(value: T.untyped).returns(T::Boolean) }
|
|
91
|
+
def truthy?(value)
|
|
92
|
+
!(value.nil? || value == false || value == "" || (value.is_a?(Numeric) && value.zero?))
|
|
93
|
+
end
|
|
94
|
+
|
|
95
|
+
# The event time in Unix milliseconds, like TS's `event.timestamp.getTime()`.
|
|
96
|
+
sig { params(event: UnredactedEvent).returns(Integer) }
|
|
97
|
+
def event_millis(event)
|
|
98
|
+
(Time.iso8601(event.timestamp).to_r * 1000).floor
|
|
99
|
+
rescue ArgumentError
|
|
100
|
+
(Time.now.to_r * 1000).floor
|
|
101
|
+
end
|
|
102
|
+
|
|
103
|
+
# A JavaScript number in JSON: 1.0 prints as 1, like JSON.stringify.
|
|
104
|
+
sig { params(value: Numeric).returns(Numeric) }
|
|
105
|
+
def js_number(value)
|
|
106
|
+
return value unless value.is_a?(Float) && value.finite?
|
|
107
|
+
|
|
108
|
+
(value % 1).zero? ? value.to_i : value
|
|
109
|
+
end
|
|
110
|
+
|
|
111
|
+
sig { params(millis: Integer).returns(String) }
|
|
112
|
+
def iso_millis(millis)
|
|
113
|
+
Time.at(Rational(millis, 1000)).utc.iso8601(3)
|
|
114
|
+
end
|
|
115
|
+
|
|
116
|
+
# TS hands its exporters the event as it goes to AgentCat: the SDK's own tags
|
|
117
|
+
# (agentcat_session_id_source, ...) are in `tags`, so they are here too.
|
|
118
|
+
sig { params(event: UnredactedEvent).returns(T.nilable(T::Hash[String, String])) }
|
|
119
|
+
def wire_tags(event)
|
|
120
|
+
event.to_wire_hash[:tags]
|
|
121
|
+
end
|
|
122
|
+
|
|
123
|
+
sig { params(event: UnredactedEvent).returns(T.nilable(T::Hash[String, T.untyped])) }
|
|
124
|
+
def wire_properties(event)
|
|
125
|
+
event.to_wire_hash[:properties]
|
|
126
|
+
end
|
|
127
|
+
|
|
128
|
+
sig { params(event: UnredactedEvent).returns(T.nilable(String)) }
|
|
129
|
+
def session_id(event)
|
|
130
|
+
id = event.session_id
|
|
131
|
+
(id.nil? || id.empty?) ? nil : id
|
|
132
|
+
end
|
|
133
|
+
end
|
|
134
|
+
end
|
|
135
|
+
end
|
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
# typed: true
|
|
2
|
+
|
|
3
|
+
module AgentCat
|
|
4
|
+
module Exporters
|
|
5
|
+
# Sends each event to Datadog as one log (logs intake v2) and a few metrics
|
|
6
|
+
# (series v1), like TS's src/modules/exporters/datadog.ts. Plain Net::HTTP, no
|
|
7
|
+
# extra gem.
|
|
8
|
+
#
|
|
9
|
+
# AgentCat.track(server, project_id, AgentCat::Options.new(
|
|
10
|
+
# exporters: [AgentCat::Exporters::Datadog.new(api_key: ENV["DD_API_KEY"], site: "datadoghq.com", service: "my-mcp-server")]
|
|
11
|
+
# ))
|
|
12
|
+
#
|
|
13
|
+
# Keys (TS names in snake_case): api_key, site, service (all required, like TS)
|
|
14
|
+
# and env. Ruby only: http_post.
|
|
15
|
+
class Datadog < Base
|
|
16
|
+
extend T::Sig
|
|
17
|
+
|
|
18
|
+
# Hash-form keys, TS camelCase and Ruby snake_case, to initializer keywords.
|
|
19
|
+
CONFIG_KEYS = {
|
|
20
|
+
"api_key" => :api_key, "apiKey" => :api_key, "site" => :site, "service" => :service,
|
|
21
|
+
"env" => :env, "http_post" => :http_post
|
|
22
|
+
}.freeze
|
|
23
|
+
|
|
24
|
+
sig { returns(T.nilable(String)) }
|
|
25
|
+
attr_reader :logs_url, :metrics_url
|
|
26
|
+
|
|
27
|
+
sig do
|
|
28
|
+
params(
|
|
29
|
+
api_key: T.nilable(String),
|
|
30
|
+
site: T.nilable(String),
|
|
31
|
+
service: T.nilable(String),
|
|
32
|
+
env: T.nilable(String),
|
|
33
|
+
http_post: T.untyped
|
|
34
|
+
).void
|
|
35
|
+
end
|
|
36
|
+
def initialize(api_key: nil, site: nil, service: nil, env: nil, http_post: nil)
|
|
37
|
+
missing = {"api_key" => api_key, "site" => site, "service" => service}.select { |_, value| blank?(value) }.keys
|
|
38
|
+
unless missing.empty?
|
|
39
|
+
setup_failed!("Datadog exporter needs #{missing.join(", ")}")
|
|
40
|
+
return
|
|
41
|
+
end
|
|
42
|
+
|
|
43
|
+
@api_key = T.must(api_key)
|
|
44
|
+
@service = T.must(service)
|
|
45
|
+
@env = env
|
|
46
|
+
# TS datadog.ts:64-66: "https://datadoghq.eu/" and "datadoghq.eu" are the same site.
|
|
47
|
+
host = T.must(site).sub(%r{\Ahttps?://}, "").sub(%r{/\z}, "")
|
|
48
|
+
@logs_url = T.let("https://http-intake.logs.#{host}/api/v2/logs", T.nilable(String))
|
|
49
|
+
@metrics_url = T.let("https://api.#{host}/api/v1/series", T.nilable(String))
|
|
50
|
+
@http_post = resolve_http_post(http_post)
|
|
51
|
+
end
|
|
52
|
+
|
|
53
|
+
# Both requests go out even when one fails, like TS; a failure then raises so
|
|
54
|
+
# Exporters.dispatch logs it.
|
|
55
|
+
sig { params(event: UnredactedEvent).void }
|
|
56
|
+
def export!(event)
|
|
57
|
+
failures = T.let([], T::Array[StandardError])
|
|
58
|
+
[[T.must(@logs_url), [log(event)]], [T.must(@metrics_url), {series: metrics(event)}]].each do |url, payload|
|
|
59
|
+
post_json!("Datadog", url, headers, payload)
|
|
60
|
+
rescue => e
|
|
61
|
+
failures << e
|
|
62
|
+
end
|
|
63
|
+
raise T.must(failures.first) unless failures.empty?
|
|
64
|
+
end
|
|
65
|
+
|
|
66
|
+
private
|
|
67
|
+
|
|
68
|
+
sig { returns(T::Hash[String, String]) }
|
|
69
|
+
def headers
|
|
70
|
+
{"DD-API-KEY" => @api_key, "Content-Type" => "application/json"}
|
|
71
|
+
end
|
|
72
|
+
|
|
73
|
+
sig { params(event: UnredactedEvent).returns(T::Array[String]) }
|
|
74
|
+
def common_tags(event)
|
|
75
|
+
tags = []
|
|
76
|
+
tags << "env:#{@env}" if truthy?(@env)
|
|
77
|
+
tags << "event_type:#{event.event_type.tr("/", ".")}" if truthy?(event.event_type)
|
|
78
|
+
tags << "resource:#{event.resource_name}" if truthy?(event.resource_name)
|
|
79
|
+
tags
|
|
80
|
+
end
|
|
81
|
+
|
|
82
|
+
# TS datadog.ts:126-189.
|
|
83
|
+
sig { params(event: UnredactedEvent).returns(T::Hash[Symbol, T.untyped]) }
|
|
84
|
+
def log(event)
|
|
85
|
+
tags = common_tags(event)
|
|
86
|
+
tags << "error:true" if event.is_error
|
|
87
|
+
tags << "source:#{SOURCE}"
|
|
88
|
+
customer_tags = wire_tags(event)
|
|
89
|
+
customer_tags&.each do |key, value|
|
|
90
|
+
tags << "agentcat.#{key.downcase.gsub(/[[:space:]:,]+/, "_")}:#{value.tr(",", "_")}"
|
|
91
|
+
end
|
|
92
|
+
|
|
93
|
+
log = {
|
|
94
|
+
message: "#{truthy?(event.event_type) ? event.event_type : "unknown"} - #{truthy?(event.resource_name) ? event.resource_name : "unknown"}",
|
|
95
|
+
service: @service,
|
|
96
|
+
ddsource: SOURCE,
|
|
97
|
+
ddtags: tags.join(","),
|
|
98
|
+
timestamp: event_millis(event),
|
|
99
|
+
status: event.is_error ? "error" : "info",
|
|
100
|
+
dd: {trace_id: TraceContext.datadog_trace_id(session_id(event)), span_id: TraceContext.datadog_span_id(event.id)},
|
|
101
|
+
mcp: {
|
|
102
|
+
session_id: event.session_id,
|
|
103
|
+
event_id: event.id,
|
|
104
|
+
event_type: event.event_type,
|
|
105
|
+
resource: event.resource_name,
|
|
106
|
+
duration_ms: event.duration,
|
|
107
|
+
user_intent: event.user_intent,
|
|
108
|
+
actor_id: event.identify_actor_given_id,
|
|
109
|
+
actor_name: event.identify_actor_name,
|
|
110
|
+
client_name: event.client_name,
|
|
111
|
+
client_version: event.client_version,
|
|
112
|
+
server_name: event.server_name,
|
|
113
|
+
server_version: event.server_version,
|
|
114
|
+
is_error: event.is_error,
|
|
115
|
+
error: event.error,
|
|
116
|
+
tags: customer_tags,
|
|
117
|
+
properties: wire_properties(event)
|
|
118
|
+
}.compact
|
|
119
|
+
}
|
|
120
|
+
log[:error] = {message: event.error.to_json} if event.is_error && event.error
|
|
121
|
+
log
|
|
122
|
+
end
|
|
123
|
+
|
|
124
|
+
# TS datadog.ts:191-233.
|
|
125
|
+
sig { params(event: UnredactedEvent).returns(T::Array[T::Hash[Symbol, T.untyped]]) }
|
|
126
|
+
def metrics(event)
|
|
127
|
+
seconds = event_millis(event).div(1000)
|
|
128
|
+
tags = ["service:#{@service}"] + common_tags(event)
|
|
129
|
+
series = T.let([], T::Array[T::Hash[Symbol, T.untyped]])
|
|
130
|
+
series << {metric: "mcp.events.count", type: "count", points: [[seconds, 1]], tags: tags}
|
|
131
|
+
series << {metric: "mcp.event.duration", type: "gauge", points: [[seconds, event.duration]], tags: tags} if truthy?(event.duration)
|
|
132
|
+
series << {metric: "mcp.errors.count", type: "count", points: [[seconds, 1]], tags: tags} if event.is_error
|
|
133
|
+
series
|
|
134
|
+
end
|
|
135
|
+
end
|
|
136
|
+
end
|
|
137
|
+
end
|
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
# typed: true
|
|
2
|
+
|
|
3
|
+
module AgentCat
|
|
4
|
+
module Exporters
|
|
5
|
+
# Posts one span per event to an OpenTelemetry collector as OTLP/HTTP JSON, like
|
|
6
|
+
# TS's src/modules/exporters/otlp.ts. Plain Net::HTTP, no gem. Each event is its
|
|
7
|
+
# own request, so nothing waits in a batch at exit.
|
|
8
|
+
#
|
|
9
|
+
# AgentCat.track(server, project_id, AgentCat::Options.new(
|
|
10
|
+
# exporters: [AgentCat::Exporters::Otlp.new(endpoint: "http://localhost:4318")]
|
|
11
|
+
# ))
|
|
12
|
+
#
|
|
13
|
+
# Keys (TS names in snake_case): endpoint (required; /v1/traces is added when the
|
|
14
|
+
# path does not end with it) and headers. Ruby only: http_post, and tracer: an
|
|
15
|
+
# OpenTelemetry tracer of your own to emit the span through instead of posting it.
|
|
16
|
+
# That tracer's provider owns batching, resource attributes and shutdown.
|
|
17
|
+
class Otlp < Base
|
|
18
|
+
extend T::Sig
|
|
19
|
+
|
|
20
|
+
TRACES_PATH = "/v1/traces"
|
|
21
|
+
SPAN_KIND_SERVER = 2
|
|
22
|
+
STATUS_OK = 1
|
|
23
|
+
STATUS_ERROR = 2
|
|
24
|
+
|
|
25
|
+
CONFIG_KEYS = {
|
|
26
|
+
"endpoint" => :endpoint, "headers" => :headers, "tracer" => :tracer, "http_post" => :http_post
|
|
27
|
+
}.freeze
|
|
28
|
+
|
|
29
|
+
sig { returns(T.nilable(String)) }
|
|
30
|
+
attr_reader :endpoint
|
|
31
|
+
|
|
32
|
+
sig { returns(T::Hash[String, String]) }
|
|
33
|
+
attr_reader :headers
|
|
34
|
+
|
|
35
|
+
sig do
|
|
36
|
+
params(
|
|
37
|
+
endpoint: T.nilable(String),
|
|
38
|
+
headers: T::Hash[T.any(String, Symbol), String],
|
|
39
|
+
tracer: T.untyped,
|
|
40
|
+
http_post: T.untyped
|
|
41
|
+
).void
|
|
42
|
+
end
|
|
43
|
+
def initialize(endpoint: nil, headers: {}, tracer: nil, http_post: nil)
|
|
44
|
+
@headers = T.let({"Content-Type" => "application/json"}.merge(headers.transform_keys(&:to_s)), T::Hash[String, String])
|
|
45
|
+
@tracer = tracer
|
|
46
|
+
return if tracer
|
|
47
|
+
|
|
48
|
+
if blank?(endpoint)
|
|
49
|
+
setup_failed!("OTLP exporter needs an endpoint or a tracer")
|
|
50
|
+
return
|
|
51
|
+
end
|
|
52
|
+
|
|
53
|
+
# TS otlp.ts:18-19: drop trailing slashes, then add /v1/traces unless it is there.
|
|
54
|
+
url = T.must(endpoint).sub(%r{/+\z}, "")
|
|
55
|
+
@endpoint = T.let(url.end_with?(TRACES_PATH) ? url : "#{url}#{TRACES_PATH}", T.nilable(String))
|
|
56
|
+
@http_post = resolve_http_post(http_post)
|
|
57
|
+
end
|
|
58
|
+
|
|
59
|
+
sig { params(event: UnredactedEvent).void }
|
|
60
|
+
def export!(event)
|
|
61
|
+
return emit_through_tracer(event) if @tracer
|
|
62
|
+
|
|
63
|
+
post_json!("OTLP", T.must(@endpoint), @headers, request(event))
|
|
64
|
+
end
|
|
65
|
+
|
|
66
|
+
private
|
|
67
|
+
|
|
68
|
+
# TS otlp.ts:33-59: service.name is the MCP server's name.
|
|
69
|
+
sig { params(event: UnredactedEvent).returns(T::Hash[Symbol, T.untyped]) }
|
|
70
|
+
def request(event)
|
|
71
|
+
{
|
|
72
|
+
resourceSpans: [{
|
|
73
|
+
resource: {
|
|
74
|
+
attributes: [
|
|
75
|
+
{key: "service.name", value: {stringValue: truthy?(event.server_name) ? event.server_name : "mcp-server"}},
|
|
76
|
+
{key: "service.version", value: {stringValue: truthy?(event.server_version) ? event.server_version : "unknown"}}
|
|
77
|
+
]
|
|
78
|
+
},
|
|
79
|
+
scopeSpans: [{
|
|
80
|
+
scope: {name: SOURCE, version: truthy?(event.agentcat_version) ? event.agentcat_version : "unknown"},
|
|
81
|
+
spans: [span(event)]
|
|
82
|
+
}]
|
|
83
|
+
}]
|
|
84
|
+
}
|
|
85
|
+
end
|
|
86
|
+
|
|
87
|
+
# TS otlp.ts:83-159.
|
|
88
|
+
sig { params(event: UnredactedEvent).returns(T::Hash[Symbol, T.untyped]) }
|
|
89
|
+
def span(event)
|
|
90
|
+
start = event_millis(event) * 1_000_000
|
|
91
|
+
finish = truthy?(event.duration) ? start + (event.duration * 1_000_000) : start
|
|
92
|
+
{
|
|
93
|
+
traceId: TraceContext.trace_id(session_id(event)),
|
|
94
|
+
spanId: TraceContext.span_id(event.id),
|
|
95
|
+
name: span_name(event),
|
|
96
|
+
kind: SPAN_KIND_SERVER,
|
|
97
|
+
startTimeUnixNano: start.to_s,
|
|
98
|
+
endTimeUnixNano: finish.to_s,
|
|
99
|
+
attributes: attributes(event).map { |key, value| {key: key, value: {stringValue: value}} },
|
|
100
|
+
status: {code: event.is_error ? STATUS_ERROR : STATUS_OK}
|
|
101
|
+
}
|
|
102
|
+
end
|
|
103
|
+
|
|
104
|
+
sig { params(event: UnredactedEvent).returns(String) }
|
|
105
|
+
def span_name(event)
|
|
106
|
+
truthy?(event.event_type) ? event.event_type : "mcp.event"
|
|
107
|
+
end
|
|
108
|
+
|
|
109
|
+
# String attributes in TS's order; empty ones are left out, like TS.
|
|
110
|
+
sig { params(event: UnredactedEvent).returns(T::Hash[String, String]) }
|
|
111
|
+
def attributes(event)
|
|
112
|
+
attributes = {
|
|
113
|
+
"source" => SOURCE,
|
|
114
|
+
"mcp.event_type" => event.event_type,
|
|
115
|
+
"mcp.session_id" => event.session_id,
|
|
116
|
+
"mcp.project_id" => event.project_id,
|
|
117
|
+
"mcp.resource_name" => event.resource_name,
|
|
118
|
+
"mcp.user_intent" => event.user_intent,
|
|
119
|
+
"mcp.actor_id" => event.identify_actor_given_id,
|
|
120
|
+
"mcp.actor_name" => event.identify_actor_name,
|
|
121
|
+
"mcp.client_name" => event.client_name,
|
|
122
|
+
"mcp.client_version" => event.client_version
|
|
123
|
+
}
|
|
124
|
+
wire_tags(event)&.each { |key, value| attributes["agentcat.tag.#{key}"] = value }
|
|
125
|
+
properties = wire_properties(event)
|
|
126
|
+
attributes["agentcat.properties"] = properties.to_json if properties
|
|
127
|
+
attributes.select { |_, value| truthy?(value) }
|
|
128
|
+
end
|
|
129
|
+
|
|
130
|
+
# Ruby only: the same span through your own OpenTelemetry tracer.
|
|
131
|
+
sig { params(event: UnredactedEvent).void }
|
|
132
|
+
def emit_through_tracer(event)
|
|
133
|
+
start = Time.at(Rational(event_millis(event), 1000))
|
|
134
|
+
span = T.unsafe(@tracer).start_span(span_name(event), kind: span_kind, attributes: attributes(event), start_timestamp: start)
|
|
135
|
+
if event.is_error
|
|
136
|
+
status = error_status
|
|
137
|
+
status ? (span.status = status) : span.set_attribute("otel.status_code", "ERROR")
|
|
138
|
+
end
|
|
139
|
+
span.finish(end_timestamp: start + (event.duration / 1000.0))
|
|
140
|
+
end
|
|
141
|
+
|
|
142
|
+
sig { returns(T.untyped) }
|
|
143
|
+
def span_kind
|
|
144
|
+
OpenTelemetry::Trace::SpanKind::SERVER
|
|
145
|
+
rescue NameError
|
|
146
|
+
:server
|
|
147
|
+
end
|
|
148
|
+
|
|
149
|
+
sig { returns(T.untyped) }
|
|
150
|
+
def error_status
|
|
151
|
+
OpenTelemetry::Trace::Status.error
|
|
152
|
+
rescue NameError
|
|
153
|
+
nil
|
|
154
|
+
end
|
|
155
|
+
end
|
|
156
|
+
end
|
|
157
|
+
end
|