railwatch 0.1.4 → 0.2.0

data/app/models/railwatch/deploy.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Railwatch
+  class Deploy < ApplicationRecord
+    self.table_name = "railwatch_deploys"
+    def environment = Environment.current
+
+    validates :deploy, presence: true, uniqueness: { scope: :environment_id }
+    validates :deployed_at, presence: true
+    # Rendered as the "Open" link on the deploy page. Same rule as
+    # Application#repository_url, checked by parsing: one whole http(s) URL
+    # with a host, so a hook (or whoever holds its token) cannot put a
+    # javascript:/data: link, a hostless "https://?x", or an arbitrary
+    # off-site destination behind a trusted button.
+    validate :url_is_a_web_address
+
+    scope :recent, -> { order(deployed_at: :desc) }
+    scope :between, ->(from, to) { where(deployed_at: from..to) }
+
+    before_validation :assign_previous_ref
+    before_validation :trim_commits
+
+    def short_ref
+      ref.to_s.first(7).presence || deploy.first(12)
+    end
+
+    def commits_count
+      commits.size
+    end
+
+    # The deploy immediately before this one in the same environment.
+    def previous_deploy
+      environment.deploys.where(deployed_at: ...deployed_at).recent.first
+    end
+
+    # The stretch of time this release was live: from its own deploy until the
+    # next one, or until now for the current release. Release health is summed
+    # over this, not over the page's window.
+    def window
+      [ deployed_at, environment.deploys.where("deployed_at > ?", deployed_at).order(:deployed_at).first&.deployed_at || Time.current ]
+    end
+
+    private
+
+    def url_is_a_web_address
+      return if url.blank?
+      parsed = url.match?(/\A\S+\z/) ? URI.parse(url) : nil
+      return if parsed.is_a?(URI::HTTP) && parsed.host.present?
+      errors.add(:url, "must be a single http:// or https:// URL")
+    rescue URI::InvalidURIError
+      errors.add(:url, "must be a single http:// or https:// URL")
+    end
+
+    def assign_previous_ref
+      return if previous_ref.present? || deployed_at.blank?
+      self.previous_ref = previous_deploy&.ref
+    end
+
+    # The post-deploy hook sends its most recent commits (newest first) without
+    # knowing where the last deploy stopped, so cut the list at that commit.
+    def trim_commits
+      return if previous_ref.blank?
+      index = commits.index { |c| c["sha"].to_s.start_with?(previous_ref) }
+      self.commits = commits.first(index) if index
+    end
+  end
+end

data/app/models/railwatch/environment.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Railwatch
+  # The one environment an embedded install monitors: the host application in
+  # its current Rails.env. Not a table. The hosted platform's Environment is an
+  # account-scoped Active Record row with a token, quota and pause state; the
+  # telemetry, ingest and dashboard code only ever asks it for an id, a slug,
+  # a name, with_telemetry, and a few display attributes, so this stands in
+  # with exactly that surface.
+  class Environment
+    ID = 1
+
+    attr_reader :id, :name, :slug, :application_name
+
+    def self.current = @current ||= new
+
+    def self.find(id)
+      raise ActiveRecord::RecordNotFound, "Environment #{id}" unless id.to_i == ID
+      current
+    end
+
+    def initialize
+      @id = ID
+      @name = Rails.env.to_s
+      @application_name = Rails.application.class.module_parent_name
+      @slug = "#{@application_name.parameterize}-#{@name}"
+    end
+
+    def with_telemetry(&block) = TelemetryRecord.with_tenant(slug, &block)
+    def telemetry_exists? = true
+    def paused? = false
+    def token_prefix = "embedded"
+    def retention_days = 7
+    def last_seen_at = Railwatch::Embedded.last_seen_at
+    def application = Application.current
+    def issues = Issue.where(environment_id: ID)
+    def deploys = Deploy.where(environment_id: ID)
+    def saved_views = SavedView.where(environment_id: ID)
+    def thresholds = Threshold.where(environment_id: ID)
+    def anomaly_rules = AnomalyRule.where(environment_id: ID)
+    def events_this_month = 0
+    # The platform lets an account list the servers it expects to report so the
+    # dashboard can flag silent ones. One embedded install is its own server.
+    def expected_servers = []
+
+    # Ingest::Batch touches this in embedded mode; there is no row to update.
+    def update_columns(last_seen_at:) = Railwatch::Embedded.last_seen_at = last_seen_at
+
+    # GlobalID for Active Job arguments (RollupJob.perform_later(environment, bucket)).
+    include GlobalID::Identification
+    def to_global_id(...) = GlobalID.create(self, app: "railwatch")
+    def self.find_by_id(id) = find(id)
+  end
+end

data/app/models/railwatch/execution_presenter.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+module Railwatch
+  # Everything the execution detail page needs: the parent, its waterfall
+  # timeline of children, exceptions with frames, logs, and links to the
+  # enqueuing request or the jobs it enqueued.
+  class ExecutionPresenter
+    # The profile page renders up to 2 MiB of collapsed stacks; the execution
+    # page only carries an inline preview flamegraph alongside everything else
+    # it already ships, so it takes a smaller slice and links out when cut.
+    INLINE_COLLAPSED_BYTES = 512.kilobytes
+
+    # Everything an attachment row needs except `data`, which is the whole
+    # gzipped file and never belongs in a page prop.
+    ATTACHMENT_COLUMNS = %i[id name content_type bytes truncated occurred_at execution_stage].freeze
+
+    def initialize(execution, environment)
+      @exe = execution
+      @environment = environment
+    end
+
+    def props
+      @environment.with_telemetry do
+        {
+          execution: base,
+          timeline: timeline,
+          exceptions: @exe.exceptions.map { |e| exception_row(e) },
+          logs: @exe.logs.order(:occurred_at).limit(500).map { |l| { id: l.id, level: l.level, message: l.message, tags: l.tags, occurred_at: l.occurred_at, stage: l.execution_stage } },
+          queries: @exe.queries.order(:occurred_at).limit(500).with_sql.map { |q| { id: q.id, sql: q.sql, duration: q.duration_ms.round(3), source: q.source, group_hash: q.group_hash, row_count: q.row_count, stage: q.execution_stage, offset: offset(q) } },
+          spans: spans,
+          profile: profile_card,
+          attachments: attachment_rows.map { |a| attachment_row(a) },
+          enqueued_jobs: enqueued_jobs,
+          parent: parent,
+          trace: trace,
+          trace_url: trace_url,
+          issues: issues,
+          person: person
+        }
+      end
+    end
+
+    # Public so the issue page can build breadcrumbs from an occurrence's
+    # execution without re-implementing the per-type mapping.
+    def timeline_entries
+      timeline
+    end
+
+    private
+
+    def base
+      {
+        execution_id: @exe.execution_id, kind: @exe.kind, name: @exe.name, duration: @exe.duration_ms.round(3), status: @exe.status,
+        outcome: @exe.outcome, method: @exe.method, route: @exe.route, controller: @exe.controller, action: @exe.action,
+        queue: @exe.queue, attempt: @exe.attempt, queue_latency: @exe.queue_latency && (@exe.queue_latency / 1000.0).round(1),
+        queue_time: @exe.queue_time && (@exe.queue_time / 1000.0).round(1),
+        job_id: @exe.job_id, task_key: @exe.task_key, inertia_component: @exe.inertia_component,
+        occurred_at: @exe.occurred_at, deploy: @exe.deploy, server: @exe.server, user_ref: @exe.user_ref, tenant: @exe.app_tenant,
+        trace_id: @exe.trace_id, allocations: @exe.allocations, peak_memory: @exe.peak_memory, exception_preview: @exe.exception_preview,
+        profiled: profile.present?,
+        stages: @exe.stages.transform_values { |v| (v / 1000.0).round(3) }, counters: @exe.counters, detail: @exe.detail
+      }
+    end
+
+    def offset(row)
+      ((row.occurred_at - @exe.occurred_at) * 1000.0).round(3)
+    end
+
+    # Rich waterfall entries for the Timeline component: unlike the model's
+    # generic `timeline_label`, this keeps type-specific fields (sql, status,
+    # subject, level...) so the frontend can render a real hover/detail panel
+    # instead of a truncated string.
+    def timeline
+      entries = []
+      @exe.queries.with_sql.each { |q| entries << { type: "query", id: q.id, offset: offset(q), duration: q.duration_ms, stage: q.execution_stage,
+        label: q.sql.to_s.first(120), sql: q.sql, source: q.source, detail: { "rows" => q.row_count, "connection" => q.connection } } }
+      @exe.cache_events.each { |c| entries << { type: "cache_event", id: c.id, offset: offset(c), duration: c.duration_ms, stage: c.execution_stage,
+        label: "#{c.type} #{c.key}".first(120), source: nil, detail: { "key" => c.key, "op" => c.type, "store" => c.store, "hits" => c.hits, "ttl" => c.ttl } } }
+      @exe.outgoing_requests.each { |o| entries << { type: "outgoing_request", id: o.id, offset: offset(o), duration: o.duration_ms, stage: o.execution_stage,
+        label: o.url.to_s.first(120), source: o.source, detail: { "method" => o.method, "url" => o.url, "status" => o.status_code, "host" => o.host, "error" => o.error, "body" => o.response_body } } }
+      @exe.mails.each { |m| entries << { type: "mail", id: m.id, offset: offset(m), duration: m.duration_ms, stage: m.execution_stage,
+        label: m.mailer.to_s.first(120), source: nil, detail: { "subject" => m.subject, "mailer" => m.mailer, "to" => m.to } } }
+      @exe.logs.each { |l| entries << { type: "log", id: l.id, offset: offset(l), duration: l.duration_ms, stage: l.execution_stage,
+        label: l.message.to_s.first(120), source: l.source, detail: { "level" => l.level, "message" => l.message.to_s.first(500) } } }
+      @exe.exceptions.each { |e| entries << { type: "exception", id: e.id, offset: offset(e), duration: e.duration_ms, stage: e.execution_stage,
+        label: "#{e.class_name}: #{e.message.to_s.first(100)}", source: (e.file ? "#{e.file}:#{e.line}" : nil), detail: { "class" => e.class_name, "message" => e.message.to_s.first(300), "handled" => e.handled } } }
+      @exe.broadcasts.each { |b| entries << { type: "broadcast", id: b.id, offset: offset(b), duration: b.duration_ms, stage: b.execution_stage,
+        label: b.channel.to_s.first(120), source: nil, detail: { "channel" => b.channel, "action" => b.action, "stream" => b.stream } } }
+      @exe.storage_ops.each { |s| entries << { type: "storage_op", id: s.id, offset: offset(s), duration: s.duration_ms, stage: s.execution_stage,
+        label: "#{s.op} #{s.key}".first(120), source: nil, detail: { "op" => s.op, "key" => s.key, "service" => s.service } } }
+      @exe.view_renders.each { |v| entries << { type: "view_render", id: v.id, offset: offset(v), duration: v.duration_ms, stage: v.execution_stage,
+        label: v.identifier.to_s.first(120), source: nil, detail: { "count" => v.count, "cache_hits" => v.cache_hits } } }
+      @exe.enqueued_jobs.each { |j| entries << { type: "enqueued_job", id: j.id, offset: offset(j), duration: j.duration_ms, stage: j.execution_stage,
+        label: j.name.to_s.first(120), source: nil, detail: { "queue" => j.queue, "job_id" => j.job_id } } }
+      @exe.spans.each { |s| entries << { type: "span", id: s.id, offset: offset(s), duration: s.duration_ms, stage: s.execution_stage,
+        label: s.name.to_s.first(120), source: nil, detail: { "status" => s.status }.merge(s.payload) } }
+      @exe.transactions.each { |t| entries << { type: "transaction", id: t.id, offset: offset(t), duration: t.duration_ms, stage: t.execution_stage,
+        label: t.outcome.to_s.first(120), source: nil, detail: { "outcome" => t.outcome, "connection" => t.connection } } }
+      @exe.llm_calls.each { |c| entries << { type: "llm_call", id: c.id, offset: offset(c), duration: c.duration_ms, stage: c.execution_stage,
+        label: c.timeline_label.first(120), source: nil, detail: { "operation" => c.operation, "provider" => c.provider, "model" => c.model,
+          "tool" => c.tool_name, "input_tokens" => c.input_tokens, "output_tokens" => c.output_tokens, "cost" => c.cost,
+          "status" => c.status, "error" => c.error, "workflow" => c.workflow_name, "step" => c.workflow_step_name } } }
+      attachment_rows.each { |a| entries << { type: "attachment", id: a.id, offset: offset(a), duration: nil, stage: a.execution_stage,
+        label: a.name.to_s.first(120), source: nil, detail: { "name" => a.name, "content_type" => a.content_type, "bytes" => a.bytes, "truncated" => a.truncated } } }
+      entries.each { |e| e[:duration] = e[:duration]&.round(3) }
+      entries.sort_by { |e| e[:offset] }
+    end
+
+    def exception_row(e)
+      { id: e.id, class_name: e.class_name, message: e.message, handled: e.handled, severity: e.severity, source: e.source,
+        file: e.file, line: e.line, frames: e.frames, cause: e.cause, locals: e.locals, context: e.context, occurred_at: e.occurred_at, group_hash: e.group_hash }
+    end
+
+    def spans
+      @exe.spans.order(:occurred_at).limit(200).map do |s|
+        { id: s.id, name: s.name, duration: s.duration_ms&.round(3), status: s.status, attributes: s.payload,
+          offset: offset(s), stage: s.execution_stage, occurred_at: s.occurred_at }
+      end
+    end
+
+    # The execution's profile, if one was shipped. Looked up by execution_id
+    # rather than through the denormalised executions.profile_id so a profile
+    # that arrived in a later batch than its execution still shows up.
+    def profile
+      return @profile if defined?(@profile)
+      @profile = @exe.profiles.recent.first
+    end
+
+    def profile_card
+      row = profile or return nil
+      collapsed, truncated = row.collapsed_capped(INLINE_COLLAPSED_BYTES)
+      { id: row.id, profiler: row.profiler, mode: row.mode, interval: row.interval, duration: row.duration_ms.round(2),
+        samples: row.samples, stacks_bytes: row.stacks_bytes, collapsed: collapsed, truncated: truncated }
+    rescue Telemetry::BoundedGzip::Error
+      nil
+    end
+
+    def attachment_rows
+      @attachment_rows ||= @exe.attachments.order(:occurred_at).limit(50).select(*ATTACHMENT_COLUMNS).to_a
+    end
+
+    def attachment_row(a)
+      { id: a.id, name: a.name, content_type: a.content_type, bytes: a.bytes, truncated: a.truncated,
+        viewable: a.viewable?, occurred_at: a.occurred_at }
+    end
+
+    def enqueued_jobs
+      @exe.enqueued_jobs.map do |j|
+        attempt = Telemetry::Execution.jobs.find_by(job_id: j.job_id)
+        { id: j.id, name: j.name, queue: j.queue, job_id: j.job_id, scheduled_at: j.scheduled_at, offset: offset(j),
+          attempt_execution_id: attempt&.execution_id, attempt_outcome: attempt&.outcome }
+      end
+    end
+
+    def parent
+      return nil unless @exe.kind == "job_attempt" && @exe.trace_id
+      p = Telemetry::Execution.where(trace_id: @exe.trace_id).where.not(execution_id: @exe.execution_id).order(:occurred_at).first
+      p && { execution_id: p.execution_id, kind: p.kind, name: p.name }
+    end
+
+    def trace
+      @trace ||= Telemetry::Execution.where(trace_id: @exe.trace_id).order(:occurred_at).limit(50)
+        .map { |e| { execution_id: e.execution_id, kind: e.kind, name: e.name, duration: e.duration_ms.round(1), status: e.status, outcome: e.outcome,
+          occurred_at: e.occurred_at, parent_id: e.parent_id, server: e.server, current: e.execution_id == @exe.execution_id } }
+    end
+
+    # Only worth linking out to the distributed trace page when this execution
+    # is not the whole trace.
+    def trace_url
+      return nil unless @exe.trace_id && trace.size > 1
+      Railwatch::Engine.routes.url_helpers.application_environment_trace_path(@environment.application, @environment, @exe.trace_id)
+    end
+
+    def issues
+      groups = @exe.exceptions.map(&:group_hash).uniq
+      @environment.issues.where(group_hash: groups).map { |i| { id: i.id, key: i.key, title: i.title, status: i.status, group_hash: i.group_hash } }
+    end
+
+    def person
+      return nil unless @exe.user_ref
+      p = Telemetry::Person.find_by(ref: @exe.user_ref) or return nil
+      { ref: p.ref, name: p.display_name, email: p.email }
+    end
+  end
+end

data/app/models/railwatch/filter_query.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Railwatch
+  # Parses and applies the "key:value key2:value2 free text" grammar shared by
+  # telemetry pages, REST endpoints, and MCP tools.
+  module FilterQuery
+    TOKEN = /\A([a-z_]+):(\S+)\z/
+    EXECUTION_KINDS = %w[request job scheduled_task command].freeze
+    LOG_LEVELS = %w[debug info warn error fatal event unknown].freeze
+    HANDLED_VALUES = %w[true false].freeze
+
+    COMMON_FIELDS = %w[after before user tenant deploy kind].freeze
+    RESOURCE_FIELDS = {
+      jobs: %w[class job_id outcome queue status],
+      exceptions: %w[source class handled severity status],
+      logs: %w[source level status],
+      queries: %w[source adapter connection role]
+    }.freeze
+
+    def self.parse(query)
+      text = []
+      fields = {}
+      query.to_s.split(/\s+/).each do |word|
+        if (m = TOKEN.match(word))
+          fields[m[1]] = m[2]
+        elsif word.present?
+          text << word
+        end
+      end
+      { text: text.join(" "), fields: fields }
+    end
+
+    # "5xx" -> 500..599, "404" -> 404..404, anything else -> nil
+    def self.status_range(value)
+      case value.to_s
+      when /\A([2-5])xx\z/i then ($1.to_i * 100)..($1.to_i * 100 + 99)
+      when /\A\d+\z/ then value.to_i..value.to_i
+      end
+    end
+
+    def self.fields_for(resource)
+      COMMON_FIELDS + RESOURCE_FIELDS.fetch(resource.to_sym)
+    end
+
+    def self.cursor_context(environment_id:, resource:, query:, window:)
+      Digest::SHA256.hexdigest([ environment_id, resource, query.to_s, window ].to_json)
+    end
+
+    # Applies the same telemetry grammar for the web UI, REST API, and MCP.
+    # The supplied window remains the outer bound; after:/before: may only
+    # narrow it. Unknown fields are inert, and every value is bound through
+    # Active Record rather than interpolated into SQL.
+    def self.apply(scope, resource:, query:, from:, to:, except: [])
+      resource = resource.to_sym
+      parsed = parse(query)
+      fields = parsed[:fields].except(*Array(except).map(&:to_s))
+      scope = scope.where(occurred_at: bounded_time_range(fields, from, to))
+      scope = apply_common(scope, fields)
+
+      case resource
+      when :jobs then apply_jobs(scope, fields, parsed[:text])
+      when :exceptions then apply_exceptions(scope, fields, parsed[:text])
+      when :logs then apply_logs(scope, fields, parsed[:text])
+      when :queries then apply_queries(scope, fields, parsed[:text])
+      else raise ArgumentError, "unsupported telemetry resource: #{resource}"
+      end
+    end
+
+    def self.bounded_time_range(fields, from, to)
+      after = parse_time(fields["after"])
+      before = parse_time(fields["before"])
+      lower = [ from, after ].compact.max
+      upper = [ to, before ].compact.min
+      lower <= upper ? lower..upper : (lower...lower)
+    end
+    private_class_method :bounded_time_range
+
+    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 self.apply_common(scope, fields)
+      scope = scope.where(user_ref: fields["user"]) if fields["user"].present?
+      scope = scope.where(app_tenant: fields["tenant"]) if fields["tenant"].present?
+      scope = scope.where(deploy: fields["deploy"]) if fields["deploy"].present?
+      if fields["source"].present?
+        if EXECUTION_KINDS.include?(fields["source"].to_s) && scope.klass.column_names.include?("execution_source")
+          scope = scope.where(execution_source: fields["source"])
+        elsif scope.klass.column_names.include?("source")
+          pattern = "#{scope.klass.sanitize_sql_like(fields["source"])}%"
+          scope = scope.where(scope.klass.arel_table[:source].matches(pattern))
+        end
+      end
+      scope = scope.where(execution_source: fields["kind"]) if EXECUTION_KINDS.include?(fields["kind"].to_s) && scope.klass.column_names.include?("execution_source")
+      scope
+    end
+    private_class_method :apply_common
+
+    def self.apply_jobs(scope, fields, text)
+      outcome = fields["outcome"].presence || fields["status"].presence
+      scope = scope.where(queue: fields["queue"]) if fields["queue"].present?
+      scope = scope.where(outcome: outcome) if outcome
+      scope = scope.where(name: fields["class"]) if fields["class"].present?
+      scope = scope.where(job_id: fields["job_id"]) if fields["job_id"].present?
+      return scope unless text.present?
+      pattern = "%#{Telemetry::Execution.sanitize_sql_like(text)}%"
+      scope.where("name LIKE :pattern OR exception_preview LIKE :pattern", pattern: pattern)
+    end
+    private_class_method :apply_jobs
+
+    def self.apply_exceptions(scope, fields, text)
+      handled = fields["handled"]
+      handled ||= { "handled" => "true", "unhandled" => "false" }[fields["status"]]
+      scope = scope.where(class_name: fields["class"]) if fields["class"].present?
+      scope = scope.where(handled: handled == "true") if HANDLED_VALUES.include?(handled.to_s)
+      scope = scope.where(severity: fields["severity"]) if fields["severity"].present?
+      return scope unless text.present?
+      pattern = "%#{Telemetry::Exception.sanitize_sql_like(text)}%"
+      scope.where("message LIKE :pattern OR class_name LIKE :pattern", pattern: pattern)
+    end
+    private_class_method :apply_exceptions
+
+    def self.apply_logs(scope, fields, text)
+      level = fields["level"].presence || fields["status"].presence
+      scope = scope.where(level: level) if LOG_LEVELS.include?(level.to_s)
+      text.present? ? scope.fts(text) : scope
+    end
+    private_class_method :apply_logs
+
+    def self.apply_queries(scope, fields, text)
+      %w[adapter connection role].each do |field|
+        scope = scope.where(field => fields[field]) if fields[field].present?
+      end
+      return scope unless text.present?
+      scope.matching(text)
+    end
+    private_class_method :apply_queries
+  end
+end

data/app/models/railwatch/followup_receipt.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Railwatch
+  # One row per (batch, exception group) whose occurrences have been counted
+  # onto an issue. Lives beside the issues, in the same database and the same
+  # transaction as the count, so "did this batch's exceptions already reach
+  # this issue" has exactly one answer however many times the follow-up runs.
+  class FollowupReceipt < ApplicationRecord
+    self.table_name = "railwatch_followup_receipts"
+
+    # Receipts outlive their batch's ledger row by this much; a replay after
+    # that is one the ledger no longer knows about either.
+    RETENTION = 30.days
+
+    # True when this call is the first for the pair: the caller's work is
+    # owed. False when a receipt already exists: the work was done, skip it.
+    # Must run inside a transaction on this database with the work itself.
+    def self.claim!(batch_id:, group_hash:)
+      insert({ batch_id: batch_id, group_hash: group_hash, created_at: Time.current },
+             unique_by: %i[batch_id group_hash]).rows.any?
+    end
+
+    def self.prune!(now: Time.current)
+      where(created_at: ...(now - RETENTION)).delete_all
+    end
+  end
+end