flare 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8eb495874fecf193c205e02c4254d2229ad264cc3e640bba5239940ac3de8e5d
+  data.tar.gz: 71218afa6c8972dcf6cf76dc3dddc059a5197a7542a05cf8d0ad8a8f964c290f
+SHA512:
+  metadata.gz: '035922584796dd1033486f6723cf859ae0d9f8dd169221817c120f66d3352ad5bbea6793f154d2963476a77e58b7f1c5a3635bf965821d245176271bd4d752de'
+  data.tar.gz: 72338f6d8503a8b464f86de6e5397023716d55a810623eefe1d9b81cfdeae4ef3829f15b1228ccb1bdbacf0d957938d54a9e345a5c08f6ba09a7c68cd4b2624e

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-12-17
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 John Nunemaker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,148 @@
+# Flare — App Monitoring
+
+Light up what's slowing you down. [flare.am](https://flare.am)
+
+App monitoring for Rails. Captures requests, queries, jobs, cache, views, HTTP calls, mail, and exceptions in development with a waterfall visualization dashboard. Sends lightweight aggregated metrics in production.
+
+## Features
+
+- **HTTP Requests** - Track all incoming requests with status codes, durations, and controller actions
+- **Background Jobs** - Monitor ActiveJob processing with queue names and execution times
+- **Database Queries** - See all SQL queries with the source location that triggered them
+- **Cache Operations** - Track cache reads, writes, hits, and misses
+- **View Rendering** - Monitor template and partial rendering times
+- **HTTP Client Calls** - See outgoing HTTP requests to external services
+- **Email Delivery** - Track ActionMailer sends with recipients and subjects
+- **Exceptions** - View errors with full stacktraces
+
+Each span shows a waterfall visualization of child operations, making it easy to understand request timing and identify bottlenecks.
+
+## Installation
+
+Add Flare to your Gemfile:
+
+```ruby
+gem "flare"
+```
+
+The local development dashboard uses SQLite to store spans. If your app doesn't already have `sqlite3` in its Gemfile, add it to the development group:
+
+```ruby
+group :development do
+  gem "sqlite3"
+end
+```
+
+Then run:
+
+```bash
+bundle install
+flare setup
+```
+
+The setup command will:
+
+1. Authenticate with flare.am to configure metrics
+2. Create a config initializer with sensible defaults
+3. Update .gitignore
+
+Start your Rails server and visit `/flare` to see the dashboard.
+
+### Manual Configuration
+
+If you prefer to skip the setup wizard, just add the gem and visit `/flare` in development. The dashboard works out of the box with no configuration needed.
+
+To enable metrics, set `FLARE_KEY` in your environment (get one at [flare.am](https://flare.am)).
+
+### CLI Commands
+
+```bash
+flare setup    # Authenticate and configure Flare
+flare doctor   # Check your setup for issues
+flare status   # Show current configuration
+```
+
+## Configuration
+
+All configuration is optional. Flare works out of the box with sensible defaults.
+
+```ruby
+Flare.configure do |config|
+  # Enable or disable Flare (default: true)
+  config.enabled = true
+
+  # How long to keep spans in hours (default: 24)
+  config.retention_hours = 24
+
+  # Maximum number of spans to store (default: 10000)
+  config.max_spans = 10_000
+
+  # Path to the SQLite database (default: db/flare.sqlite3)
+  config.database_path = Rails.root.join("db", "flare.sqlite3").to_s
+
+  # Ignore specific requests (receives a Rack::Request, return true to ignore)
+  config.ignore_request = ->(request) {
+    request.path.start_with?("/health")
+  }
+
+  # Subscribe to custom notification prefixes (default: ["app."])
+  config.subscribe_patterns << "mycompany."
+end
+```
+
+## Custom Instrumentation
+
+Flare automatically captures Rails internals, but you can also instrument your own code. Use `ActiveSupport::Notifications.instrument` with an `app.` prefix:
+
+```ruby
+# In your application code
+ActiveSupport::Notifications.instrument("app.geocoding", address: address) do
+  geocoder.lookup(address)
+end
+
+ActiveSupport::Notifications.instrument("app.stripe.charge", amount: 1000) do
+  Stripe::Charge.create(amount: 1000, currency: "usd")
+end
+
+ActiveSupport::Notifications.instrument("app.send_sms", to: phone) do
+  twilio.messages.create(to: phone, body: message)
+end
+```
+
+This works in all environments - in production it's essentially a no-op, in development Flare automatically captures and displays it.
+
+### Custom Notification Prefixes
+
+By default, Flare subscribes to notifications starting with `app.`. You can add additional prefixes:
+
+```ruby
+Flare.configure do |config|
+  config.subscribe_patterns << "mycompany."
+  config.subscribe_patterns << "external_service."
+end
+```
+
+## How It Works
+
+Flare uses [OpenTelemetry](https://opentelemetry.io/) for instrumentation. It automatically configures:
+
+- `OpenTelemetry::Instrumentation::Rack` - HTTP requests
+- `OpenTelemetry::Instrumentation::ActiveSupport` - Notifications (SQL, cache, mail)
+- `OpenTelemetry::Instrumentation::ActionPack` - Controller actions
+- `OpenTelemetry::Instrumentation::ActionView` - View rendering
+- `OpenTelemetry::Instrumentation::ActiveJob` - Background jobs
+- `OpenTelemetry::Instrumentation::Net::HTTP` - Outgoing HTTP calls
+
+Spans are stored in a local SQLite database (`db/flare.sqlite3` by default) and automatically pruned based on retention settings.
+
+## 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.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/app/controllers/flare/application_controller.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Flare
+  class ApplicationController < ActionController::Base
+    protect_from_forgery with: :exception
+
+    layout "flare/application"
+
+    helper_method :show_redis_tab?
+
+    private
+
+    # Only show the Redis tab if:
+    # 1. The Redis client library is loaded
+    # 2. There are Redis spans in the database
+    def show_redis_tab?
+      return false unless defined?(::Redis)
+
+      Flare.storage.count_spans_by_category("redis") > 0
+    end
+  end
+end

data/app/controllers/flare/jobs_controller.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Flare
+  class JobsController < ApplicationController
+    around_action :untrace_request
+
+    helper_method :current_section, :page_title
+
+    PER_PAGE = 50
+
+    def index
+      @offset = params[:offset].to_i
+      filter_params = {
+        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)
+      @total_count = Flare.storage.count_jobs(**filter_params)
+      @has_next = jobs.size > PER_PAGE
+      @jobs = jobs.first(PER_PAGE)
+      @has_prev = @offset > 0
+    end
+
+    def show
+      @job = Flare.storage.find_job(params[:id])
+
+      if @job.blank?
+        redirect_to jobs_path, alert: "Job not found"
+        return
+      end
+
+      @spans = Flare.storage.spans_for_trace(params[:id])
+
+      # Find the root span (the job itself) with full properties
+      @root_span = @spans.find { |s| s[:parent_span_id] == Flare::MISSING_PARENT_ID }
+
+      # Child spans (everything except the root)
+      @child_spans = @spans.reject { |s| s[:parent_span_id] == Flare::MISSING_PARENT_ID }
+    end
+
+    private
+
+    def untrace_request
+      Flare.untraced { yield }
+    end
+
+    def current_section
+      "jobs"
+    end
+
+    def page_title
+      "Jobs"
+    end
+  end
+end

data/app/controllers/flare/requests_controller.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Flare
+  class RequestsController < ApplicationController
+    around_action :untrace_request
+
+    helper_method :current_section, :page_title, :current_origin
+
+    PER_PAGE = 50
+
+    def index
+      @offset = params[:offset].to_i
+      filter_params = {
+        status: params[:status].presence,
+        method: params[:method].presence,
+        name: params[:name].presence,
+        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)
+      @total_count = Flare.storage.count_requests(**filter_params)
+      @has_next = requests.size > PER_PAGE
+      @requests = requests.first(PER_PAGE)
+      @has_prev = @offset > 0
+    end
+
+    def show
+      @request = Flare.storage.find_request(params[:id])
+
+      if @request.blank?
+        redirect_to requests_path, alert: "Request not found"
+        return
+      end
+
+      @spans = Flare.storage.spans_for_trace(params[:id])
+
+      # Find the root span (the request itself) with full properties
+      @root_span = @spans.find { |s| s[:parent_span_id] == Flare::MISSING_PARENT_ID }
+
+      # Child spans (everything except the root)
+      @child_spans = @spans.reject { |s| s[:parent_span_id] == Flare::MISSING_PARENT_ID }
+    end
+
+    def clear
+      Flare.storage.clear_all
+      redirect_to root_path
+    end
+
+    private
+
+    def untrace_request
+      Flare.untraced { yield }
+    end
+
+    def current_section
+      "requests"
+    end
+
+    def page_title
+      "Requests"
+    end
+
+    def current_origin
+      # If origin was explicitly set (even to empty for "All"), use that
+      if params.key?(:origin)
+        return params[:origin].presence  # nil for "All Origins", "app" or "rails" otherwise
+      end
+
+      # Default to "app" to hide Rails framework noise
+      "app"
+    end
+  end
+end

data/app/controllers/flare/spans_controller.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Flare
+  class SpansController < ApplicationController
+    around_action :untrace_request
+
+    helper_method :current_section, :page_title, :category_config
+
+    PER_PAGE = 50
+
+    CATEGORIES = {
+      "queries" => { title: "Queries", icon: "database", badge_class: "sql" },
+      "cache" => { title: "Cache", icon: "archive", badge_class: "cache" },
+      "views" => { title: "Views", icon: "layout", badge_class: "view" },
+      "http" => { title: "HTTP", icon: "globe", badge_class: "http" },
+      "mail" => { title: "Mail", icon: "mail", badge_class: "mail" },
+      "redis" => { title: "Redis", icon: "database", badge_class: "other" },
+      "exceptions" => { title: "Exceptions", icon: "alert-triangle", badge_class: "exception" }
+    }.freeze
+
+    def queries
+      list_spans("queries")
+    end
+
+    def cache
+      list_spans("cache")
+    end
+
+    def views
+      list_spans("views")
+    end
+
+    def http
+      list_spans("http")
+    end
+
+    def mail
+      list_spans("mail")
+    end
+
+    def redis
+      list_spans("redis")
+    end
+
+    def exceptions
+      list_spans("exceptions")
+    end
+
+    def show
+      @span = Flare.storage.find_span(params[:id])
+
+      if @span.blank?
+        redirect_to requests_path, alert: "Span not found"
+        return
+      end
+
+      @category = params[:category]
+    end
+
+    private
+
+    def list_spans(category)
+      @category = category
+      @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)
+      @total_count = Flare.storage.count_spans_by_category(category, **filter_params)
+      @has_next = spans.size > PER_PAGE
+      @spans = spans.first(PER_PAGE)
+      @has_prev = @offset > 0
+
+      # Load properties for display
+      span_ids = @spans.map { |s| s[:id] }
+      if span_ids.any?
+        all_properties = Flare.storage.load_properties_for_ids("Flare::Span", span_ids)
+        @spans.each do |span|
+          span[:properties] = all_properties[span[:id]] || {}
+        end
+      end
+
+      render :index
+    end
+
+    def untrace_request
+      Flare.untraced { yield }
+    end
+
+    def current_section
+      @category || "spans"
+    end
+
+    def page_title
+      category_config[:title]
+    end
+
+    def category_config
+      CATEGORIES[@category] || { title: "Spans", icon: "activity", badge_class: "other" }
+    end
+  end
+end

data/app/helpers/flare/application_helper.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module Flare
+  module ApplicationHelper
+    def span_category(span)
+      name = span[:name].to_s.downcase
+      case name
+      when /sql\.active_record/, /mysql/, /postgres/, /sqlite/
+        "sql"
+      when /cache/
+        "cache"
+      when /render/, /view/
+        "view"
+      when /http/, /net_http/, /faraday/
+        "http"
+      when /mail/
+        "mailer"
+      when /job/, /active_job/
+        "job"
+      when /action_controller/, /process_action/
+        "controller"
+      else
+        "other"
+      end
+    end
+
+    def span_display_info(span, category)
+      props = span[:properties] || {}
+      case category
+      when "queries"
+        stmt = props["db.statement"]&.to_s
+        name = props["name"]&.to_s
+        db_name = props["db.name"]&.to_s
+        source_loc = if props["code.filepath"] && props["code.lineno"]
+          "#{props["code.filepath"]}:#{props["code.lineno"]}"
+        end
+        secondary = [name.presence, db_name.presence, source_loc].compact.join(" \u00b7 ").presence
+        if stmt.present?
+          { primary: stmt, secondary: secondary }
+        elsif name.present?
+          { primary: name, secondary: [db_name.presence, source_loc].compact.join(" \u00b7 ").presence }
+        else
+          { primary: span[:name], secondary: [db_name.presence, source_loc].compact.join(" \u00b7 ").presence }
+        end
+      when "cache"
+        key = props["key"]&.to_s
+        op = span[:name].to_s.sub(".active_support", "").sub("cache_", "")
+        store = props["store"]&.to_s&.sub(/^ActiveSupport::Cache::/, "")
+        { primary: key.presence || span[:name], secondary: store, cache_op: op }
+      when "views"
+        identifier = props["identifier"] || props["code.filepath"]
+        primary = identifier ? identifier.to_s.sub(/^.*\/app\/views\//, "") : span[:name]
+        { primary: primary, secondary: nil }
+      when "http"
+        full_url = props["http.url"] || ""
+        target = props["http.target"] || ""
+        host = props["http.host"] || props["net.peer.name"] || props["peer.service"]
+        uri = URI.parse(full_url) rescue nil
+        if uri && uri.host
+          domain = uri.host
+          path = uri.path.presence || "/"
+          path = "#{path}?#{uri.query}" if uri.query.present?
+        else
+          domain = host
+          path = target.presence || full_url
+        end
+        method = props["http.method"]
+        status = props["http.status_code"]
+        { primary: path.to_s.truncate(100), secondary: domain, http_method: method, http_status: status }
+      when "mail"
+        mailer = props["mailer"]
+        action = props["action"]
+        subject = props["subject"]
+        if mailer && action
+          { primary: "#{mailer}##{action}", secondary: subject }
+        else
+          { primary: span[:name], secondary: nil }
+        end
+      when "redis"
+        cmd = props["db.statement"]&.to_s
+        { primary: cmd.presence || span[:name], secondary: nil }
+      when "exceptions"
+        exc_type = span[:exception_type]
+        exc_message = span[:exception_message]
+        primary = if exc_type.present? && exc_message.present?
+          "#{exc_type}: #{exc_message}"
+        elsif exc_message.present?
+          exc_message
+        elsif exc_type.present?
+          exc_type
+        else
+          span[:name]
+        end
+        stacktrace = span[:exception_stacktrace].to_s
+        first_app_line = stacktrace.split("\n").find { |line| line.include?("/app/") } || stacktrace.split("\n").first
+        secondary = first_app_line&.strip.to_s.truncate(200)
+        { primary: primary, secondary: secondary }
+      else
+        { primary: span[:name], secondary: nil }
+      end
+    end
+
+    def format_duration(ms)
+      return "-" if ms.nil?
+
+      if ms >= 1000
+        "#{(ms / 1000.0).round(1)}s"
+      else
+        "#{ms.round(1)}ms"
+      end
+    end
+
+    def format_content(data, indent = 0)
+      return "" if data.nil?
+
+      lines = []
+      prefix = "  " * indent
+
+      case data
+      when Hash
+        data.each do |key, value|
+          if value.is_a?(Hash) || value.is_a?(Array)
+            lines << "#{prefix}#{key}:"
+            lines << format_content(value, indent + 1)
+          else
+            formatted_value = format_value(value)
+            if formatted_value.include?("\n")
+              lines << "#{prefix}#{key}:"
+              formatted_value.each_line do |line|
+                lines << "#{prefix}  #{line.rstrip}"
+              end
+            else
+              lines << "#{prefix}#{key}: #{formatted_value}"
+            end
+          end
+        end
+      when Array
+        data.each do |item|
+          if item.is_a?(Hash) || item.is_a?(Array)
+            lines << "#{prefix}-"
+            lines << format_content(item, indent + 1)
+          else
+            lines << "#{prefix}- #{format_value(item)}"
+          end
+        end
+      else
+        lines << "#{prefix}#{format_value(data)}"
+      end
+
+      lines.join("\n")
+    end
+
+    private
+
+    def format_value(value)
+      case value
+      when nil
+        "null"
+      when true, false
+        value.to_s
+      when Numeric
+        value.to_s
+      else
+        value.to_s
+      end
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+<div class="page-header">
+  <h1 class="page-title"><%= page_title %></h1>
+  <div class="filters">
+    <%= form_tag(jobs_path, method: :get, id: "filter-form") do %>
+      <%= text_field_tag :name, params[:name], placeholder: "Search...", class: "filter-select", style: "min-width: 200px;", onchange: "this.form.submit()" %>
+    <% end %>
+  </div>
+</div>
+
+<div class="page-body">
+  <div class="card">
+    <div class="card-body">
+      <% if @jobs.blank? %>
+        <div class="empty-state">
+          <div class="empty-state-icon">
+            <i class="bi bi-briefcase" style="font-size: 1.5rem;"></i>
+          </div>
+          <h3>No jobs found</h3>
+          <p>Data will appear here as your application processes background jobs.</p>
+        </div>
+      <% else %>
+        <table class="data-table">
+          <thead>
+            <tr>
+              <th>Job</th>
+              <th style="width: 100px; text-align: right;">Duration</th>
+              <th style="width: 120px; text-align: right;">Happened</th>
+            </tr>
+          </thead>
+          <tbody>
+            <% @jobs.each do |job| %>
+              <% started_at = Time.at(job[:start_timestamp] / 1_000_000_000.0) rescue nil %>
+              <%
+                display_name = job[:job_class] || job[:name].to_s.sub(/ (process|publish)$/, '')
+              %>
+              <tr onclick="navigateIfNotSelecting('<%= job_path(job[:trace_id]) %>')" style="cursor: pointer;">
+                <td class="path-cell">
+                  <span class="job-name path-text" title="<%= display_name %>"><%= display_name %></span>
+                  <% queue = job[:queue_name] || "default" %>
+                  <span class="path-subtext" title="<%= queue %>"><%= queue %></span>
+                </td>
+                <td class="duration" style="text-align: right;"><%= format_duration(job[:duration_ms]) %></td>
+                <td class="timestamp" style="text-align: right;"><%= started_at ? time_ago_in_words(started_at) : "-" %></td>
+              </tr>
+            <% end %>
+          </tbody>
+        </table>
+
+        <% if @total_count > 0 %>
+          <div class="pagination">
+            <div class="pagination-side">
+              <% if @has_prev %>
+                <%= link_to "Previous", jobs_path(request.query_parameters.merge(offset: [@offset - 50, 0].max)), class: "pagination-link" %>
+              <% end %>
+            </div>
+            <div class="pagination-info">
+              <%= number_with_delimiter(@offset + 1) %> - <%= number_with_delimiter([@offset + @jobs.size, @total_count].min) %> of <%= number_with_delimiter(@total_count) %>
+            </div>
+            <div class="pagination-side" style="text-align: right;">
+              <% if @has_next %>
+                <%= link_to "Next", jobs_path(request.query_parameters.merge(offset: @offset + 50)), class: "pagination-link" %>
+              <% end %>
+            </div>
+          </div>
+        <% end %>
+      <% end %>
+    </div>
+  </div>
+</div>