activeagents-telemetry 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1c2085ce9e986ab9f20cd5b8b6faf925301ec001c3f2c1c2b83192a5dcdde2f3
-  data.tar.gz: a62a35e305d0aa40b045759aef40ba1875ee44c87fa5a8c567e26b9ecda32ad5
+  metadata.gz: fe9ec7ae7a6a457e50b5da5ec21640978ce363718236c64b3eb0b1a16fe1b7f7
+  data.tar.gz: f225f754c6365b3bc7b75d683e9f8684954e68d2b8b69e010c51b2b7f04485bc
 SHA512:
-  metadata.gz: e5c6fdd40bd2528aa6c8deea2cbe5aaf506a05020b2a298f00f264178ef86821af63b36a6f6b7bb3bd03c3b23b35d15dce5ed1b24a5a3cfca0a30e336582167a
-  data.tar.gz: 93342e15bc143cd5298b39a6944ea95dea84a0cb50f19c359605b5c5f777f91b780e75f02638f074f632fdf473aaf3a8f9cdc05df0af8331324d538a7b3ced4a
+  metadata.gz: d7e70e2daef1faa3527d61fcd303f6783cbac2ce32da62c5cf053fc215dc5e602a166b6b9791bee256f041a04474557e75719563f1a3e077b8218650a3296704
+  data.tar.gz: a0b55b62db84a92e41cff0ad30edc2b420fff2a947d10665f9acaf8938bb469068cc797940e89a7d3ed53a5a0ec25efc95a738b4b1c395b6b1ecb56a083dec81

data/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## [0.3.0] - 2026-09-12
+
+### Added
+
+- `RubyLLM.with_agent` takes `attributes:`, `on_trace:` and `synchronous:`.
+  `attributes` are merged onto the root span of every trace recorded in the
+  block, with the `agent.*` identity keys taking precedence, so an evaluation
+  can stamp its run and result identifiers on the traces it causes. `on_trace`
+  receives each trace the reporter accepted for delivery, so the caller can
+  keep the `trace_id` of that delivery attempt; a trace dropped by
+  `sample_rate` or a disabled configuration is never announced. Acceptance is
+  not ingestion: a delivery that fails afterwards is logged by the reporter,
+  not surfaced to the callback. `synchronous: true` delivers in
+  the calling thread for that scope only, through the same sampling and
+  configuration checks as ordinary delivery; the shared asynchronous
+  configuration is untouched, and a delivery failure follows the reporter's
+  existing logging policy rather than raising. A turn keeps the scope it
+  started under, so a turn left open by a pending tool call and closed later
+  by `flush!` still reports with that scope's agent, attributes and callback,
+  and a turn that started outside any scope never adopts a later one.
+  Nested scopes restore the previous context, including when the block
+  raises. A callback that raises is logged by exception class and the trace
+  is still delivered. (#5)
+- `Reporter#report` takes `sync: true` to deliver in the calling thread for
+  that call only, keeping the enabled, configured and sampling checks that
+  `report_now` skips, and returns whether the traces were accepted.
+  `BatchingReporter#report` delivers that call's traces in the calling
+  thread when asked the same, leaving its buffer on its own schedule. The
+  RubyLLM adapter now requires core `~> 0.3` for it.
+
+### Fixed
+
+- `Configuration::LOCAL_ENDPOINT_PATH`, the class docs and the README's
+  self-hosting example pointed at `/active_agent/api/traces`, a path no
+  current dashboard mount serves. The actionagent engine ingests at
+  `<mount>/api/traces` and is mounted at `/activeagents` by default, so the
+  constant and the docs now say `/activeagents/api/traces` and note that a
+  custom mount changes the prefix. (#3)
+
 ## [0.2.0] - 2026-08-14
 
 ### Added
@@ -18,8 +57,6 @@
   the application sends the model, so enabling this is a data-handling
   decision — the truncation is a cap on trace size, not a redaction boundary.
 
-## [Unreleased]
-
 ## [0.1.0] - 2026-08-10
 
 First public release of both gems: `activeagents-telemetry` (the shared

data/README.md

@@ -56,12 +56,16 @@ backtraces are never transmitted.
 
 ## Self-hosting
 
-Point the endpoint at your mounted dashboard — same gems, same wire format:
+Point the endpoint at your mounted dashboard — same gems, same wire format.
+The dashboard engine ingests at `<mount>/api/traces`; its install generator
+mounts it at `/activeagents`, so on a default install that is:
 
 ```ruby
-config.endpoint = "https://your-app.example.com/active_agent/api/traces"
+config.endpoint = "https://your-app.example.com/activeagents/api/traces"
 ```
 
+If you mounted `ActionAgent::Engine` somewhere else, use that prefix instead.
+
 ## Development
 
 ```bash

data/lib/activeagents/telemetry/batching_reporter.rb

@@ -24,13 +24,28 @@ module ActiveAgents
         @shutdown = false
       end
 
-      # Enqueues a trace, flushing if the batch is full.
-      def report(traces)
-        return if @shutdown
+      # Enqueues a trace, flushing if the batch is full. `sync: true` skips the
+      # buffer: that call's traces are delivered in the calling thread before
+      # it returns, so a short-lived process can hand a trace over before it
+      # exits, and whatever the buffer already holds stays on its own schedule.
+      # @return [Boolean] whether any of the traces were accepted
+      def report(traces, sync: false)
+        return false if @shutdown
 
         accepted = normalize(traces).select { sample_trace? }
-        return if accepted.empty?
-        return unless configuration.enabled? && configuration.configured?
+        return false if accepted.empty?
+        return false unless configuration.enabled? && configuration.configured?
+
+        if sync
+          body = begin
+            payload_for(accepted)
+          rescue StandardError => e
+            log("failed to build trace payload: #{e.class}: #{e.message}")
+            return false
+          end
+          deliver(body)
+          return true
+        end
 
         batch = nil
         @mutex.synchronize do
@@ -39,7 +54,7 @@ module ActiveAgents
           start_flusher
         end
         deliver_batch(batch) if batch
-        nil
+        true
       end
 
       # Delivers everything buffered, blocking until done.

data/lib/activeagents/telemetry/configuration.rb

@@ -14,13 +14,17 @@ module ActiveAgents
     #   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".
+    # endpoint — point it at "https://your-app.example.com/activeagents/api/traces"
+    # (the actionagent engine's default mount; adjust the prefix to wherever
+    # the host app actually mounted ActionAgent::Engine).
     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"
+      # The ingest path of the dashboard engine (ActionAgent::Engine) at its
+      # default mount. The engine ingests at "<mount>/api/traces", so a host
+      # that mounted it elsewhere uses that prefix instead.
+      LOCAL_ENDPOINT_PATH = "/activeagents/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.

data/lib/activeagents/telemetry/reporter.rb

@@ -35,19 +35,29 @@ module ActiveAgents
 
       # @param traces [Trace, Hash, Array<Trace, Hash>] traces to deliver —
       #   Trace objects or already-serialized trace hashes
-      # @return [void]
-      def report(traces)
+      # @param sync [Boolean] deliver in the calling thread for this call
+      #   only; every other call keeps the configured async behaviour. The
+      #   enabled, configured and sampling checks still apply, unlike
+      #   #report_now.
+      # @return [Boolean] whether the traces were accepted for delivery. A
+      #   delivery failure is logged rather than surfaced here, so true means
+      #   the traces passed the enabled, configured and sampling checks.
+      def report(traces, sync: false)
         traces = normalize(traces)
-        return if traces.empty?
-        return unless configuration.enabled? && configuration.configured?
-        return unless sample_trace?
+        return false if traces.empty?
+        return false unless configuration.enabled? && configuration.configured?
+        return false unless sample_trace?
 
         body = payload_for(traces)
-        configuration.async? ? Thread.new { deliver(body) } : deliver(body)
-        nil
+        if sync || !configuration.async?
+          deliver(body)
+        else
+          Thread.new { deliver(body) }
+        end
+        true
       rescue StandardError => e
         log("failed to build trace payload: #{e.class}: #{e.message}")
-        nil
+        false
       end
 
       # Blocking delivery, for tests and for at-exit flushes.

data/lib/activeagents/telemetry/version.rb

@@ -2,6 +2,6 @@
 
 module ActiveAgents
   module Telemetry
-    VERSION = "0.2.0"
+    VERSION = "0.3.0"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: activeagents-telemetry
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - ActiveAgents
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-14 00:00:00.000000000 Z
+date: 2026-09-13 00:00:00.000000000 Z
 dependencies: []
 description: |
   The wire format, configuration, and delivery layer behind ActiveAgents