activeagents-telemetry 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6c38e176c17f5a182fcab038fd6d83d9c4892323e25396233b05c8ba77c4b5fe
+  data.tar.gz: f884e7ee222f1e58d6d839c03d36e8dd8cff4f364850eff485d7f8b99e840899
+SHA512:
+  metadata.gz: c455c628880fa3394dd19cdcb9e332f6a66624c1c85ca786d034ee29b4b20d8c3606c9a328f25a979ca29ed35a93aebe42155bc27666f4cab54feeb4502b5a5d
+  data.tar.gz: c6d2eb0384422271e510528fa363fc5b961b9aceb393e2fe575985fa9326433765e014eda642acd891e75b038f1faf25a1101d74416ef325278e6a458948d020

data/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.1.0] - 2026-08-10
+
+First public release of both gems: `activeagents-telemetry` (the shared
+core) and `activeagents-telemetry-ruby_llm` (the RubyLLM adapter).
+
+### Added
+
+- Feature parity with the ActiveAgent framework's built-in telemetry, so the
+  framework can adopt this gem as a dependency: an `enabled` kill-switch,
+  `load_from_hash` for YAML-driven config, child spans (`Span#add_span`,
+  flattened by `Trace#to_h`), `Span#set_status`/`status_message`/`measure`,
+  `BatchingReporter` (buffered delivery with `batch_size`/`flush_interval`),
+  and a pluggable `local_store` for in-process persistence without HTTP.
+- Attribute redaction is now actually applied at delivery: span attribute
+  keys matching `redact_attributes` (by dot-separated segment) are scrubbed.
+  The framework's previous implementation declared the option but never
+  enforced it.
+
+- `activeagents-telemetry` — shared core extracted from the ActiveAgent gem's
+  telemetry and the RubyLLM adapter: `Configuration`, `Span`, `Trace`, and
+  `Reporter`, which together own the `POST /v1/traces` wire format.
+- `activeagents-telemetry-ruby_llm` — the RubyLLM adapter, moved out of the
+  activeagents monorepo (`ruby_llm_telemetry/`) and ported onto the shared core.
+
+### Changed
+
+- The adapter's namespace moved from `ActiveAgents::RubyLLMTelemetry` to
+  `ActiveAgents::Telemetry::RubyLLM`, and the gem name from
+  `active_agents-ruby_llm_telemetry` to `activeagents-telemetry-ruby_llm`. The
+  predecessor was never published to RubyGems, so there is no upgrade path to
+  maintain.
+- `subscribe!` now inherits its destination from
+  `ActiveAgents::Telemetry.configuration` when arguments are omitted, so an app
+  configures the endpoint once for every adapter.
+- Errors are reported through `Span#record_error`, which truncates the message
+  and never transmits a backtrace.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 ActiveAgents
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,74 @@
+# activeagents-telemetry
+
+LLM tracing for Ruby apps. Reports what your app asked the model, how long it
+took, what it cost in tokens, and which tools ran — to the
+[ActiveAgents](https://activeagents.ai) platform or any self-hosted ActiveAgent
+dashboard.
+
+**[Configuration guide → the wiki](https://github.com/activeagents/activeagents-telemetry/wiki)**
+
+## Gems in this repo
+
+| Gem | Use it when |
+|-----|-------------|
+| `activeagents-telemetry` | Shared core — wire format, configuration, delivery. Every adapter depends on it. |
+| `activeagents-telemetry-ruby_llm` | Your app calls models through [RubyLLM](https://github.com/crmne/ruby_llm). |
+
+Apps built on the [ActiveAgent](https://github.com/activeagents/activeagent)
+framework don't need an adapter — the framework reports telemetry on its own.
+
+## Quick start
+
+```ruby
+# Gemfile
+gem "activeagents-telemetry-ruby_llm"
+```
+
+```ruby
+# config/initializers/telemetry.rb
+RubyLLM.configure do |config|
+  config.instrumenter = ActiveSupport::Notifications # RubyLLM 1.x; 2.x wires this up in Rails
+end
+
+ActiveAgents::Telemetry.configure do |config|
+  config.api_key      = ENV["ACTIVEAGENTS_API_KEY"]
+  config.service_name = "my-app"
+end
+
+ActiveAgents::Telemetry::RubyLLM.subscribe!
+```
+
+That's it. Every chat turn now reports as a trace.
+
+## What a trace looks like
+
+One trace per conversation turn:
+
+```
+root   SupportBot.respond              1,240ms   OK
+└─ llm llm.generate    gpt-4o  2 rounds  1,180ms  42 tokens
+   └─ tool tool.search_docs               310ms   OK
+```
+
+Tool arguments and results are never sent. Error messages are truncated and
+backtraces are never transmitted.
+
+## Self-hosting
+
+Point the endpoint at your mounted dashboard — same gems, same wire format:
+
+```ruby
+config.endpoint = "https://your-app.example.com/active_agent/api/traces"
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rake test_all   # core + every adapter
+bundle exec rake build_all  # build all gems into pkg/
+```
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt).

data/lib/activeagents/telemetry/batching_reporter.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module ActiveAgents
+  module Telemetry
+    # A Reporter that buffers traces and delivers them in batches — fewer
+    # HTTP requests under sustained traffic, at the cost of traces arriving
+    # up to flush_interval seconds late.
+    #
+    # A full buffer (configuration.batch_size) flushes immediately; a
+    # background thread flushes whatever accumulated every
+    # configuration.flush_interval seconds. Call #shutdown before process
+    # exit or the tail of the buffer is lost.
+    #
+    # Sampling happens on enqueue, so a dropped trace never occupies buffer
+    # space; enabled?/configured? are also checked on enqueue AND inherited
+    # from Reporter#report at delivery time.
+    class BatchingReporter < Reporter
+      def initialize(configuration, **options)
+        super
+        @buffer = []
+        @mutex = Mutex.new
+        @flusher = nil
+        @send_threads = []
+        @shutdown = false
+      end
+
+      # Enqueues a trace, flushing if the batch is full.
+      def report(traces)
+        return if @shutdown
+
+        accepted = normalize(traces).select { sample_trace? }
+        return if accepted.empty?
+        return unless configuration.enabled? && configuration.configured?
+
+        batch = nil
+        @mutex.synchronize do
+          @buffer.concat(accepted)
+          batch = @buffer.slice!(0..) if @buffer.size >= configuration.batch_size
+          start_flusher
+        end
+        deliver_batch(batch) if batch
+        nil
+      end
+
+      # Delivers everything buffered, blocking until done.
+      def flush
+        batch = @mutex.synchronize { @buffer.slice!(0..) }
+        deliver_batch(batch, blocking: true) unless batch.empty?
+        nil
+      end
+
+      # Flushes, waits out in-flight sends, and stops the background thread —
+      # traces reported just before process exit are delivered, not dropped.
+      # Idempotent.
+      def shutdown
+        @shutdown = true
+        flush
+        @mutex.synchronize { @send_threads.dup }.each { |thread| thread.join(configuration.timeout) }
+        @flusher&.kill
+        @flusher = nil
+      end
+
+      private
+
+      def deliver_batch(batch, blocking: false)
+        body = payload_for(batch)
+        return deliver(body) if blocking || !configuration.async?
+
+        thread = Thread.new { deliver(body) }
+        @mutex.synchronize do
+          @send_threads.select!(&:alive?)
+          @send_threads << thread
+        end
+        thread
+      rescue StandardError => e
+        log("failed to build trace payload: #{e.class}: #{e.message}")
+      end
+
+      # Lazily started so a reporter constructed at boot in a process that
+      # never traces (a console, a one-off rake task) spawns no thread.
+      def start_flusher
+        return if @flusher&.alive? || @shutdown
+
+        @flusher = Thread.new do
+          Thread.current.name = "activeagents-telemetry-flusher"
+          until @shutdown
+            sleep(configuration.flush_interval)
+            flush
+          end
+        end
+      end
+    end
+  end
+end

data/lib/activeagents/telemetry/configuration.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module ActiveAgents
+  module Telemetry
+    # Where traces go and how they get there.
+    #
+    # Every adapter takes one of these, so an app configures the destination
+    # once and each adapter inherits it:
+    #
+    #   ActiveAgents::Telemetry.configure do |config|
+    #     config.api_key      = ENV["ACTIVEAGENTS_API_KEY"]
+    #     config.service_name = "my-app"
+    #     config.environment  = Rails.env
+    #   end
+    #
+    # A self-hosted ActiveAgent dashboard is the same thing with a different
+    # endpoint — point it at "https://your-app.example.com/active_agent/api/traces".
+    class Configuration
+      # The hosted platform. Self-hosters override `endpoint`.
+      DEFAULT_ENDPOINT = "https://api.activeagents.ai/v1/traces"
+
+      # Path a mounted ActiveAgent::Dashboard::Engine serves traces on.
+      LOCAL_ENDPOINT_PATH = "/active_agent/api/traces"
+
+      # Attribute keys scrubbed from spans before delivery. Name-based — a
+      # secret inside free text is not caught; see the wiki's privacy page.
+      DEFAULT_REDACT_ATTRIBUTES = %w[password secret token key credential api_key].freeze
+
+      attr_accessor :endpoint, :api_key, :service_name, :environment,
+                    :resource_attributes, :logger, :timeout, :open_timeout,
+                    :async, :sample_rate, :error_message_limit,
+                    :enabled, :batch_size, :flush_interval,
+                    :capture_bodies, :redact_attributes, :local_store
+
+      def initialize
+        @enabled = true
+        @endpoint = DEFAULT_ENDPOINT
+        @api_key = nil
+        @service_name = nil
+        @environment = nil
+        @resource_attributes = {}
+        @logger = nil
+        @timeout = 10
+        @open_timeout = 10
+        @async = true
+        @sample_rate = 1.0
+        @error_message_limit = 200
+        @batch_size = 100
+        @flush_interval = 5
+        @capture_bodies = false
+        @redact_attributes = DEFAULT_REDACT_ATTRIBUTES.dup
+        @local_store = nil
+      end
+
+      # Traces are only sent when there is somewhere to send them: an endpoint
+      # plus something to authenticate with, or a local store that bypasses
+      # HTTP entirely.
+      def configured?
+        local_store? || (!endpoint.to_s.empty? && !api_key.to_s.empty?)
+      end
+
+      # An explicit kill-switch over and above configured?. Defaults to true —
+      # for adapters, the presence of an api_key remains the effective switch;
+      # frameworks that want opt-in default this to false.
+      def enabled?
+        @enabled == true
+      end
+
+      # A callable (trace_hash, sdk_hash) that persists traces in-process —
+      # the ActiveAgent dashboard wires this to its TelemetryTrace model.
+      def local_store?
+        !@local_store.nil?
+      end
+
+      def capture_bodies?
+        @capture_bodies == true
+      end
+
+      def async?
+        @async == true
+      end
+
+      # Head-based sampling: decided once per trace, at report time.
+      def sample?
+        return true if sample_rate >= 1.0
+        return false if sample_rate <= 0.0
+
+        rand < sample_rate
+      end
+      alias should_sample? sample?
+
+      FLOAT_SETTINGS = %w[sample_rate].freeze
+      INTEGER_SETTINGS = %w[batch_size flush_interval timeout open_timeout error_message_limit].freeze
+
+      # Loads settings from a hash — how config/*.yml files reach here.
+      # Unknown keys are ignored, so a newer config file works on an older
+      # gem; numeric settings are coerced because ERB-interpolated YAML
+      # values arrive as strings.
+      def load_from_hash(hash)
+        (hash || {}).each do |key, value|
+          writer = "#{key}="
+          next unless respond_to?(writer)
+
+          value = value.to_f if FLOAT_SETTINGS.include?(key.to_s)
+          value = value.to_i if INTEGER_SETTINGS.include?(key.to_s)
+          public_send(writer, value)
+        end
+        self
+      end
+
+      # Falls back to the Rails application name, then to a generic label, so
+      # traces are attributable even when the app never sets one.
+      def resolved_service_name
+        @service_name || rails_app_name || "ruby"
+      end
+
+      def resolved_environment
+        @environment || rails_env || ENV.fetch("RACK_ENV", "production")
+      end
+
+      def resolved_logger
+        @logger || rails_logger || Logger.new(File::NULL)
+      end
+
+      def to_h
+        {
+          enabled: enabled,
+          endpoint: endpoint,
+          api_key: api_key ? "[REDACTED]" : nil,
+          service_name: resolved_service_name,
+          environment: resolved_environment,
+          sample_rate: sample_rate,
+          async: async,
+          batch_size: batch_size,
+          flush_interval: flush_interval,
+          capture_bodies: capture_bodies,
+          local_store: local_store? ? "[CALLABLE]" : nil
+        }
+      end
+
+      private
+
+      def rails_app_name
+        return nil unless defined?(Rails) && Rails.application
+
+        Rails.application.class.module_parent_name.underscore
+      rescue StandardError
+        nil
+      end
+
+      def rails_env
+        defined?(Rails) && Rails.respond_to?(:env) ? Rails.env.to_s : nil
+      end
+
+      def rails_logger
+        defined?(Rails) && Rails.respond_to?(:logger) ? Rails.logger : nil
+      end
+    end
+  end
+end

data/lib/activeagents/telemetry/reporter.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+module ActiveAgents
+  module Telemetry
+    # Delivers traces to the configured endpoint.
+    #
+    # Telemetry is never worth breaking an app over, so every failure path here
+    # ends in a log line: a bad endpoint, a down collector, a serialization bug
+    # in an adapter, and a nil api_key all degrade to "no traces" rather than an
+    # exception in the caller's request cycle.
+    #
+    # Delivery is fire-and-forget on a thread by default. Pass `async: false`
+    # for tests, or for scripts short enough that the process may exit before a
+    # background thread flushes.
+    class Reporter
+      SDK_NAME = "activeagents-telemetry"
+
+      attr_reader :configuration
+
+      # @param sdk_name [String] overridden by adapters so ingest can tell
+      #   which integration produced a trace.
+      # @param sample [Boolean] pass false when the caller already applied
+      #   head-based sampling at trace creation — sampling twice compounds
+      #   the rate to rate².
+      def initialize(configuration, sdk_name: SDK_NAME, sdk_version: VERSION, sample: true)
+        @configuration = configuration
+        @sdk_name = sdk_name
+        @sdk_version = sdk_version
+        @sample = sample
+      end
+
+      # @param traces [Trace, Hash, Array<Trace, Hash>] traces to deliver —
+      #   Trace objects or already-serialized trace hashes
+      # @return [void]
+      def report(traces)
+        traces = normalize(traces)
+        return if traces.empty?
+        return unless configuration.enabled? && configuration.configured?
+        return unless sample_trace?
+
+        body = payload_for(traces)
+        configuration.async? ? Thread.new { deliver(body) } : deliver(body)
+        nil
+      rescue StandardError => e
+        log("failed to build trace payload: #{e.class}: #{e.message}")
+        nil
+      end
+
+      # Blocking delivery, for tests and for at-exit flushes.
+      def report_now(traces)
+        traces = normalize(traces)
+        return if traces.empty?
+        return unless configuration.enabled? && configuration.configured?
+
+        deliver(payload_for(traces))
+      end
+
+      private
+
+      # Array() is wrong here: it would explode a raw trace hash into
+      # key/value pairs. Traces arrive as Trace objects or serialized hashes,
+      # singly or in arrays.
+      def normalize(traces)
+        (traces.is_a?(Array) ? traces : [ traces ]).reject { |trace| trace.nil? || (trace.respond_to?(:empty?) && trace.empty?) }
+      end
+
+      # Trace#to_h is already string-keyed; raw hashes may arrive symbol-keyed
+      # and both local stores and ingest read string keys.
+      def serialize(trace)
+        trace.is_a?(Trace) ? trace.to_h : deep_stringify(trace)
+      end
+
+      def deep_stringify(value)
+        case value
+        when Hash then value.each_with_object({}) { |(key, inner), out| out[key.to_s] = deep_stringify(inner) }
+        when Array then value.map { |inner| deep_stringify(inner) }
+        else value
+        end
+      end
+
+      def sample_trace?
+        !@sample || configuration.sample?
+      end
+
+      def payload_for(traces)
+        {
+          "traces" => traces.map { |trace| redact(serialize(trace)) },
+          "sdk" => {
+            "name" => @sdk_name,
+            "version" => @sdk_version,
+            "language" => "ruby",
+            "runtime_version" => RUBY_VERSION
+          }
+        }
+      end
+
+      # Scrubs span attributes whose key matches the configured redaction
+      # list. Matching is by attribute key segment ("api_key", "http.api_key"),
+      # not by value — a secret inside free text is not caught here.
+      def redact(trace_hash)
+        redacted = Array(configuration.redact_attributes).map(&:to_s)
+        return trace_hash if redacted.empty?
+
+        spans = trace_hash["spans"] || trace_hash[:spans] || []
+        spans.each do |span|
+          attributes = span["attributes"] || span[:attributes]
+          next unless attributes.is_a?(Hash)
+
+          attributes.each_key do |key|
+            segments = key.to_s.downcase.split(".")
+            attributes[key] = "[REDACTED]" if segments.any? { |segment| redacted.include?(segment) }
+          end
+        end
+        trace_hash
+      end
+
+      def deliver(body)
+        return deliver_locally(body) if configuration.local_store?
+
+        uri = URI.parse(configuration.endpoint)
+
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = configuration.open_timeout
+        http.read_timeout = configuration.timeout
+
+        request = Net::HTTP::Post.new(uri.request_uri)
+        request["Content-Type"] = "application/json"
+        request["Authorization"] = "Bearer #{configuration.api_key}"
+        request["User-Agent"] = "#{@sdk_name}/#{@sdk_version} Ruby/#{RUBY_VERSION}"
+        request["X-Service-Name"] = configuration.resolved_service_name.to_s
+        request["X-Environment"] = configuration.resolved_environment.to_s
+        request.body = JSON.generate(body)
+
+        response = http.request(request)
+        log("ingest rejected traces: #{response.code} #{response.message}") unless response.is_a?(Net::HTTPSuccess)
+        response
+      rescue StandardError => e
+        log("#{e.class}: #{e.message}")
+        nil
+      end
+
+      # Hands each trace to the configured local store instead of HTTP —
+      # nothing leaves the process. Per-trace rescue: one bad row must not
+      # drop its batch-mates.
+      def deliver_locally(body)
+        body["traces"].each do |trace|
+          configuration.local_store.call(trace, body["sdk"])
+        rescue StandardError => e
+          log("local store failed: #{e.class}: #{e.message}")
+        end
+        nil
+      end
+
+      def log(message)
+        configuration.resolved_logger.error("[ActiveAgents::Telemetry] #{message}")
+      rescue StandardError
+        warn "[ActiveAgents::Telemetry] #{message}"
+      end
+    end
+  end
+end

data/lib/activeagents/telemetry/span.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module ActiveAgents
+  module Telemetry
+    # A single operation inside a trace, serialized to the `/v1/traces` wire
+    # format. Adapters build these rather than hand-rolling hashes, so a span
+    # from the RubyLLM adapter and a span from any future adapter are shaped
+    # identically on the wire.
+    class Span
+      TYPES = %w[root prompt llm tool thinking embedding error].freeze
+
+      OK = "OK"
+      ERROR = "ERROR"
+      UNSET = "UNSET"
+
+      ZERO_TOKENS = { "input" => 0, "output" => 0, "thinking" => 0, "total" => 0 }.freeze
+
+      attr_reader :span_id, :name, :type, :attributes, :events, :children, :status_message
+      attr_accessor :parent_span_id, :start_time, :end_time, :status
+
+      def initialize(name, type:, trace_id: nil, parent_span_id: nil, span_id: nil, attributes: {}, start_time: nil)
+        @span_id = span_id || SecureRandom.hex(8)
+        @trace_id = trace_id
+        @parent_span_id = parent_span_id
+        @name = name.to_s
+        @type = type.to_s
+        @attributes = stringify(attributes)
+        @start_time = start_time || Time.now
+        @end_time = nil
+        @status = UNSET
+        @status_message = nil
+        @tokens = ZERO_TOKENS.dup
+        @events = []
+        @children = []
+      end
+
+      attr_reader :trace_id
+
+      # Stamping a trace_id propagates to children, so a subtree built before
+      # its trace exists still lands in one piece.
+      def trace_id=(value)
+        @trace_id = value
+        @children.each { |child| child.trace_id = value }
+      end
+
+      # Builds a child span sharing this span's trace. Instrumentation that
+      # holds only a span — not the enclosing trace — nests through this;
+      # Trace#to_h flattens the tree back out for the wire.
+      def add_span(name, type: "root", **options)
+        child = Span.new(name, type: type, trace_id: trace_id, parent_span_id: span_id, **options)
+        @children << child
+        child
+      end
+
+      def set_attribute(key, value)
+        @attributes[key.to_s] = value
+        self
+      end
+
+      def set_attributes(attrs)
+        @attributes.merge!(stringify(attrs))
+        self
+      end
+
+      def set_tokens(input: 0, output: 0, thinking: 0)
+        @tokens = {
+          "input" => input.to_i,
+          "output" => output.to_i,
+          "thinking" => thinking.to_i,
+          "total" => input.to_i + output.to_i + thinking.to_i
+        }
+        self
+      end
+
+      def tokens
+        @tokens.dup
+      end
+
+      # Adds another span's token counts to this one — how a turn-level llm
+      # span accumulates the rounds it covers.
+      def add_tokens(other)
+        counts = other.respond_to?(:tokens) ? other.tokens : other
+        @tokens = @tokens.merge(stringify(counts)) { |_key, carried, added| carried.to_i + added.to_i }
+        self
+      end
+
+      def add_event(name, attributes = {})
+        @events << { "name" => name.to_s, "timestamp" => iso8601(Time.now), "attributes" => stringify(attributes) }
+        self
+      end
+
+      # @param code [Symbol, String] :ok, :error, or :unset
+      def set_status(code, message = nil)
+        @status = { ok: OK, error: ERROR, unset: UNSET }.fetch(code.to_s.downcase.to_sym, UNSET)
+        @status_message = message
+        self
+      end
+
+      # Records an error without ever putting a backtrace or an untruncated
+      # message on the wire — telemetry payloads leave the app's trust boundary.
+      def record_error(error, message_limit: 200)
+        @status = ERROR
+        @status_message = truncate(error.message.to_s, message_limit)
+        set_attribute("error.type", error.class.name)
+        set_attribute("error.message", truncate(error.message.to_s, message_limit))
+        self
+      end
+
+      def finish(at: nil)
+        @end_time = at || Time.now
+        @status = OK if @status == UNSET
+        self
+      end
+
+      def finished?
+        !@end_time.nil?
+      end
+
+      def duration_ms
+        return nil unless finished?
+
+        ((@end_time - @start_time) * 1000).round(2)
+      end
+
+      def to_h
+        {
+          "span_id" => span_id,
+          "trace_id" => trace_id,
+          "parent_span_id" => parent_span_id,
+          "name" => name,
+          "type" => type,
+          "start_time" => iso8601(start_time),
+          "end_time" => end_time ? iso8601(end_time) : nil,
+          "duration_ms" => duration_ms,
+          "status" => status,
+          "status_message" => status_message,
+          "attributes" => attributes,
+          "tokens" => tokens,
+          "events" => events
+        }
+      end
+
+      # Runs the block, recording its outcome and timing on the span.
+      def measure
+        result = yield(self)
+        set_status(:ok) if @status == UNSET
+        result
+      rescue StandardError => e
+        record_error(e)
+        raise
+      ensure
+        finish
+      end
+
+      private
+
+      def stringify(hash)
+        (hash || {}).each_with_object({}) { |(key, value), out| out[key.to_s] = value }
+      end
+
+      def truncate(string, limit)
+        string.length > limit ? "#{string[0, limit - 1]}…" : string
+      end
+
+      def iso8601(time)
+        time.utc.strftime("%Y-%m-%dT%H:%M:%S.%6N%:z")
+      end
+    end
+  end
+end

data/lib/activeagents/telemetry/trace.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module ActiveAgents
+  module Telemetry
+    # A collection of spans sharing a trace_id, plus the service metadata the
+    # ingest endpoint keys on. Adapters build one per unit of work — for chat
+    # adapters, one per conversation turn.
+    class Trace
+      attr_reader :trace_id, :spans
+      attr_accessor :service_name, :environment, :resource_attributes
+
+      def initialize(trace_id: nil, service_name: nil, environment: nil, resource_attributes: {})
+        @trace_id = trace_id || SecureRandom.hex(16)
+        @service_name = service_name
+        @environment = environment
+        @resource_attributes = resource_attributes || {}
+        @spans = []
+      end
+
+      # Adopts the span into this trace, stamping the trace_id so adapters
+      # cannot emit a span that belongs to no trace.
+      def add_span(span)
+        span.trace_id = trace_id
+        @spans << span
+        span
+      end
+
+      # Builds and adopts a span in one step.
+      def span(name, type:, parent: nil, **options)
+        add_span(Span.new(name, type: type, parent_span_id: parent&.span_id, **options))
+      end
+
+      def root
+        @spans.find { |span| span.type == "root" }
+      end
+
+      def empty?
+        @spans.empty?
+      end
+
+      def to_h
+        {
+          "trace_id" => trace_id,
+          "service_name" => service_name,
+          "environment" => environment,
+          "timestamp" => timestamp,
+          "resource_attributes" => resource_attributes,
+          "spans" => spans.flat_map { |span| flatten(span) }.map(&:to_h)
+        }
+      end
+
+      private
+
+      # Spans built through Span#add_span nest as children; the wire format is
+      # flat, with parentage carried by parent_span_id.
+      def flatten(span)
+        [ span ] + span.children.flat_map { |child| flatten(child) }
+      end
+
+      # The trace's own end time, so out-of-order delivery still lands the
+      # trace at the moment it actually finished.
+      def timestamp
+        finished = spans.map(&:end_time).compact.max || Time.now
+        finished.utc.strftime("%Y-%m-%dT%H:%M:%S.%6N%:z")
+      end
+    end
+  end
+end

data/lib/activeagents/telemetry/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module ActiveAgents
+  module Telemetry
+    VERSION = "0.1.0"
+  end
+end

data/lib/activeagents/telemetry.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "logger"
+
+require_relative "telemetry/version"
+require_relative "telemetry/configuration"
+require_relative "telemetry/span"
+require_relative "telemetry/trace"
+require_relative "telemetry/reporter"
+require_relative "telemetry/batching_reporter"
+
+# Shared core for reporting LLM traces to ActiveAgents.
+#
+# This gem carries no integration of its own — it owns the wire format, the
+# configuration, and delivery. Install an adapter for whatever your app calls
+# the model through:
+#
+#   gem "activeagents-telemetry-ruby_llm"   # apps built on RubyLLM
+#
+# Configure the destination once and every adapter inherits it:
+#
+#   ActiveAgents::Telemetry.configure do |config|
+#     config.api_key      = ENV["ACTIVEAGENTS_API_KEY"]
+#     config.service_name = "my-app"
+#   end
+module ActiveAgents
+  module Telemetry
+    class << self
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure
+        yield(configuration) if block_given?
+        configuration
+      end
+
+      # Replaces configuration wholesale; mostly useful in tests.
+      attr_writer :configuration
+
+      def reset!
+        @configuration = Configuration.new
+        @reporter = nil
+      end
+
+      def reporter
+        @reporter ||= Reporter.new(configuration)
+      end
+
+      attr_writer :reporter
+
+      def enabled?
+        configuration.configured?
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification
+name: activeagents-telemetry
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- ActiveAgents
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-08-10 00:00:00.000000000 Z
+dependencies: []
+description: |
+  The wire format, configuration, and delivery layer behind ActiveAgents
+  telemetry. Install an adapter for whatever your app calls the model
+  through — activeagents-telemetry-ruby_llm for apps built on RubyLLM —
+  and traces land in the ActiveAgents platform or any self-hosted
+  ActiveAgent dashboard (POST /v1/traces). Nothing beyond stdlib.
+email:
+- hello@activeagents.ai
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/activeagents/telemetry.rb
+- lib/activeagents/telemetry/batching_reporter.rb
+- lib/activeagents/telemetry/configuration.rb
+- lib/activeagents/telemetry/reporter.rb
+- lib/activeagents/telemetry/span.rb
+- lib/activeagents/telemetry/trace.rb
+- lib/activeagents/telemetry/version.rb
+homepage: https://github.com/activeagents/activeagents-telemetry
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/activeagents/activeagents-telemetry
+  source_code_uri: https://github.com/activeagents/activeagents-telemetry
+  documentation_uri: https://github.com/activeagents/activeagents-telemetry/wiki
+  changelog_uri: https://github.com/activeagents/activeagents-telemetry/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Shared core for reporting LLM traces to ActiveAgents
+test_files: []