chronos-ruby 0.6.0.pre.1 → 0.8.0.pre.1

data/docs/modules/rails-legacy.md

@@ -29,7 +29,7 @@ The public `ActiveSupport::Notifications.subscribe` API is used for:
 | `sql.active_record` | `query` | operation name, cached flag, and duration |
 | `deliver.action_mailer` | `job` with `kind=mailer` | mailer, action, and duration |
 | `perform.active_job` | `job` | job class, queue, and duration, when Active Job is available |
-| cache read/write/hit notifications | `cache` | operation, store, hit flag, and duration |
+| cache read/write/hit notifications | `cache` | operation, backend, namespace, hit/miss, duration, and optional scoped key hash |
 
 Raw SQL, binds, cache keys, mail recipients and bodies, job IDs and arguments, request/response bodies, cookies, and authorization headers are not copied. Template identifiers are reduced to their basename. Every event passes through `Sanitizer`, `SafeSerializer`, the bounded queue, retry policy, circuit breaker, and memory backlog.
 
@@ -57,4 +57,4 @@ The repository contains independent applications under `examples/rails-4.2` and
 
 ## Limits
 
-Version 0.5 emits individual bounded timings. It does not aggregate APM metrics, capture SQL text, or calculate query fingerprints. Sidekiq support is a separate optional integration beginning in version 0.6; full Active Job propagation remains a later 0.6 increment.
+Version 0.7 aggregates controller, SQL, and job timings into bounded APM batches. SQL literals and binds remain excluded while a bounded normalized query and fingerprint are produced. Sidekiq support remains a separate optional integration; full Active Job propagation remains a later legacy increment.

data/docs/modules/sidekiq-legacy.md

@@ -4,7 +4,7 @@ Version `0.6.0.pre.1` starts the legacy jobs line with optional Sidekiq 4 and 5
 
 ```ruby
 gem "sidekiq", "~> 5.0"
-gem "chronos-ruby", "0.6.0.pre.1", :require => "chronos/sidekiq"
+gem "chronos-ruby", "0.8.0.pre.1", :require => "chronos/sidekiq"
 ```
 
 `chronos/sidekiq` installs middleware through the public `configure_client` and `configure_server` APIs. It does nothing when Sidekiq is unavailable, and the core gem never requires Sidekiq. Installation adds no Chronos thread or Redis/database connection per job; delivery continues through the agent's existing fixed worker pool.
@@ -13,7 +13,7 @@ The client middleware adds a top-level `chronos` metadata object to the Sidekiq
 
 Collected Sidekiq fields are worker class, queue, JID, retry count, duration, queue latency, status, error class, bounded tags, and bounded arguments. At most 20 top-level arguments, 20 values per nested collection, four levels, and 512 bytes per string are traversed. Arguments then pass through the standard sensitive-key/content sanitizer before queueing. Limits reduce exposure and resource use but do not make unnecessary personal data safe to collect.
 
-On failure, the server middleware records failed-job telemetry, invokes `notify_once`, and re-raises the identical exception so Sidekiq retains ownership of retries and failure handlers. A shared execution marker prevents a nested Active Job hook and the Sidekiq middleware from sending the same exception twice. Chronos does not install an additional global Sidekiq error handler.
+On failure, the server middleware records a failed-job observation, invokes `notify_once`, and re-raises the identical exception so Sidekiq retains ownership of retries and failure handlers. A shared execution marker prevents a nested Active Job hook and the Sidekiq middleware from sending the same exception twice. Version 0.7 aggregates the job observation; the exception retains sanitized bounded arguments. Chronos does not install an additional global Sidekiq error handler.
 
 Known limitations for this first 0.6 prerelease:
 

data/docs/modules/telemetry-events.md

@@ -1,9 +1,9 @@
 # Framework telemetry events
 
-`Chronos::Core::TelemetryEvent` and `Chronos::Core::TelemetrySerializer` extend the v1 envelope to `request`, `query`, `job`, and `cache` events. These values exist so framework adapters do not model operational timings as fake exceptions.
+`Chronos::Core::TelemetryEvent` and `Chronos::Core::TelemetrySerializer` extend the v1 envelope to `request`, `query`, `job`, `cache`, `external_http`, `dependencies`, and `metric_batch` events. These values exist so integrations do not model operational telemetry as fake exceptions.
 
 Telemetry has the same `schema_version`, event ID, timestamps, project, environment, service, runtime, context, sanitization, payload-size limit, idempotency header, asynchronous queue, retry, circuit breaker, and memory backlog used by exception events. Unsupported types are rejected locally.
 
 `Chronos.record_event` is the narrow integration entry point. Application code should prefer documented higher-level APIs; its payload is allowlisted by each bundled integration and then sanitized. Remote configuration can reduce or disable any locally enabled telemetry type but cannot enable a type excluded by local configuration.
 
-Version 0.5 intentionally sends individual framework events. Aggregation, percentiles, slow-query analysis, and transaction breakdowns remain part of version 0.7.
+Version 0.8 aggregates request, query, job, and enabled external HTTP observations into `metric_batch` events by default. Cache remains an individual event while contributing to an existing traced request breakdown. Dependencies use one separate event per agent. Set `apm_enabled = false` only when individual legacy telemetry is required for diagnostics. Percentiles remain server-side; see [Essential APM aggregation](apm-aggregation.md).

data/docs/performance.md

@@ -1,6 +1,6 @@
 # Performance
 
-Performance is a functional requirement, but version 0.6 makes no unverified speed claim.
+Performance is a functional requirement, but version 0.8 makes no unverified speed claim.
 
 Current controls:
 
@@ -20,6 +20,10 @@ Current controls:
 - Rack middleware never consumes request or response bodies.
 - Rails subscribers copy only small allowlisted field sets and never copy raw SQL or job arguments.
 - Sidekiq middleware creates no per-job thread or connection and bounds arguments, collections, nesting, strings, and tags before telemetry capture.
+- APM group, trace, query-fingerprint, histogram, and batch counts are fixed; no APM timer thread is created.
+- outbound HTTP instrumentation uses two clock reads and bounded metadata without body/header traversal;
+- cache normalization is bounded and SHA-256 runs only when explicitly enabled;
+- dependency inventory runs at most once per agent and is capped at 200 loaded specs.
 
 Run the scripts under `benchmarks/` and record Ruby version, operating system, CPU, warmup, iteration count, median, and dispersion before publishing results. `benchmarks/filtering.rb` measures privacy filtering, `benchmarks/retry_backlog.rb` measures fixed-memory outage behavior, `benchmarks/request_overhead.rb` compares Rack-protocol calls, and `benchmarks/rails_notifications.rb` isolates subscriber normalization overhead.
 
@@ -87,3 +91,27 @@ ITERATIONS=100000 bundle _1.17.3_ exec ruby benchmarks/sidekiq_middleware.rb
 ```
 
 The benchmark executes client context injection and successful server normalization with a no-op notifier. It includes bounded argument handling and clock reads, but excludes Sidekiq/Redis, serialization, queueing, and network delivery. Record a controlled result before making a performance claim.
+
+## Version 0.7 APM aggregation benchmark
+
+Run:
+
+```bash
+ITERATIONS=100000 bundle _1.17.3_ exec ruby benchmarks/apm_aggregation.rb
+```
+
+The fixture repeatedly updates one SQL metric group and one trace-local fingerprint. It excludes ActiveSupport dispatch, serialization, queueing, and network delivery. The benchmark must report one retained group; memory must remain bounded by configuration. Record runtime, hardware, warmup, median, and dispersion before publishing a performance claim.
+
+A local diagnostic run on 2026-07-20 used Ruby 2.2.10 on macOS arm64 and 10,000 observations. It retained one group and measured approximately 34.972 microseconds per observation. This single run has no controlled warmup, median, or dispersion and is not a production performance claim.
+
+## Version 0.8 external HTTP benchmark
+
+Run:
+
+```bash
+ITERATIONS=100000 bundle _1.17.3_ exec ruby benchmarks/external_http.rb
+```
+
+The fixture compares a no-op Net::HTTP-compatible object with the per-instance wrapper. It includes trace-header injection, bounded outcome capture, and clock reads, but excludes DNS, sockets, TLS, serialization, queueing, and network delivery. Record a controlled result before making a performance claim.
+
+A local diagnostic run on 2026-07-20 used Ruby 2.2.10 on macOS arm64 and 10,000 calls. It measured approximately 15.155 microseconds of wrapper overhead per call. This single run has no controlled warmup, median, or dispersion and is not a production performance claim.

data/docs/privacy-lgpd.md

@@ -1,6 +1,6 @@
 # Privacy and LGPD
 
-Version 0.6 sanitizes exception and framework telemetry before JSON serialization, queueing, retry backlog, or transport. This reduces accidental exposure, but the host application remains responsible for lawful purpose, minimization, access control, retention, and responses to data-subject requests.
+Version 0.8 sanitizes exception, framework telemetry, dependency inventory, and APM metric batches before JSON serialization, queueing, retry backlog, or transport. This reduces accidental exposure, but the host application remains responsible for lawful purpose, minimization, access control, retention, and responses to data-subject requests.
 
 ## Default policy
 
@@ -15,8 +15,18 @@ Version 0.6 sanitizes exception and framework telemetry before JSON serializatio
 | Unknown Ruby objects | Represented by class name without calling application serialization |
 | Request/response bodies, raw query strings, cookies, authorization headers, raw SQL/binds, cache values, mail bodies, environment variables | Never collected automatically |
 | Sidekiq arguments | Collected automatically, limited before sanitization, then redacted by the common policy |
+| SQL | Comments, quoted/numeric/boolean/null literals removed; binds never read; bounded identifiers remain |
+| External HTTP | Host/method/status/timing only; URL path/query, Authorization, bodies, headers, and error messages omitted |
+| Cache key | Omitted by default; optional project-scoped SHA-256 hash; cache value never read |
+| Dependencies | Bounded loaded gem names/versions and detected runtime labels; paths and lockfiles omitted |
 
-The retry backlog exists only in process memory, accepts only `SerializedEvent`, has a fixed capacity, and disappears on process exit. Version 0.6 does not persist telemetry to disk.
+The retry backlog exists only in process memory, accepts only `SerializedEvent`, has a fixed capacity, and disappears on process exit. Version 0.8 does not persist telemetry to disk.
+
+## External services, cache, and dependencies
+
+Outbound HTTP instrumentation is disabled by default and installed per connection. Trace headers reveal correlation identifiers to the selected destination; enable propagation only for destinations permitted to receive them. The wrapper does not inspect any other header or URL component.
+
+Raw cache keys can contain user or business data and are never delivered. Optional hashing is pseudonymization, not anonymization: predictable low-entropy keys can still be guessed. Dependency reporting is a separate once-per-agent event, never copied into exceptions, and can be disabled. It reads loaded gem name/version pairs only, with no filesystem path, source, configuration, or complete lockfile.
 
 ## Rails telemetry
 
@@ -26,6 +36,10 @@ Rails subscribers use per-notification allowlists. SQL events retain only the op
 
 The optional Sidekiq middleware is the only version 0.6 integration that automatically reads job arguments. It traverses at most 20 top-level arguments, 20 items per nested collection, four levels, and 512 bytes per string. These structural limits run before the common key and content sanitizer. Trace propagation contains only trace and request identifiers. Do not place credentials or unnecessary personal, health, or financial data in job arguments; configure application-specific blocklist keys and audit representative synthetic payloads before enabling production delivery.
 
+## APM dimensions
+
+Metric groups deliberately exclude user IDs, JIDs, raw URLs, request parameters, bind values, exception messages, and cache keys. SQL normalization removes common literal forms and comments before fingerprinting, but retains bounded database identifiers and cannot parse every dialect. Do not encode personal or secret values in schema, table, column, SQL keyword, or operation names. Slow-query source contains a bounded file/line frame under the configured application root, not source-code contents.
+
 ## Rack context and breadcrumbs
 
 The Rack middleware copies only bounded operational fields and parameter hashes that another component already parsed. It does not read `rack.input` or copy `QUERY_STRING`. User context is opt-in through `chronos.user`, and user agent collection is disabled unless the middleware option enables it.

data/docs/troubleshooting.md

@@ -22,7 +22,19 @@ Require `chronos/rails` from the generated initializer and confirm it runs befor
 
 ## Rails telemetry contains no SQL or cache key
 
-This is intentional. Version 0.5 records SQL operation name/duration and cache operation/store/hit status without raw statements, binds, keys, or values. These omissions are privacy and cardinality boundaries, not capture failures.
+This is intentional. Chronos records bounded SQL and cache operational metadata without raw statements, binds, keys, or values. Set `cache_key_mode = :sha256` before configuration only when a stable pseudonymous key identity is required.
+
+## External HTTP telemetry is missing
+
+Set `external_http_enabled = true`, then call `Chronos.instrument_net_http(http)` for each `Net::HTTP` instance after Chronos is configured. Existing and future objects are not patched globally. The method returns `false` when disabled, already installed, incompatible, or unconfigured.
+
+## Trace headers should not reach a destination
+
+Set `external_http_trace_headers = false` before configuring the agent, or do not instrument that connection. Chronos preserves an application-supplied Chronos header instead of overwriting it.
+
+## Dependency inventory is missing or incomplete
+
+The event is emitted once per agent and contains only gems loaded at collection time, capped by `dependency_max_items`. It does not parse the lockfile or activate optional frameworks. Call `Chronos.report_dependencies` after application boot if the first event can occur before all integrations load, or set `dependency_reporting = false` to disable collection.
 
 ## Sidekiq telemetry is missing
 
@@ -32,6 +44,18 @@ Require `chronos/sidekiq` after Sidekiq is available and configure Chronos befor
 
 The bundled middleware does not install a global error handler and uses `notify_once` inside a shared job scope. Check for application-installed Chronos calls or third-party global handlers outside that scope. Keep a single bundled server middleware entry in the Sidekiq chain.
 
+## Request, query, or job events are not sent immediately
+
+This is expected with version 0.7 APM aggregation. Groups drain after `apm_flush_count` observations or during `Chronos.flush`/`Chronos.close`. Inspect `agent.diagnostics[:apm]` when using an explicit agent. Set `apm_enabled = false` only for temporary individual-event diagnostics.
+
+## Query metrics contain no literal values or binds
+
+This is intentional. The normalizer removes common literal forms and never reads binds. Queries differing only by values should share a fingerprint. If an unsupported database dialect leaves a sensitive literal form, stop delivery, add a synthetic privacy fixture, and report the dialect through the security/support process.
+
+## Possible N+1 or deadlock signal is inaccurate
+
+Local detectors emit bounded heuristics, not confirmed diagnoses. Repetition can be legitimate and exception class names can be adapter-specific. Confirm the trace in the SaaS and application logs before changing application behavior.
+
 ## Context appears missing
 
 The legacy context store is thread-local. A new application-created thread does not inherit context. Establish a new `Chronos.with_context` scope inside that thread, and issue manual notification before the scope exits. For Rack capture, supply user and explicit parameters through the documented environment keys.

data/lib/chronos/agent.rb

@@ -37,13 +37,16 @@ module Chronos
         pipeline_options
       )
       initialize_capture(options)
+      @dependency_reporter = options[:dependency_reporter] || Application::DependencyReporter.new(config)
     end
 
     def notify(exception, context = {})
+      report_dependencies
       @capture.call(exception, context_for_capture(context))
     end
 
     def notify_sync(exception, context = {})
+      report_dependencies
       @capture.call_sync(exception, context_for_capture(context))
     end
 
@@ -64,9 +67,48 @@ module Chronos
     end
 
     def record_event(event_type, payload = {}, context = {})
+      report_dependencies unless event_type.to_s == "dependencies"
       @telemetry.call(event_type, payload, telemetry_context(context))
     end
 
+    def report_dependencies
+      payload = @dependency_reporter.call
+      return false unless payload
+
+      @telemetry.call("dependencies", payload, {})
+    rescue StandardError => error
+      @logger.warn("Chronos dependency reporting failed: #{error.class}")
+      false
+    end
+
+    def record_event_once(key, event_type, payload = {}, context = {})
+      execution = @context_store.get
+      captured = execution[:__chronos_captured_events] || {}
+      return false if captured[key.to_s]
+
+      captured[key.to_s] = true
+      @context_store.set(execution.merge(:__chronos_captured_events => captured))
+      record_event(event_type, payload, context)
+    rescue StandardError
+      false
+    end
+
+    def apm_integration_options
+      {
+        :enabled => @config.apm_enabled,
+        :slow_query_threshold_ms => @config.apm_slow_query_threshold_ms,
+        :root_directory => @config.root_directory
+      }
+    end
+
+    def external_http_integration_options
+      {:enabled => @config.external_http_enabled, :trace_headers => @config.external_http_trace_headers}
+    end
+
+    def cache_integration_options
+      {:project_id => @config.project_id, :key_mode => @config.cache_key_mode}
+    end
+
     # Returns the correlation subset safe for an integration-owned process boundary.
     def propagation_context
       current = context_hash(@context_store.get)
@@ -104,6 +146,8 @@ module Chronos
     end
 
     def flush(timeout = DEFAULT_FLUSH_TIMEOUT)
+      report_dependencies
+      @telemetry.flush
       @delivery_pipeline.flush(timeout)
     rescue StandardError => error
       @logger.warn("Chronos flush failed: #{error.class}")
@@ -111,6 +155,8 @@ module Chronos
     end
 
     def close(timeout = DEFAULT_FLUSH_TIMEOUT)
+      report_dependencies
+      @telemetry.flush
       @delivery_pipeline.close(timeout)
     rescue StandardError => error
       @logger.warn("Chronos close failed: #{error.class}")
@@ -119,6 +165,7 @@ module Chronos
 
     def diagnostics
       details = @delivery_pipeline.diagnostics
+      details[:apm] = @telemetry.diagnostics
       details[:queue].merge(details)
     end
 
@@ -139,6 +186,8 @@ module Chronos
       merged = deep_merge(context_hash(@context_store.get), context_hash(additional))
       merged.delete(:__chronos_captured_exceptions)
       merged.delete("__chronos_captured_exceptions")
+      merged.delete(:__chronos_captured_events)
+      merged.delete("__chronos_captured_events")
       buffer = merged.delete(:__chronos_breadcrumbs) || merged.delete("__chronos_breadcrumbs")
       if buffer.respond_to?(:to_a)
         merged[:context] = context_hash(merged[:context]).merge("breadcrumbs" => buffer.to_a)

data/lib/chronos/application/apm_aggregator.rb

@@ -0,0 +1,270 @@
+module Chronos
+  module Application
+    # Aggregates bounded request, query, job, and external HTTP observations into metric batches.
+    #
+    # @responsibility Maintain statistics, histograms, breakdown, and local query signals.
+    # @motivation Avoid one network event per observation while retaining diagnostic value.
+    # @limits Percentiles and heavy correlation remain server-side; state is process-local.
+    # @collaborators CaptureTelemetry and immutable Chronos configuration.
+    # @thread_safety A mutex protects groups, request trackers, counters, and drains.
+    # @compatibility Ruby 2.2.10 through Ruby 2.6; independent of Rails.
+    # @example
+    #   aggregator.record("request", payload, context)
+    #   batches = aggregator.flush
+    # @errors Invalid observations are ignored and never escape to the application.
+    # @performance Group, transaction, query, bucket, and batch counts are strictly bounded.
+    class ApmAggregator
+      include ApmErrorClassifier
+
+      METRIC_TYPES = %w(request query job external_http).freeze
+      def initialize(config)
+        @config = config
+        @mutex = Mutex.new
+        @groups = {}
+        @transactions = {}
+        @observations = 0
+        @dropped_groups = 0
+      end
+
+      def record(event_type, payload = {}, context = {})
+        return [] unless @config.apm_enabled
+
+        @mutex.synchronize do
+          type = event_type.to_s
+          data = hash(payload)
+          execution = hash(context)
+          observe_component(type, data, execution)
+          add_metric(type, data, execution) if aggregate_metric?(type, data)
+          @observations += 1 if aggregate_metric?(type, data)
+          @observations >= @config.apm_flush_count ? drain_locked : []
+        end
+      rescue StandardError
+        []
+      end
+
+      def flush
+        @mutex.synchronize { drain_locked }
+      rescue StandardError
+        []
+      end
+
+      def diagnostics
+        @mutex.synchronize do
+          {
+            "groups" => @groups.length, "dropped_groups" => @dropped_groups,
+            "transactions" => @transactions.length,
+            "tracked_queries" => @transactions.values.inject(0) do |total, transaction|
+              total + transaction["queries"].length
+            end
+          }
+        end
+      end
+
+      private
+
+      def aggregate_metric?(type, payload)
+        METRIC_TYPES.include?(type) && !(type == "request" && payload["kind"].to_s == "view")
+      end
+
+      def add_metric(type, payload, context)
+        dimensions = dimensions_for(type, payload)
+        key = metric_key(type, dimensions)
+        aggregate = @groups[key]
+        unless aggregate
+          if @groups.length >= @config.apm_max_groups
+            @dropped_groups += 1
+            return
+          end
+          aggregate = Core::MetricAggregate.new(type, dimensions, @config.apm_histogram_buckets)
+          @groups[key] = aggregate
+        end
+        duration = non_negative(payload["duration_ms"] || payload[:duration_ms])
+        status = ["request", "external_http"].include?(type) ? payload["status"] || payload[:status] : nil
+        signals = signals_for(type, payload, context, duration)
+        breakdown = breakdown_for(type, payload, context, duration)
+        aggregate.observe(
+          duration, error?(type, payload), breakdown, signals, status
+        )
+      end
+
+      def observe_component(type, payload, context)
+        return if type == "job"
+
+        trace_id = trace_id(context)
+        return if trace_id.empty?
+
+        transaction = transaction_for(trace_id)
+        return unless transaction
+
+        category = component_category(type, payload)
+        return observe_query(transaction, payload) if type == "query" && category.nil?
+        return unless category
+
+        transaction["breakdown_ms"][category] ||= 0.0
+        transaction["breakdown_ms"][category] += non_negative(payload["duration_ms"] || payload[:duration_ms])
+        observe_query(transaction, payload) if type == "query"
+      end
+
+      def transaction_for(trace_id)
+        existing = @transactions[trace_id]
+        return existing if existing
+        return nil if @transactions.length >= @config.apm_max_groups
+
+        @transactions[trace_id] = {"breakdown_ms" => {}, "signals" => {}, "queries" => {}}
+      end
+
+      def observe_query(transaction, payload)
+        fingerprint = (payload["fingerprint"] || payload[:fingerprint]).to_s
+        return if fingerprint.empty?
+
+        queries = transaction["queries"]
+        return unless queries.key?(fingerprint) || queries.length < @config.apm_max_queries_per_request
+
+        queries[fingerprint] ||= 0
+        queries[fingerprint] += 1
+        count = queries[fingerprint]
+        slow = non_negative(payload["duration_ms"]) >= @config.apm_slow_query_threshold_ms
+        increment_signal(transaction, "slow_query") if slow
+        increment_signal(transaction, "repeated_query") if count > 1
+        increment_signal(transaction, "possible_n_plus_one") if count == @config.apm_n_plus_one_threshold
+      end
+
+      def breakdown_for(type, payload, context, duration)
+        explicit = hash(payload["breakdown_ms"] || payload[:breakdown_ms]).dup
+        if type == "request"
+          transaction = @transactions.delete(trace_id(context))
+          explicit = merge_numeric(explicit, transaction && transaction["breakdown_ms"])
+          accounted = explicit.values.inject(0.0) { |total, value| total + non_negative(value) }
+          explicit["application"] = [duration - accounted, 0.0].max
+        elsif type == "query"
+          explicit["database"] = duration
+        elsif type == "job"
+          explicit["queue"] = non_negative(payload["queue_latency_ms"] || payload[:queue_latency_ms])
+          explicit["application"] = duration
+        end
+        explicit
+      end
+
+      def signals_for(type, payload, context, duration)
+        return request_signals(context) if type == "request"
+        return query_signals(payload, duration) if type == "query"
+
+        {}
+      end
+
+      def request_signals(context)
+        transaction = @transactions[trace_id(context)]
+        transaction ? transaction["signals"].dup : {}
+      end
+
+      def query_signals(payload, duration)
+        signals = {}
+        signals["slow_query"] = 1 if duration >= @config.apm_slow_query_threshold_ms
+        signals["long_transaction"] = 1 if long_transaction?(payload, duration)
+        error_class = (payload["error_class"] || payload[:error_class]).to_s
+        signals["connection_error"] = 1 if error_class =~ /Connection|NoDatabase|Adapter/i
+        signals["deadlock"] = 1 if error_class =~ /Deadlock/i
+        signals
+      end
+
+      def long_transaction?(payload, duration)
+        operation = (payload["operation"] || payload[:operation]).to_s
+        name = (payload["name"] || payload[:name]).to_s
+        transaction = operation == "BEGIN" || operation == "COMMIT" || name =~ /TRANSACTION/i
+        transaction && duration >= @config.apm_long_transaction_threshold_ms
+      end
+
+      def dimensions_for(type, payload)
+        names = case type
+                when "request" then %w(route method)
+                when "query" then %w(adapter operation table fingerprint normalized_query name cached role shard source)
+                when "job" then %w(kind class queue status)
+                when "external_http" then %w(host method)
+                else []
+                end
+        names.each_with_object({}) do |name, result|
+          value = payload[name] || payload[name.to_sym]
+          next if value.nil? || value.to_s.empty?
+
+          result[name] = dimension_value(type, name, value)
+        end
+      end
+
+      def dimension_value(type, name, value)
+        return value == true if name == "cached"
+        return value.to_i if type == "request" && name == "status"
+
+        text = value.to_s
+        text = normalize_route(text) if name == "route"
+        text.bytesize > 512 ? text.byteslice(0, 512) : text
+      end
+
+      def normalize_route(route)
+        route.split("/").map do |segment|
+          segment =~ /\A\d+\z/ || segment =~ /\A[0-9a-f]{8}-[0-9a-f-]{27,}\z/i ? ":id" : segment
+        end.join("/")
+      end
+
+      def metric_key(type, dimensions)
+        type + "|" + dimensions.keys.sort.map { |key| "#{key}=#{dimensions[key]}" }.join("|")
+      end
+
+      def component_category(type, payload)
+        return "database" if type == "query"
+        return "view" if type == "request" && payload["kind"].to_s == "view"
+        return "cache" if type == "cache"
+        return "queue" if type == "job"
+        return "external_http" if type == "external_http"
+
+        nil
+      end
+
+      def trace_id(context)
+        (context["trace_id"] || context[:trace_id]).to_s
+      end
+
+      def increment_signal(transaction, name)
+        transaction["signals"][name] ||= 0
+        transaction["signals"][name] += 1
+      end
+
+      def merge_numeric(left, right)
+        hash(right).each do |key, value|
+          left[key.to_s] ||= 0.0
+          left[key.to_s] += non_negative(value)
+        end
+        left
+      end
+
+      def drain_locked
+        metrics = @groups.values.map(&:to_h)
+        if metrics.empty?
+          @transactions = {}
+          return []
+        end
+
+        dropped = @dropped_groups
+        @groups = {}
+        @transactions = {}
+        @observations = 0
+        @dropped_groups = 0
+        batches = []
+        metrics.each_slice(@config.apm_batch_size) do |slice|
+          batches << {"metrics" => slice, "dropped_groups" => batches.empty? ? dropped : 0}
+        end
+        batches
+      end
+
+      def non_negative(value)
+        number = value.to_f
+        number < 0.0 ? 0.0 : number
+      rescue StandardError
+        0.0
+      end
+
+      def hash(value)
+        value.is_a?(Hash) ? value : {}
+      end
+    end
+  end
+end

data/lib/chronos/application/apm_error_classifier.rb

@@ -0,0 +1,27 @@
+module Chronos
+  module Application
+    # Classifies bounded APM observations without inspecting exception messages.
+    module ApmErrorClassifier
+      private
+
+      def error?(type, payload)
+        return status_error?(payload) if type == "request"
+        return (payload["status"] || payload[:status]).to_s == "failed" if type == "job"
+        return external_http_error?(payload) if type == "external_http"
+
+        !(payload["error_class"] || payload[:error_class]).to_s.empty?
+      end
+
+      def external_http_error?(payload)
+        return true unless (payload["error_class"] || payload[:error_class]).to_s.empty?
+        return true if payload["timeout"] == true || payload[:timeout] == true
+
+        status_error?(payload)
+      end
+
+      def status_error?(payload)
+        (payload["status"] || payload[:status]).to_i >= 500
+      end
+    end
+  end
+end

data/lib/chronos/application/capture_telemetry.rb

@@ -2,10 +2,10 @@ module Chronos
   module Application
     # Coordinates bounded non-exception telemetry capture.
     #
-    # @responsibility Build, sanitize, serialize, and enqueue integration events.
-    # @motivation Keep Rails notification policy outside transport and domain objects.
-    # @limits It handles request, query, job, and cache events only.
-    # @collaborators TelemetryEvent, TelemetrySerializer, and DeliveryPipeline.
+    # @responsibility Aggregate APM observations or serialize and enqueue integration events.
+    # @motivation Keep framework policy and local batching outside transport and domain objects.
+    # @limits It handles only the event types declared by TelemetryEvent.
+    # @collaborators ApmAggregator, TelemetryEvent, TelemetrySerializer, and DeliveryPipeline.
     # @thread_safety Calls own event state and may execute concurrently.
     # @compatibility Ruby 2.2.10 through Ruby 2.6; independent of Rails.
     # @example
@@ -20,18 +20,58 @@ module Chronos
         @serializer = options[:serializer] || Core::TelemetrySerializer.new(
           config, nil, :max_payload_size => proc { @delivery_pipeline.max_payload_size }
         )
+        @aggregator = options[:aggregator] || ApmAggregator.new(config)
       end
 
       def call(event_type, payload = {}, context = {})
         return false unless @config.enabled_for_environment?
         return false unless @delivery_pipeline.capture_allowed?(event_type)
 
+        aggregate = aggregation_enabled?
+        batches = aggregate ? @aggregator.record(event_type, payload, context) : []
+        return enqueue_batches(batches) if aggregate && aggregate_type?(event_type)
+
         event = Core::TelemetryEvent.new(event_type, payload, context)
-        @delivery_pipeline.enqueue(@serializer.call(event))
+        delivered = @delivery_pipeline.enqueue(@serializer.call(event))
+        enqueue_batches(batches)
+        delivered
       rescue StandardError => error
         @logger.warn("Chronos telemetry capture failed: #{error.class}")
         false
       end
+
+      def flush
+        enqueue_batches(@aggregator.flush)
+      rescue StandardError => error
+        @logger.warn("Chronos APM flush failed: #{error.class}")
+        false
+      end
+
+      def diagnostics
+        @aggregator.diagnostics
+      rescue StandardError
+        {}
+      end
+
+      private
+
+      def aggregate_type?(event_type)
+        ApmAggregator::METRIC_TYPES.include?(event_type.to_s)
+      end
+
+      def aggregation_enabled?
+        @config.apm_enabled && @delivery_pipeline.event_enabled?("metric_batch")
+      end
+
+      def enqueue_batches(batches)
+        results = Array(batches).map do |batch|
+          next false unless @delivery_pipeline.event_enabled?("metric_batch")
+
+          event = Core::TelemetryEvent.new("metric_batch", batch)
+          @delivery_pipeline.enqueue(@serializer.call(event))
+        end
+        results.empty? || results.all?
+      end
     end
   end
 end

data/lib/chronos/application/delivery_pipeline.rb

@@ -67,6 +67,13 @@ module Chronos
         false
       end
 
+      def event_enabled?(event_type)
+        @remote_configuration.delivery_enabled?(event_type)
+      rescue StandardError => error
+        diagnose(error)
+        false
+      end
+
       def max_payload_size
         @remote_configuration.max_payload_size
       end