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.
Files changed (51) 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 +98 -0
  5. data/lib/agentcat/adapters/official.rb +277 -0
  6. data/lib/agentcat/client.rb +189 -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 +728 -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 +286 -0
  30. data/lib/agentcat/redaction.rb +176 -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/server_info.rb +280 -0
  36. data/lib/agentcat/session_manager.rb +83 -0
  37. data/lib/agentcat/tags.rb +61 -0
  38. data/lib/agentcat/test_mode.rb +86 -0
  39. data/lib/agentcat/testing.rb +153 -0
  40. data/lib/agentcat/text.rb +68 -0
  41. data/lib/agentcat/token_estimate.rb +98 -0
  42. data/lib/agentcat/tool_call.rb +129 -0
  43. data/lib/agentcat/tool_handle.rb +289 -0
  44. data/lib/agentcat/tracker.rb +204 -0
  45. data/lib/agentcat/truncation.rb +265 -0
  46. data/lib/agentcat/unredacted_event.rb +155 -0
  47. data/lib/agentcat/user_identity.rb +11 -0
  48. data/lib/agentcat/version.rb +2 -2
  49. data/lib/agentcat.rb +393 -21
  50. metadata +194 -16
  51. 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