Standardized metrics export - feature flagged

.rubocop.yml

@@ -21,6 +21,7 @@ Style/MixinUsage:
 
 # Metrics settings
 Metrics/BlockLength:
+  Max: 40
   Exclude:
     - 'spec/**/*'
     - '*.gemspec'

AGENTS.md

@@ -300,46 +300,17 @@ end
 
 ### Metrics Collection
 
-The MetricsCollector listens to events and tracks metrics:
+The SDK supports legacy and canonical metric surfaces, selected by the
+`WORKER_CANONICAL_METRICS` environment variable. `MetricsCollector.create`
+returns the appropriate collector:
 
 ```ruby
-class MetricsCollector
-  def on_poll_started(event)
-    increment("task_poll_total", task_type: event.task_type)
-  end
-
-  def on_poll_completed(event)
-    observe("task_poll_time_seconds", event.duration_ms / 1000.0,
-            task_type: event.task_type)
-  end
-
-  def on_task_execution_completed(event)
-    observe("task_execute_time_seconds", event.duration_ms / 1000.0,
-            task_type: event.task_type)
-    observe("task_result_size_bytes", event.output_size_bytes,
-            task_type: event.task_type)
-  end
-
-  def on_task_execution_failure(event)
-    increment("task_execute_error_total",
-              task_type: event.task_type,
-              exception: event.cause.class.name,
-              retryable: event.is_retryable.to_s)
-  end
-end
+metrics = Conductor::Worker::Telemetry::MetricsCollector.create(backend: :prometheus)
 ```
 
-### Prometheus Metrics
-
-| Metric | Type | Labels | Description |
-|--------|------|--------|-------------|
-| `task_poll_total` | Counter | `task_type` | Number of poll operations |
-| `task_poll_time_seconds` | Histogram | `task_type` | Poll latency |
-| `task_poll_error_total` | Counter | `task_type`, `error` | Poll failures |
-| `task_execute_time_seconds` | Histogram | `task_type` | Execution time |
-| `task_execute_error_total` | Counter | `task_type`, `exception`, `retryable` | Execution failures |
-| `task_result_size_bytes` | Histogram | `task_type` | Output size |
-| `task_update_failed_total` | Counter | `task_type` | CRITICAL: Update failures |
+See [docs/METRICS_AND_INTERCEPTORS.md](docs/METRICS_AND_INTERCEPTORS.md) for
+the full legacy and canonical metrics catalogs, label reference, and migration
+guide.
 
 ### Worker Configuration (3-Tier Hierarchy)
 
@@ -436,8 +407,11 @@ lib/conductor/
 │   │   ├── listeners.rb          # Listener protocol
 │   │   └── listener_registry.rb  # Registration helper
 │   └── telemetry/                # Metrics
-│       ├── metrics_collector.rb  # Event-based metrics
-│       └── prometheus_backend.rb # Prometheus integration
+│       ├── metrics_collector.rb  # Factory (WORKER_CANONICAL_METRICS gate)
+│       ├── legacy_metrics_collector.rb  # Legacy metric set
+│       ├── canonical_metrics_collector.rb # Canonical metric set
+│       ├── prometheus_backend.rb # Legacy Prometheus backend
+│       └── canonical_prometheus_backend.rb # Canonical Prometheus backend
 └── workflow/
     ├── dsl/                      # Workflow DSL
     │   ├── workflow_builder.rb   # Core DSL engine (~1000 lines)

CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Canonical metrics mode: opt-in harmonized metric surface via `WORKER_CANONICAL_METRICS=true` -- [details](docs/METRICS_AND_INTERCEPTORS.md#detailed-technical-notes----unreleased)
+- Bounded `uri` label on `http_api_client_request_seconds`: uses path templates (e.g. `/workflow/{workflowId}`) instead of fully-resolved paths, preventing metric cardinality explosion
+- `WorkflowStatusProbe` in harness: opt-in probe (via `HARNESS_PROBE_RATE_PER_SEC`) that exercises UUID-bearing endpoints to validate template URI metrics
+
 ### Changed
 
 - **BREAKING: Workflow DSL Redesign** - Complete redesign of the workflow DSL for Ruby-idiomatic syntax
@@ -17,6 +23,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Control flow blocks: `parallel do`, `decide expr do`, `loop_over items do`
   - Auto-generated task reference names
   - Simplified LLM task methods with hash-to-ChatMessage auto-conversion
+- `MetricsCollector.new(...)` is deprecated; use `MetricsCollector.create(...)` instead. `.new` still works but logs a deprecation warning. The previous implementation is preserved as `LegacyMetricsCollector` and remains the default.
+- Legacy metrics emit unchanged by default; existing dashboards and alerts continue to work without modification
+- HTTP request timing (`http_api_client_request_seconds`) is now zero-overhead in legacy mode: `RestClient` only enters the timing path when a canonical collector is subscribed to `GlobalDispatcher`
+- `thread_uncaught_exceptions_total` is no longer incremented for caught exceptions in the polling loop; the metric surface is retained but unwired, matching the Python and JavaScript SDKs
+- Both `CanonicalMetricsCollector` and `LegacyMetricsCollector` now respond to `stop`; `TaskHandler#stop` calls it automatically to unsubscribe from process-wide dispatchers
+- `MetricsCollector.create` accepts `measure_payload_size:` (default `true` for canonical, `false` for legacy) to opt out of `workflow_input_size_bytes` JSON serialization overhead
 
 ### Removed
 

Gemfile

@@ -4,6 +4,9 @@ source 'https://rubygems.org'
 
 gemspec
 
+install_if -> { RUBY_VERSION >= '3.3' } do
+  gem 'async', '~> 2.0', group: :test
+end
 gem 'prometheus-client', '~> 4.0'
 gem 'rake', '~> 13.0'
 gem 'webrick', '~> 1.8'

Gemfile.lock

@@ -14,11 +14,21 @@ GEM
     addressable (2.8.8)
       public_suffix (>= 2.0.2, < 8.0)
     ast (2.4.3)
+    async (2.39.0)
+      console (~> 1.29)
+      fiber-annotation
+      io-event (~> 1.11)
+      metrics (~> 0.12)
+      traces (~> 0.18)
     base64 (0.3.0)
     bigdecimal (4.0.1)
     coderay (1.1.3)
     concurrent-ruby (1.3.6)
     connection_pool (2.5.5)
+    console (1.35.1)
+      fiber-annotation
+      fiber-local (~> 1.1)
+      json
     crack (1.0.1)
       bigdecimal
       rexml
@@ -33,10 +43,16 @@ GEM
       net-http-persistent (>= 4.0.4, < 5)
     faraday-retry (2.4.0)
       faraday (~> 2.0)
+    fiber-annotation (0.2.0)
+    fiber-local (1.1.0)
+      fiber-storage
+    fiber-storage (1.0.1)
     hashdiff (1.2.1)
     io-console (0.8.2)
+    io-event (1.16.0)
     json (2.7.6)
     method_source (1.1.0)
+    metrics (0.15.0)
     net-http-persistent (4.0.8)
       connection_pool (>= 2.2.4, < 4)
     parallel (1.24.0)
@@ -89,6 +105,7 @@ GEM
       rubocop-capybara (~> 2.17)
     ruby-progressbar (1.13.0)
     ruby2_keywords (0.0.5)
+    traces (0.18.2)
     unicode-display_width (2.6.0)
     vcr (6.1.0)
     webmock (3.26.1)
@@ -101,6 +118,7 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
+  async (~> 2.0)
   conductor_ruby!
   prometheus-client (~> 4.0)
   pry (~> 0.14)