flare 0.4.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c94277634cce4170817b717f3ff6b3cb99ac980908f51ed6aaa6ba07a8c59de6
-  data.tar.gz: 4d882034612ac608246ea1a3f232a5f491c283d97b6082a97115f60f0b80fdf5
+  metadata.gz: 1bc922e7eef0dab2d93ab0a6d765a6d5cc5f1dbf40f322774fe6e8ceb146d626
+  data.tar.gz: 9bab57b668d51b8c7d2047611443bf36dfb77fa76d7827acc4444749c622529b
 SHA512:
-  metadata.gz: f8cfaf0827068925802b90582a3c12a2513649db82b23e51509ed689c111cfcbcd7397c2c260d13934dadfe3a2899481925875faf0bc75f3262c326fa8718e63
-  data.tar.gz: 38727869b8f7ebf8283354a7c696aded643a5da8260bce61d2ddacb4e6e441868d72eed7c01766b9e8d83d2d95954b1fab2fd75e8cdd1bf7adfabef3d23e4ae5
+  metadata.gz: 28b4a678ea6563eba5449a5864953cefa7218eb4531de4a8deeb33ead3d9bc5a138ee4f310b01b147b808e820c2091494116beae9ebc0fb8db614f8a8c0eb7a5
+  data.tar.gz: 45b32e82c6b8e4470d09eab648911541a1a7f76414b16f4d2b53cac2a11628f4f8b7b04b144bc55ef03f03d4849f6b39756b65bedbd7511f5cfe6f01980b89b1

data/README.md

@@ -60,8 +60,58 @@ To enable metrics, set `FLARE_KEY` in your environment (get one at [flare.am](ht
 flare setup    # Authenticate and configure Flare
 flare doctor   # Check your setup for issues
 flare status   # Show current configuration
+flare requests # List recent requests from local development spans
+flare request  # Show one request's timeline from local development spans
+flare nplus1   # Find queries repeated within recent requests from local development spans
 ```
 
+`flare requests` reads the local spans database, so you or a coding agent can make a request and check its duration and query count without opening `/flare`:
+
+```bash
+$ bundle exec flare requests --last 2
+2026-10-27T20:14:03.412-04:00  GET     200       48.2ms    12 queries  /posts  PostsController#index  4bf92f3577b34da6a3ce929d0e0e4736
+2026-10-27T20:13:41.087-04:00  GET     404        3.0ms     1 queries  /posts/9  PostsController#show  0af7651916cd43dd8448eb211c80319c
+```
+
+`flare request <trace_id>` shows what one of those requests did, in order, with the code that ran each query:
+
+```bash
+$ bundle exec flare request 4bf92f3577b34da6a3ce929d0e0e4736
+GET /posts  200  48.2ms  PostsController#index
+Started 2026-10-27T20:14:03.412-04:00  12 queries
+
+   offset  duration
+    1.2ms     0.4ms  sql.active_record: SELECT "posts".* FROM "posts"  app/controllers/posts_controller.rb:5
+    2.1ms     0.2ms  sql.active_record: SELECT "users".* FROM "users" WHERE "users"."id" = ?  app/views/posts/index.html.erb:3
+```
+
+`flare nplus1` checks recent requests for the same query running more than once, ignoring the values bound to it, and names the code that ran it. Add `--last N` to check more or fewer requests than the default 10:
+
+```bash
+$ bundle exec flare nplus1
+GET /posts  200  48.2ms  PostsController#index  4bf92f3577b34da6a3ce929d0e0e4736
+  10x     2.3ms  SELECT "users".* FROM "users" WHERE "users"."id" = ?
+     10x  app/views/posts/index.html.erb:3
+```
+
+All three commands take `--json` for machine-readable output and `--db PATH` if you changed `database_path`.
+
+### Coding agents
+
+Add something like this to your app's `AGENTS.md` or `CLAUDE.md` so coding agents (Claude Code, Codex, Cursor) use these commands:
+
+```markdown
+## Checking performance
+
+Flare records every request in development. After changing a controller, view or query, make the request, then:
+
+- `bundle exec flare requests --last 1 --json` shows its duration, query count and trace_id
+- `bundle exec flare nplus1 --last 1 --json` shows any query it ran more than once, with the code that ran it
+- `bundle exec flare request <trace_id> --json` shows every query in order, when you need the full timeline
+```
+
+No Flare account or network access needed.
+
 ## Configuration
 
 All configuration is optional. Flare works out of the box with sensible defaults.
@@ -87,6 +137,11 @@ Flare.configure do |config|
 
   # Subscribe to custom notification prefixes (default: ["app."])
   config.subscribe_patterns << "mycompany."
+
+  # The deployed revision, shown as deploy markers on your charts
+  # (default: FLARE_REVISION, then your platform's commit variable, a
+  # REVISION file, or git rev-parse HEAD)
+  config.revision = ENV["MY_BUILD_SHA"]
 end
 ```
 
@@ -135,13 +190,17 @@ Flare uses [OpenTelemetry](https://opentelemetry.io/) for instrumentation. It au
 
 Spans are stored in a local SQLite database (`db/flare.sqlite3` by default) and automatically pruned based on retention settings.
 
+### What leaves your app
+
+Captured traces go through your app's `config.filter_parameters` before upload, including query strings, along with a default list of common credential names. SQL statements have their values replaced with `?`, Redis statements keep the command and the key's first segment, MongoDB commands keep their structure with values masked, URLs lose their userinfo and fragments, and mail recipients, subjects, job arguments and exception contents are left out. Cache keys keep only their leading word. Metrics carry names (controller, job, table, operation, host), not values, plus your app's deployed revision (usually a git SHA) so Flare can mark deploys. Your local development database and dashboard keep the full values, except Redis arguments, which aren't kept anywhere.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/jnunemaker/flare.
+Bug reports and pull requests are welcome on GitHub at https://github.com/verygoodsoftwarellc/flare-gem.
 
 ## License
 

data/app/controllers/flare/jobs_controller.rb

@@ -14,7 +14,7 @@ module Flare
         name: params[:name].presence
       }
       # Fetch one extra to know if there's a next page
-      jobs = Flare.storage.list_jobs(**filter_params, limit: PER_PAGE + 1, offset: @offset)
+      jobs = Flare.storage.list_jobs(**filter_params, sort: params[:sort], limit: PER_PAGE + 1, offset: @offset)
       @total_count = Flare.storage.count_jobs(**filter_params)
       @has_next = jobs.size > PER_PAGE
       @jobs = jobs.first(PER_PAGE)

data/app/controllers/flare/requests_controller.rb

@@ -17,7 +17,7 @@ module Flare
         origin: current_origin
       }
       # Fetch one extra to know if there's a next page
-      requests = Flare.storage.list_requests(**filter_params, limit: PER_PAGE + 1, offset: @offset)
+      requests = Flare.storage.list_requests(**filter_params, sort: params[:sort], limit: PER_PAGE + 1, offset: @offset)
       @total_count = Flare.storage.count_requests(**filter_params)
       @has_next = requests.size > PER_PAGE
       @requests = requests.first(PER_PAGE)

data/app/controllers/flare/spans_controller.rb

@@ -64,7 +64,7 @@ module Flare
       @offset = params[:offset].to_i
       filter_params = { name: params[:name].presence }
 
-      spans = Flare.storage.list_spans_by_category(category, **filter_params, limit: PER_PAGE + 1, offset: @offset)
+      spans = Flare.storage.list_spans_by_category(category, **filter_params, sort: params[:sort], limit: PER_PAGE + 1, offset: @offset)
       @total_count = Flare.storage.count_spans_by_category(category, **filter_params)
       @has_next = spans.size > PER_PAGE
       @spans = spans.first(PER_PAGE)

data/app/helpers/flare/application_helper.rb

@@ -100,6 +100,29 @@ module Flare
       end
     end
 
+    def bookkeeping_query?(span)
+      Storage::SQLite.bookkeeping_query?(span[:properties] || {})
+    end
+
+    def sorted_by_slowest?
+      params[:sort] == "slowest"
+    end
+
+    # Links the Duration heading to the slowest first, or back to newest first,
+    # keeping the filters and starting again from the first page.
+    def duration_sort_link
+      query = request.query_parameters.except("offset", "sort")
+      label, css, title = "Duration", "sort-link", "Sort by slowest first"
+
+      if sorted_by_slowest?
+        label, css, title = "Duration \u2193", "sort-link active", "Back to newest first"
+      else
+        query = query.merge("sort" => "slowest")
+      end
+
+      link_to label, [request.path, query.to_query.presence].compact.join("?"), class: css, title: title
+    end
+
     def format_duration(ms)
       return "-" if ms.nil?
 

data/app/views/flare/jobs/index.html.erb

@@ -2,6 +2,7 @@
   <h1 class="page-title"><%= page_title %></h1>
   <div class="filters">
     <%= form_tag(jobs_path, method: :get, id: "filter-form") do %>
+      <%= hidden_field_tag :sort, "slowest" if sorted_by_slowest? %>
       <%= text_field_tag :name, params[:name], placeholder: "Search...", class: "filter-select", style: "min-width: 200px;", onchange: "this.form.submit()" %>
     <% end %>
   </div>
@@ -23,7 +24,7 @@
           <thead>
             <tr>
               <th>Job</th>
-              <th style="width: 100px; text-align: right;">Duration</th>
+              <th style="width: 100px; text-align: right;"><%= duration_sort_link %></th>
               <th style="width: 120px; text-align: right;">Happened</th>
             </tr>
           </thead>

data/app/views/flare/requests/index.html.erb

@@ -2,6 +2,7 @@
   <h1 class="page-title"><%= page_title %></h1>
   <div class="filters">
     <%= form_tag(requests_path, method: :get, id: "filter-form") do %>
+      <%= hidden_field_tag :sort, "slowest" if sorted_by_slowest? %>
       <%= select_tag :origin,
         options_for_select([
           ["All Origins", ""],
@@ -54,7 +55,7 @@
               <th>Name</th>
               <th style="width: 70px;">Verb</th>
               <th style="width: 80px; text-align: right;">Status</th>
-              <th style="width: 100px; text-align: right;">Duration</th>
+              <th style="width: 100px; text-align: right;"><%= duration_sort_link %></th>
               <th style="width: 120px; text-align: right;">Happened</th>
             </tr>
           </thead>

data/app/views/flare/requests/show.html.erb

@@ -1,9 +1,9 @@
 <%
   # Get root span properties
   root_props = @root_span ? @root_span[:properties] : {}
-  http_method = root_props["http.request.method"]
-  http_status = root_props["http.response.status_code"]
-  http_target = root_props["url.path"]
+  http_method = root_props["http.request.method"] || root_props["http.method"]
+  http_status = root_props["http.response.status_code"] || root_props["http.status_code"]
+  http_target = root_props["url.path"] || root_props["http.target"]
   controller = root_props["code.namespace"]
   action = root_props["code.function"]
 
@@ -306,6 +306,7 @@
       name: span[:name],
       duration_ms: span[:duration_ms],
       offset_ms: (span[:start_timestamp] - root_start) / 1_000_000.0,
+      bookkeeping: bookkeeping_query?(span),
       properties: span[:properties]
     }
   }.to_json.html_safe %>;
@@ -334,9 +335,10 @@
     output.push('> Given this Rails request trace, how would you improve performance? What information is missing that would help diagnose issues?');
     output.push('');
 
-    const method = requestData.http_method || 'GET';
+    // The method and path, else the span name, which often has the method already.
+    const title = requestData.http_method && requestData.http_target ? requestData.http_method + ' ' + requestData.http_target : requestData.name;
     const status = requestData.http_status || '200';
-    output.push('# ' + method + ' ' + requestData.name + ' [' + status + '] - ' + formatDuration(requestData.duration_ms));
+    output.push('# ' + title + ' [' + status + '] - ' + formatDuration(requestData.duration_ms));
     if (requestData.controller && requestData.action) {
       output.push('Controller: ' + requestData.controller + '#' + requestData.action);
     }
@@ -346,10 +348,17 @@
     output.push('');
     output.push('- **Total:** ' + formatDuration(requestData.duration_ms));
 
-    const sqlSpans = spansData.filter(function(s) { return getSpanCategory(s.name) === 'sql'; });
+    // Count and rank the app's queries the way flare requests does, so
+    // schema lookups and BEGIN/COMMIT don't pass for slow app queries.
+    const sqlSpans = spansData.filter(function(s) { return getSpanCategory(s.name) === 'sql' && !s.bookkeeping; });
     if (sqlSpans.length > 0) {
       const sqlTotalMs = sqlSpans.reduce(function(sum, s) { return sum + (s.duration_ms || 0); }, 0);
-      output.push('- **SQL:** ' + sqlSpans.length + ' queries, ' + formatDuration(sqlTotalMs) + ' total');
+      const bookkeepingCount = spansData.filter(function(s) { return s.bookkeeping; }).length;
+      let sqlLine = '- **SQL:** ' + sqlSpans.length + ' queries, ' + formatDuration(sqlTotalMs) + ' total';
+      if (bookkeepingCount > 0) {
+        sqlLine += ' (plus ' + bookkeepingCount + ' schema and transaction statements from Active Record)';
+      }
+      output.push(sqlLine);
 
       const slowest = sqlSpans.slice().sort(function(a, b) { return (b.duration_ms || 0) - (a.duration_ms || 0); }).slice(0, 3);
       if (slowest.length > 0 && slowest[0].duration_ms > 1) {

data/app/views/flare/spans/index.html.erb

@@ -6,6 +6,7 @@
   <h1 class="page-title"><%= page_title %></h1>
   <div class="filters">
     <%= form_tag(current_path, method: :get, id: "filter-form") do %>
+      <%= hidden_field_tag :sort, "slowest" if sorted_by_slowest? %>
       <%= text_field_tag :name, params[:name], placeholder: "Search...", class: "filter-select", style: "min-width: 200px;", onchange: "this.form.submit()" %>
     <% end %>
   </div>
@@ -33,7 +34,7 @@
               <% elsif @category == "cache" %>
                 <th style="width: 100px; text-align: right;">Operation</th>
               <% end %>
-              <th style="width: 100px; text-align: right;">Duration</th>
+              <th style="width: 100px; text-align: right;"><%= duration_sort_link %></th>
               <th style="width: 120px; text-align: right;">Happened</th>
             </tr>
           </thead>

data/lib/flare/cli/doctor_command.rb

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
 
 require_relative "output"
+require_relative "project"
 
 module Flare
   class DoctorCommand
     include CLI::Output
+    include CLI::Project
 
     def run
       puts bold("Flare Doctor")
@@ -62,7 +64,7 @@ module Flare
 
       contents = File.read(gitignore_path)
       missing = []
-      missing << ".env" unless contents.match?(/^\.env$/)
+      missing << ".env" if key_in_dotenv? && !env_ignored?(contents)
       missing << "flare.sqlite3*" unless contents.include?("flare.sqlite3")
 
       if missing.empty?
@@ -99,16 +101,7 @@ module Flare
     end
 
     def key_configured?
-      return true if ENV["FLARE_KEY"] && !ENV["FLARE_KEY"].empty?
-
-      env_path = File.join(Dir.pwd, ".env")
-      File.exist?(env_path) && File.read(env_path).match?(/^FLARE_KEY=.+/)
-    end
-
-    def credentials_exist?
-      %w[config/credentials.yml.enc config/credentials/production.yml.enc].any? do |path|
-        File.exist?(File.join(Dir.pwd, path))
-      end
+      (ENV["FLARE_KEY"] && !ENV["FLARE_KEY"].empty?) || key_in_dotenv?
     end
 
     def spans_expected?

data/lib/flare/cli/local_spans.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "time"
+
+module Flare
+  module CLI
+    # Read-only access to the local development spans database, for commands
+    # that inspect it from the terminal. Explains a missing or unreadable
+    # database and exits rather than printing a backtrace.
+    module LocalSpans
+      DEFAULT_LIMIT = 10
+
+      private
+
+      # Parses the options these commands share, returning the other arguments.
+      # Pass last_help for commands that read several requests.
+      def parse_options(argv, banner:, last_help: nil)
+        @limit = DEFAULT_LIMIT
+        @json = false
+        @database_path = default_database_path
+
+        OptionParser.new do |opts|
+          opts.banner = banner
+          if last_help
+            opts.on("--last N", Integer, "#{last_help} (default: #{DEFAULT_LIMIT})") do |n|
+              raise OptionParser::InvalidArgument, "#{n} (must be at least 1)" if n < 1
+
+              @limit = n
+            end
+          end
+          opts.on("--json", "Print JSON instead of text") { @json = true }
+          opts.on("--db PATH", "Spans database (default: db/flare.sqlite3)") { |path| @database_path = File.expand_path(path) }
+        end.parse!(argv)
+      rescue OptionParser::ParseError => e
+        $stderr.puts e.message
+        exit 1
+      end
+
+      def default_database_path
+        File.join(Dir.pwd, "db", "flare.sqlite3")
+      end
+
+      # The fields every request-reading command reports, so their JSON stays
+      # in step.
+      def request_summary(span, method:, path:, status:, controller:, action:, queries:)
+        {
+          trace_id: span[:trace_id],
+          method: method,
+          path: path,
+          status: status,
+          duration_ms: span[:duration_ms].round(1),
+          queries: queries,
+          controller: controller,
+          action: action,
+          started_at: Time.at(span[:start_timestamp] / 1_000_000_000r).iso8601(3),
+        }
+      end
+
+      def recent_requests(storage, limit)
+        requests = storage.list_requests(limit: limit)
+        query_counts = storage.count_queries_by_trace(requests.map { |r| r[:trace_id] })
+
+        requests.map do |r|
+          request_summary(r, method: r[:http_method], path: r[:http_target], status: r[:http_status],
+            controller: r[:controller], action: r[:action], queries: query_counts.fetch(r[:trace_id], 0))
+        end
+      end
+
+      def source_location(props)
+        return unless props["code.filepath"]
+
+        [props["code.filepath"], props["code.lineno"]].compact.join(":")
+      end
+
+      def request_heading(request, title)
+        [bold(title), request[:status], format("%.1fms", request[:duration_ms]), endpoint(request)].compact.join("  ")
+      end
+
+      def endpoint(request)
+        name = [request[:controller], request[:action]].compact.join("#")
+        name unless name.empty?
+      end
+
+      def read_local_spans(database_path)
+        unless File.exist?(database_path)
+          $stderr.puts "No Flare spans database at #{database_path}."
+          $stderr.puts "Start your app in development and make a request, or pass --db PATH."
+          exit 1
+        end
+
+        begin
+          require "sqlite3"
+        rescue LoadError
+          $stderr.puts "The sqlite3 gem is required. Add `gem \"sqlite3\"` to your Gemfile and run with `bundle exec`."
+          exit 1
+        end
+        require_relative "../storage"
+        require_relative "../storage/sqlite"
+
+        begin
+          yield Storage::SQLite.new(database_path, readonly: true)
+        rescue SQLite3::Exception => e
+          $stderr.puts "Could not read #{database_path}: #{e.message}"
+          exit 1
+        end
+      end
+    end
+  end
+end

data/lib/flare/cli/nplus1_command.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "local_spans"
+require_relative "output"
+
+module Flare
+  # Finds queries repeated within recent requests in the local development
+  # spans database, and the code that ran them, so you (or a coding agent) can
+  # spot an N+1 and confirm a fix without opening /flare.
+  class Nplus1Command
+    include CLI::LocalSpans
+    include CLI::Output
+
+    MINIMUM_REPEATS = 2
+
+    def initialize(argv)
+      parse_options(argv, banner: "Usage: flare nplus1 [options]", last_help: "Number of requests to check")
+    end
+
+    def run
+      requests = read_local_spans(@database_path) { |storage| load_requests(storage) }
+
+      if @json
+        puts JSON.pretty_generate(requests)
+      elsif requests.empty?
+        puts "No repeated queries in recent requests (checked up to #{@limit})."
+      else
+        requests.each { |request| print_request(request) }
+      end
+    end
+
+    private
+
+    def load_requests(storage)
+      recent_requests(storage, @limit).filter_map do |request|
+        repeated = repeated_queries(storage.spans_for_trace(request[:trace_id]))
+        request.merge(repeated: repeated) if repeated.any?
+      end
+    end
+
+    def repeated_queries(spans)
+      spans.select { |span| query?(span) }
+        .group_by { |span| shape(span[:properties]["db.statement"]) }
+        .select { |_, queries| queries.size >= MINIMUM_REPEATS }
+        .map { |statement, queries| summarize(statement, queries) }
+        .sort_by { |query| [-query[:count], -query[:total_ms]] }
+    end
+
+    def query?(span)
+      props = span[:properties]
+      statement = props["db.statement"]
+      return false unless statement && Storage::SQLite::SPAN_CATEGORIES["queries"].any? { |pattern| span[:name].downcase.include?(pattern) }
+
+      # Active Record's bookkeeping repeats by design. Transaction statements
+      # from elsewhere have no name, so they're also matched by their text.
+      !Storage::SQLite::BOOKKEEPING_QUERY_NAMES.include?(props["name"]) && !Storage::SQLite::TRANSACTION_STATEMENTS.include?(statement.to_s.strip.upcase)
+    end
+
+    # The statement with its values taken out, so one query run with different
+    # values reads as the same query.
+    def shape(statement)
+      statement.to_s
+        .gsub(%r{/\*.*?\*/}m, " ")
+        .gsub(/'(?:[^']|'')*'/, "?")
+        .gsub(/\$\d+/, "?")
+        .gsub(/\b\d+(?:\.\d+)?\b/, "?")
+        .gsub(/\bIN\s*\(\s*\?(?:\s*,\s*\?)*\s*\)/i, "IN (?)")
+        .gsub(/\s+/, " ")
+        .strip
+    end
+
+    def summarize(statement, queries)
+      {
+        statement: statement,
+        count: queries.size,
+        total_ms: queries.sum { |query| query[:duration_ms] }.round(1),
+        sources: sources(queries),
+      }
+    end
+
+    def sources(queries)
+      queries.filter_map { |query| source_location(query[:properties]) }.tally
+        .sort_by { |_, count| -count }
+        .map { |location, count| { location: location, count: count } }
+    end
+
+    def print_request(request)
+      puts "#{request_heading(request, "#{request[:method]} #{request[:path]}")}  #{dim(request[:trace_id])}"
+
+      request[:repeated].each do |query|
+        puts format("%4dx %7.1fms  %s", query[:count], query[:total_ms], query[:statement])
+        query[:sources].each { |source| puts dim(format("%7dx  %s", source[:count], source[:location])) }
+      end
+    end
+  end
+end

data/lib/flare/cli/project.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Flare
+  module CLI
+    # What the commands need to know about the app they're run in.
+    module Project
+      private
+
+      # Also matches /.env*, the rule in a new Rails app's .gitignore. The last
+      # rule wins, as it does in git, so a later !.env means it isn't ignored.
+      def env_ignored?(gitignore)
+        last_rule = gitignore.scan(%r{^!?/?\.env\*?$}).last
+        !last_rule.nil? && !last_rule.start_with?("!")
+      end
+
+      # A FLARE_KEY in .env, whether setup saved it there or someone added it
+      # by hand. Setup and doctor both treat that .env as needing to be ignored.
+      def key_in_dotenv?
+        env_path = File.join(Dir.pwd, ".env")
+        File.exist?(env_path) && File.read(env_path).match?(/^FLARE_KEY=.+/)
+      end
+
+      def credentials_exist?
+        Dir.glob("config/credentials{.yml.enc,/*.yml.enc}", base: Dir.pwd).any?
+      end
+    end
+  end
+end

data/lib/flare/cli/request_command.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "local_spans"
+require_relative "output"
+
+module Flare
+  # Shows what one request did, from the local development spans database, so
+  # you (or a coding agent) can read its timeline without opening /flare. Trace
+  # ids come from `flare requests`.
+  class RequestCommand
+    include CLI::LocalSpans
+    include CLI::Output
+
+    USAGE = "Usage: flare request <trace_id> [options]"
+
+    def initialize(argv)
+      arguments = parse_options(argv, banner: USAGE)
+
+      unless arguments.size == 1
+        $stderr.puts USAGE
+        exit 1
+      end
+      @trace_id = arguments.first
+    end
+
+    def run
+      request = read_local_spans(@database_path) { |storage| load_request(storage) }
+
+      unless request
+        $stderr.puts "No request with trace id #{@trace_id}. Run `flare requests` to list recent ones."
+        exit 1
+      end
+
+      if @json
+        puts JSON.pretty_generate(request)
+      else
+        print_request(request)
+      end
+    end
+
+    private
+
+    def load_request(storage)
+      root = storage.find_request(@trace_id)
+      return unless root
+
+      spans = storage.spans_for_trace(@trace_id)
+      props = root[:properties]
+
+      request_summary(root,
+        method: props["http.request.method"] || props["http.method"],
+        path: props["url.path"] || props["http.target"],
+        status: props["http.response.status_code"] || props["http.status_code"],
+        controller: props["code.namespace"],
+        action: props["code.function"],
+        queries: storage.count_queries_by_trace([@trace_id]).fetch(@trace_id, 0)).merge(
+          name: root[:name],
+          exceptions: spans.flat_map { |span| exceptions(span) },
+          spans: spans.reject { |span| span[:id] == root[:id] }.map { |span| timeline_entry(span, root) },
+        )
+    end
+
+    def exceptions(span)
+      span[:events].select { |event| event[:name] == "exception" }.map do |event|
+        {
+          type: event[:properties]["exception.type"],
+          message: event[:properties]["exception.message"],
+          stacktrace: event[:properties]["exception.stacktrace"],
+        }
+      end
+    end
+
+    def timeline_entry(span, root)
+      props = span[:properties]
+      {
+        name: span[:name],
+        offset_ms: ((span[:start_timestamp] - root[:start_timestamp]) / 1_000_000.0).round(1),
+        duration_ms: span[:duration_ms].round(1),
+        detail: detail(props),
+        source: source_location(props),
+      }
+    end
+
+    def detail(props)
+      statement = props["db.statement"]
+      return statement.to_s.gsub(/\s+/, " ").strip if statement
+
+      identifier = props["identifier"]
+      return identifier.to_s.sub(%r{\A.*/app/views/}, "") if identifier
+
+      props["http.url"] || props["url.full"]
+    end
+
+    def print_request(request)
+      title = request[:method] ? "#{request[:method]} #{request[:path]}" : request[:name]
+      puts request_heading(request, title)
+      puts "Started #{request[:started_at]}  #{request[:queries]} queries"
+
+      request[:exceptions].each do |exception|
+        puts red("Exception: #{[exception[:type], exception[:message]].compact.join(": ")}")
+      end
+
+      return if request[:spans].empty?
+
+      puts
+      puts dim(format("%9s %9s", "offset", "duration"))
+      request[:spans].each { |span| puts format_span(span) }
+    end
+
+    def format_span(span)
+      label = span[:detail] ? "#{span[:name]}: #{span[:detail]}" : span[:name]
+      [
+        format("%7.1fms %7.1fms", span[:offset_ms], span[:duration_ms]),
+        label,
+        span[:source] && dim(span[:source]),
+      ].compact.join("  ")
+    end
+  end
+end