railwatch 0.4.0 → 0.5.1

data/app/models/railwatch/telemetry/log.rb

@@ -77,6 +77,12 @@ module Railwatch
         def quote(term) = %("#{term.gsub('"', '""')}")
       end
 
+      def as_row
+        { id: id, level: level, message: message.first(2000), tags: tags, occurred_at: occurred_at, deploy: deploy,
+          execution_id: execution_id, execution_source: execution_source, execution_preview: execution_preview,
+          source: source, tenant: app_tenant, user_ref: user_ref, context: context }
+      end
+
       def timeline_label
         message.to_s.first(120)
       end

data/app/models/railwatch/telemetry/query.rb

@@ -42,6 +42,13 @@ module Railwatch
         text
       end
 
+      def as_row
+        { id: id, group_hash: group_hash, sql: sql.first(2_000), name: name, duration: duration_ms.round(3), occurred_at: occurred_at,
+          deploy: deploy, execution_id: execution_id, execution_preview: execution_preview, source: source,
+          connection: connection, role: role, adapter: adapter, row_count: row_count, tenant: app_tenant, user_ref: user_ref,
+          explain: explain.present? }
+      end
+
       def timeline_label
         sql.to_s.first(120)
       end

data/app/models/railwatch/telemetry/release_health.rb

@@ -36,13 +36,19 @@ module Railwatch
         }
       end
 
-      # Hourly points for the stacked sessions-by-status chart.
-      def self.series(deploy, from, to)
-        between(from, to).for_release(deploy).group(:bucket).order(:bucket)
-          .pluck(:bucket, Arel.sql("SUM(sessions)"), Arel.sql("SUM(sessions_errored)"), Arel.sql("SUM(sessions_crashed)"))
-          .map { |bucket, sessions, errored, crashed|
-            { t: bucket, sessions: sessions, ok: sessions - errored - crashed, errored: errored, crashed: crashed }
+      # Points for the stacked sessions-by-status chart, one per `step` across
+      # the window. The table is hourly and a session is counted once per hour
+      # it was seen, so a step under an hour is drawn at an hour: raw session
+      # rows would count a live session on every flush.
+      def self.series(deploy, from, to, step: nil)
+        step = [ Telemetry::Aggregations::STEPS.fetch(step || Telemetry::Aggregations.default_step(from, to)), 1.hour ].max
+        bucket = Telemetry::Aggregations.bucket_sql("bucket", step)
+        points = between(from, to).for_release(deploy).group(bucket).order(bucket)
+          .pluck(bucket, Arel.sql("SUM(sessions)"), Arel.sql("SUM(sessions_errored)"), Arel.sql("SUM(sessions_crashed)"))
+          .map { |b, sessions, errored, crashed|
+            { t: Time.at(b).utc, sessions: sessions, ok: sessions - errored - crashed, errored: errored, crashed: crashed }
           }
+        Telemetry::Aggregations.fill(points, from, to, step) { |t| { t: t, sessions: 0, ok: 0, errored: 0, crashed: 0 } }
       end
 
       # Each release's share of the window's sessions, as a percentage -- how

data/app/models/railwatch/telemetry/rollup.rb

@@ -54,7 +54,7 @@ module Railwatch
       # Aggregate a relation of rollups into one summary with merged percentiles.
       def self.summarize(relation)
         rows = relation.to_a
-        return { count: 0, errors: 0, client_errors: 0, avg: 0, p50: 0, p95: 0, p99: 0, max: 0 } if rows.empty?
+        return { count: 0, errors: 0, client_errors: 0, avg: 0, p50: 0, p95: 0, p99: 0, max: 0, extra: {} } if rows.empty?
         # merge! pushes the row's centroids into one accumulating digest.
         # `+` built a brand-new digest from both operands' centroids on every
         # row, so merging N rows re-pushed every earlier centroid N times:
@@ -70,9 +70,24 @@ module Railwatch
           p50: merged.percentile(0.5).to_i,
           p95: merged.percentile(0.95).to_i,
           p99: merged.percentile(0.99).to_i,
-          max: rows.map(&:duration_max).max
+          max: rows.map(&:duration_max).max,
+          # Everything a type puts in `extra` -- llm_call's cost_nanos and
+          # token counts, cache_event's hits and misses -- merged the way
+          # absorb! merges it: numbers add up, anything else is last-wins.
+          # Spend is a sum over a window rather than a percentile of
+          # durations, so a rule about money has nowhere else to read from.
+          extra: merge_extras(rows)
         }
       end
+
+      def self.merge_extras(rows)
+        rows.each_with_object({}) do |row, out|
+          row.extra.each do |key, value|
+            existing = out[key]
+            out[key] = existing.is_a?(Numeric) && value.is_a?(Numeric) ? existing + value : value
+          end
+        end
+      end
     end
   end
 end

data/app/models/railwatch/telemetry/tenant.rb

@@ -18,7 +18,6 @@ module Railwatch
       # aggregate), so only the busiest tenants get one; the rest report 0.
       P95_TENANTS = 50
       SPARKLINE_BUCKETS = 12
-      SERIES_BUCKETS = 48
       SORTS = { "requests" => :requests, "errors" => :errors, "p95" => :p95, "users" => :users }.freeze
 
       ERRORS_SQL = Arel.sql("SUM(CASE WHEN status >= 500 THEN 1 ELSE 0 END)")
@@ -71,21 +70,12 @@ module Railwatch
         }
       end
 
-      # Request volume and duration bucketed over the window, SeriesPoint-shaped
-      # so the same charts render it. Percentiles are approximations: these
-      # buckets come from raw rows, without the per-bucket t-digest
-      # Telemetry::Rollup keeps, so p50 is the bucket's average and p95/p99 its
-      # max.
-      def self.series(tenant, from, to)
-        width = bucket_width(from, to, SERIES_BUCKETS)
-        bucket = bucket_sql(from, width)
-        Telemetry::Execution.requests.between(from, to).where(app_tenant: tenant).group(bucket)
-          .pluck(bucket, COUNT_SQL, ERRORS_SQL, CLIENT_ERRORS_SQL, Arel.sql("SUM(duration)"), Arel.sql("MAX(duration)"))
-          .map { |index, count, errors, client_errors, sum, max|
-            avg = ms(sum / count)
-            { t: bucket_at(from, width, index, SERIES_BUCKETS).iso8601, count: count, errors: errors, client_errors: client_errors,
-              avg: avg, p50: avg, p95: ms(max), p99: ms(max) }
-          }.sort_by { |point| point[:t] }
+      # Request volume and duration bucketed over the window at `step`,
+      # SeriesPoint-shaped so the same charts render it. Rollups carry no tenant,
+      # so every step reads raw rows (Telemetry::Aggregations.points does that
+      # for a tenant), with exact percentiles per bucket.
+      def self.series(tenant, from, to, step: nil)
+        Telemetry::Aggregations.points("request", from: from, to: to, step: step, tenant: tenant)
       end
 
       def self.routes(tenant, from, to, limit: 20)
@@ -109,14 +99,9 @@ module Railwatch
         end
       end
 
-      # Same field shape as RequestsController#execution_row, for the tenant
-      # page's "Recent requests" table.
+      # The tenant page's "Recent requests" table.
       def self.recent_requests(tenant, from, to, limit: 50)
-        Telemetry::Execution.requests.between(from, to).where(app_tenant: tenant).recent.limit(limit).map do |r|
-          { execution_id: r.execution_id, name: r.name, status: r.status, duration: r.duration_ms.round(2), occurred_at: r.occurred_at,
-            user_ref: r.user_ref, tenant: r.app_tenant, exception_preview: r.exception_preview, inertia_component: r.inertia_component,
-            queries: r.counters["queries"], deploy: r.deploy }
-        end
+        Telemetry::Execution.requests.between(from, to).where(app_tenant: tenant).recent.limit(limit).map(&:as_row)
       end
 
       # -- Aggregation steps -----------------------------------------------------

data/app/models/railwatch/telemetry_record.rb

@@ -2,12 +2,14 @@
 
 module Railwatch
   # Base class for everything the engine stores about the host application.
-  # The hosted platform keeps one SQLite file per monitored environment through
-  # activerecord-tenanted; an embedded install monitors exactly one application,
-  # so this is a plain second database (`railwatch_telemetry` in the host's
-  # database.yml), separate from the host's own primary and from the engine's
-  # meta tables. Every telemetry query still runs inside
-  # Environment#with_telemetry so the code path matches the platform's.
+  # An embedded install monitors exactly one application, so this is a plain
+  # second database (`railwatch_telemetry` in the host's database.yml),
+  # separate from the host's own primary and from the engine's meta tables.
+  # The hosted platform keeps one SQLite file per monitored environment
+  # instead: it calls `Railwatch::TelemetryRecord.tenanted("telemetry")`
+  # (activerecord-tenanted) from an initializer, which replaces the
+  # connection below with a per-tenant one, and every telemetry query runs
+  # inside Environment#with_telemetry so the code path is the same in both.
   class TelemetryRecord < ActiveRecord::Base
     self.abstract_class = true
     begin

data/app/models/railwatch/threshold.rb

@@ -7,8 +7,22 @@ module Railwatch
     self.table_name = "railwatch_thresholds"
     MAX_LIMIT = 1_000_000_000
     MAX_WINDOW_MINUTES = 1_440
-    TARGET_KINDS = %w[requests jobs commands queries scheduled_tasks outgoing_requests].freeze
-    METRICS = %w[p95 max avg error_rate failure_rate missed].freeze
+    TARGET_KINDS = %w[requests jobs commands queries scheduled_tasks outgoing_requests
+                      llm_calls llm_tools].freeze
+    METRICS = %w[p95 max avg error_rate failure_rate missed spend tokens truncation_rate].freeze
+
+    # Duration and rate metrics read the same on any timed record, so they are
+    # allowed everywhere. Money and tokens only mean something where a record
+    # carries them: a spend rule on tool calls could never fire, and a rule
+    # that cannot fire is worse than no rule -- it reads as coverage.
+    SHARED_METRICS = %w[p95 max avg error_rate failure_rate missed].freeze
+    LLM_METRICS = %w[spend tokens truncation_rate].freeze
+
+    # Money leads with its symbol; milliseconds and percent follow the number.
+    # The old code assumed two units and branched on the metric name ending in
+    # "rate", which cannot express a dollar sign in front.
+    UNITS = { "spend" => "$", "tokens" => "", "truncation_rate" => "%",
+             "error_rate" => "%", "failure_rate" => "%" }.freeze
 
     def environment = Environment.current
 
@@ -20,10 +34,33 @@ module Railwatch
     validates :target, presence: true, length: { maximum: 256 }
     validates :limit, numericality: { less_than_or_equal_to: 100 }, if: -> { metric&.end_with?("rate") }
     validates :target, uniqueness: { scope: %i[environment_id target_kind metric] }
+    validate :metric_applies_to_target_kind
+
+    def self.metrics_for(target_kind)
+      target_kind == "llm_calls" ? SHARED_METRICS + LLM_METRICS : SHARED_METRICS
+    end
+
+    def unit = UNITS.fetch(metric, "ms")
+
+    # "$4.50", "2000ms", "5%", "150000" -- the symbol's position is part of
+    # the unit, not something a caller should have to know.
+    def format_value(value)
+      return "$#{value.is_a?(Float) ? format('%.2f', value) : value}" if unit == "$"
+
+      "#{value}#{unit}"
+    end
 
     def description
-      unit = metric.end_with?("rate") ? "%" : "ms"
-      "#{target_kind} #{target == '*' ? 'all' : target}: #{metric} over #{limit}#{unit} in #{window_minutes}m"
+      "#{target_kind} #{target == '*' ? 'all' : target}: #{metric} over #{format_value(limit)} in #{window_minutes}m"
+    end
+
+    private
+
+    def metric_applies_to_target_kind
+      return if metric.blank? || target_kind.blank?
+      return if Threshold.metrics_for(target_kind).include?(metric)
+
+      errors.add(:metric, "is not available for #{target_kind}")
     end
   end
 end

data/app/models/railwatch/window.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Railwatch
+  # The time range a telemetry page, API call, or MCP tool looks at: one of the
+  # fixed presets ("1h" .. "30d") ending now, or a custom [from, to] pair. The
+  # dashboard, the JSON API, and MCP all resolve their ?window= / "window"
+  # argument through here so the presets and the default agree everywhere.
+  class Window
+    PRESETS = { "1h" => 1.hour, "6h" => 6.hours, "24h" => 24.hours, "7d" => 7.days, "30d" => 30.days }.freeze
+    DEFAULT = "24h"
+    MAX_CUSTOM_RANGE = 90.days
+
+    attr_reader :key, :from, :to
+
+    # A preset key, or anything else for the default.
+    def self.preset(key)
+      key = PRESETS.key?(key.to_s) ? key.to_s : DEFAULT
+      to = Time.current
+      new(key, to - PRESETS[key], to)
+    end
+
+    # A custom range from ?from=&to= when both parse, are in order, and span
+    # no more than MAX_CUSTOM_RANGE; otherwise the preset (or default).
+    def self.parse(window: nil, from: nil, to: nil)
+      custom(from, to) || preset(window)
+    end
+
+    def self.custom(from, to)
+      from = parse_time(from) or return
+      to = to.blank? ? Time.current : parse_time(to) or return
+      new("custom", from, to) if to > from && (to - from) <= MAX_CUSTOM_RANGE
+    end
+
+    def self.parse_time(value)
+      return if value.blank?
+      Time.zone.parse(value.to_s)
+    rescue ArgumentError, TypeError
+      nil
+    end
+    private_class_method :parse_time
+
+    def initialize(key, from, to)
+      @key = key
+      @from = from
+      @to = to
+    end
+
+    def custom? = key == "custom"
+    def range = [ from, to ]
+    def span = to - from
+
+    # The same length immediately before this one, for "vs. previous period".
+    def previous
+      self.class.new(key, from - span, from)
+    end
+
+    def to_h
+      { from: from.iso8601(6), to: to.iso8601(6) }
+    end
+
+    # Query params that reproduce this window on another page.
+    def to_params
+      custom? ? to_h : { window: key }
+    end
+  end
+end

data/docs/embedded.md

@@ -44,6 +44,17 @@ an embedded install that has one configured still sends nothing.
 fails loudly if you ask for it and it cannot work. `railwatch:export:status`
 shows what is queued.
 
+## Railwatch Cloud runs the same models
+
+The hosted platform is this engine's telemetry layer plus what hosting adds
+(accounts, tokens, quotas, alert routing). It uses `Railwatch::Telemetry::*`,
+`Railwatch::Ingest::Batch`, `Railwatch::Telemetry::Aggregations` and the rest
+directly, with two seams: it tenants `Railwatch::TelemetryRecord` so each
+monitored environment gets its own database, and its `Environment` is an
+account-scoped Active Record row rather than the embedded singleton. Anything
+those models need from an environment is the surface `Railwatch::Environment`
+documents: `id`, `slug`, `name`, `with_telemetry`, and the display attributes.
+
 ## Install
 
 ```sh

data/lib/railwatch/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Railwatch
-  VERSION = "0.4.0"
+  VERSION = "0.5.1"
 end

data/lib/railwatch.rb

@@ -599,6 +599,18 @@ module Railwatch
     File.expand_path("../db/#{database}_migrate", __dir__)
   end
 
+  # Where links the models build (a trace from an execution page, a saved
+  # view's page) resolve. The engine's own routes serve the embedded
+  # dashboard; a host that mounts these pages on its own routes, as
+  # Railwatch Cloud does, points this at them.
+  def self.url_helpers
+    @url_helpers || Engine.routes.url_helpers
+  end
+
+  def self.url_helpers=(helpers)
+    @url_helpers = helpers
+  end
+
   # The one browser client, relative to the gem root. The dashboard bundle
   # is built from it, the install generator copies it, the gem ships it (the
   # only app/frontend file it does), and a host with its own frontend build