If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/roidrage/lograge shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• 34+ active contributors
• Distributed ownership (top contributor 20% of recent commits)
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 1y ago

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live roidrage/lograge repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/roidrage/lograge.

What it runs against: a local clone of roidrage/lograge — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in roidrage/lograge | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | Last commit ≤ 575 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of roidrage/lograge. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/roidrage/lograge.git
#   cd lograge
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of roidrage/lograge and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "roidrage/lograge(\\.git)?\\b" \\
  && ok "origin remote is roidrage/lograge" \\
  || miss "origin remote is not roidrage/lograge (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 575 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~545d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/roidrage/lograge"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Lograge replaces Rails' default multi-line request logging with a single structured line of key-value pairs per HTTP request. It solves the critical production logging problem where Rails outputs dozens of lines per request (views, database queries, rendering timings), making logs unreadable and unparseable when multiple processes write concurrently. Instead of verbose output like 'Rendered text template within layouts/application (0.0ms)', you get method=GET path=/ format=json controller=HomeController action=index status=200 duration=79.0 view=78.8 db=0.0. Monolithic gem organized by concern: lib/lograge/log_subscribers/ contains Rails event subscribers for ActionController and ActionCable; lib/lograge/formatters/ contains pluggable output formatters (JSON, CEE, Graylog2, logstash, LTSV, key-value variants, L2MET); lib/lograge/rails_ext/ patches Rack and ActionCable internals; lib/lograge/railtie.rb bootstraps the gem into Rails; config lives in lib/lograge/ordered_options.rb.

Rails application operators and DevOps engineers running multi-process Rails services in production who need machine-readable, single-line request logs suitable for aggregation and analysis. Developers maintaining or monitoring Rails 5.2+ applications (especially API-only apps) who want to reduce log noise and improve debugging efficiency.

Production-ready and actively maintained. The project has a clean CI/CD setup (GitHub Actions for multiple Rails versions 5.2–7.1 and Ruby versions), comprehensive test suite under spec/, well-documented README, and regular gem releases. This is a foundational logging gem in the Rails ecosystem with established adoption.

Low risk for production use. Single maintainer (roidrage) is a potential concern for long-term maintenance, but the codebase is stable and focused. No indication of breaking changes in recent work. Dependency footprint is minimal (it extends Rails' built-in logging via Railtie). Main risk is Rails API changes requiring version bumps for new major Rails releases.

No specific PR or milestone data visible in the file structure provided, but the Gemfile lists concurrent testing across Rails 5.2–7.1 gemfiles and a CodeQL security workflow, indicating active maintenance and security awareness. Dependabot configuration suggests automated dependency updates.

git clone https://github.com/roidrage/lograge.git
cd lograge
bundle install
bundle exec rspec

Daily commands:

bundle exec rspec              # Run full test suite
bundle exec rspec spec/formatters/cee_spec.rb  # Test specific formatter
APPLE_PLATFORMS=true bundle exec rspec  # Test with various Rails versions via Gemfile switching

• lib/lograge/railtie.rb: Bootstraps the gem into Rails, registers log subscribers, attaches Rack middleware for log suppression, and handles config initialization
• lib/lograge/log_subscribers/action_controller.rb: Core logic for capturing and formatting HTTP request lifecycle events; directly responsible for the single-line output per request
• lib/lograge/formatters/json.rb: Reference implementation of the formatter interface; shows how to convert captured request data into structured output
• lib/lograge/rails_ext/rack/logger.rb: Patches Rails' Rack logger middleware to suppress default noisy log output, allowing lograge to take over cleanly
• lib/lograge/ordered_options.rb: Configuration container for all lograge settings (enabled, formatter, custom fields, filter parameters); users configure this in initializers
• lib/lograge/log_subscribers/base.rb: Abstract base class defining the interface and common behavior for all event subscribers (ActionController, ActionCable)

Adding a new formatter: Create lib/lograge/formatters/my_format.rb inheriting from a base formatter (see lib/lograge/formatters/json.rb), implement #format(data) returning a string, add test in spec/formatters/my_format_spec.rb. Changing request capture: Modify lib/lograge/log_subscribers/action_controller.rb to add/remove fields in the extra_keys method or the event data hash. ActionCable logging: Edit lib/lograge/log_subscribers/action_cable.rb and corresponding patches in lib/lograge/rails_ext/action_cable/. Configuration options: Add to lib/lograge/ordered_options.rb and document in README.

1. Rails version coupling: The gem must be compatible with the Rails version in use; test matrix in Gemfiles is required because log event APIs differ (Rails 5.2–7.1 have breaking changes in instrumentation events). 2. Config placement: Lograge config must be set early in Rails initialization (in config/initializers/lograge.rb or config/environments/production.rb), not in the application controller or after boot. 3. Log suppressor activation: The Rack logger patch in rails_ext/rack/logger.rb is what silences Rails' default logs; if config.lograge.enabled = false, you'll get double logging. 4. Custom formatter must return a string: Formatters are called with a hash of request data and must return a single string; returning a hash or object will cause log output to be JSON-encoded again by the logger.

• Rails Instrumentation API (ActiveSupport::Notifications) — Lograge is built entirely on Rails' event pub/sub system; understanding how process_action.action_controller and render_template.action_view events fire is essential to extending or debugging lograge
• Rack Middleware — Lograge patches Rails' Rack logger middleware in lib/lograge/rails_ext/rack/logger.rb to suppress default output; understanding the Rack middleware chain is required to customize log suppression or add middleware around lograge
• Rails Railtie — Lograge uses Railtie (in lib/lograge/railtie.rb) to hook into the Rails boot process and register subscribers at the right time; essential for adding features that need early initialization
• Log Formatting and Structured Logging — Lograge's core value is replacing unstructured multi-line logs with single-line key-value or JSON output; understanding structured logging design (why format=json vs format=key-value matters for downstream parsing) is critical to choosing formatters and adding custom ones
• ActionController lifecycle hooks — Lograge captures timing and metadata by instrumenting ActionController's process_action, send_data, and view/db timing events; modifying what gets logged requires understanding the controller request lifecycle
• ActionCable channel/connection lifecycle — Lograge includes log subscribers for ActionCable (WebSocket) events in lib/lograge/log_subscribers/action_cable.rb; extending WebSocket logging requires understanding connect/subscribe/disconnect event timing
• Formatter plugin pattern — Lograge is extensible through pluggable formatters (base class with multiple implementations); understanding the formatter interface (#format(data) returning a string) allows adding custom output formats without modifying core code

• rails/rails — The target framework being instrumented; lograge uses Rails' ActiveSupport::Notifications API and patches Rack middleware to intercept logging
• aacook/structured_logging — Alternative Rails structured logging gem; similar goal of reducing log noise but different approach using structured JSON logging contexts
• socketry/socketry — Companion for non-Rails Ruby services; if you want lograge-style output for background jobs or other Ruby processes, this provides similar structured logging patterns
• elastic/ecs-logging-ruby — ECS (Elastic Common Schema) logging formatter; if you want lograge output to be ECS-compatible for Elasticsearch, this provides the schema mapping
• paper-trail-gem/paper_trail — Complements lograge by auditing data model changes; while lograge captures request metadata, paper_trail captures what changed in the database

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive test coverage for all formatters with edge cases

The spec/formatters directory has tests for individual formatters, but there's no test coverage for error handling, nil/empty value handling, or formatter composition. The formatters like logstash.rb, graylog2.rb, and cee.rb need edge case testing (malformed data, special characters, very large payloads). This would prevent regressions when users encounter real-world logging scenarios.

• [ ] Review existing spec/formatters/* files to identify missing edge case tests
• [ ] Add tests for nil/empty request params in spec/formatters/logstash_spec.rb
• [ ] Add tests for special characters and escape sequences in spec/formatters/json_spec.rb and spec/formatters/ltsv_spec.rb
• [ ] Add tests for deeply nested custom_options in spec/formatters/key_value_deep_spec.rb
• [ ] Run full test suite with rake to ensure all formatters handle edge cases

Add Rails 8.0+ compatibility tests and gemfile

The repo has gemfiles for Rails 5.2 through 7.1 and an edge version, but no explicit Rails 8.0 gemfile. With Rails 8.0 released, contributors should add gemfiles/rails_8.0.gemfile and potentially a rails_8.1.gemfile to ensure lograge works with the latest versions. This requires updating .github/workflows/ci.yml to test against these versions.

• [ ] Create gemfiles/rails_8.0.gemfile following the pattern of gemfiles/rails_7.1.gemfile
• [ ] Create gemfiles/rails_8.1.gemfile for next major version
• [ ] Update .github/workflows/ci.yml to add matrix test jobs for Rails 8.0 and 8.1
• [ ] Verify lib/lograge/log_subscribers/action_controller.rb works with Rails 8 API changes
• [ ] Run tests: bundle exec appraisal rails_8.0 rake

Add integration tests for Action Cable logging with realistic scenarios

The spec/log_subscribers/action_cable_spec.rb exists but likely has minimal coverage. Real-world Action Cable usage includes connection errors, subscription lifecycle events, and broadcast scenarios. Integration tests would validate that lib/lograge/rails_ext/action_cable/* modules correctly format these events alongside the formatters.

• [ ] Review spec/log_subscribers/action_cable_spec.rb to identify coverage gaps
• [ ] Add tests for connection_established, connection_rejected, and connection_closed events
• [ ] Add tests for subscribe, unsubscribe, and receive events with custom parameters
• [ ] Add tests for error conditions (invalid channels, rejected subscriptions)
• [ ] Add integration test that validates Action Cable logs through json and logstash formatters
• [ ] Verify lib/lograge/rails_ext/action_cable/channel/base.rb formats custom params correctly

• Add test coverage for lib/lograge/formatters/key_value_deep.rb—the file exists but may lack corresponding spec file or edge-case tests for nested parameter flattening
• Document the custom field filtering API in README with working example code—users often need to exclude sensitive params or add custom fields but lack clear docs showing override patterns for the extra_keys method
• Implement formatter for OpenTelemetry or W3C trace context output—the codebase has 8+ formatters (JSON, logstash, graylog2, CEE, L2MET, LTSV, lines, raw, key-value variants) but none for modern distributed tracing standards

Lograge is a well-maintained logging gem with reasonable security posture. Primary risks are configuration-dependent: developers must properly filter sensitive parameters, and formatters should validate/sanitize user-controlled data to prevent log injection. The codebase itself lacks obvious hardcoded secrets or direct injection vulnerabilities. Security relies heavily on proper implementation by end users. Recommendation: Review dependency versions, enhance documentation on security best practices, and add built-in default filters for common sensitive fields.

• Medium · Potential Information Disclosure via Detailed Logging — lib/lograge/formatters/ (all formatter files). Lograge is designed to customize Rails request logging. While this is intentional, formatters like json.rb, logstash.rb, and graylog2.rb may inadvertently log sensitive information (authentication tokens, API keys, PII) if not properly configured with custom parameter filtering. The library provides filtering capabilities but relies on developer configuration. Fix: Ensure comprehensive documentation on filtering sensitive parameters. Implement default filters for common sensitive fields (password, token, secret, api_key, credit_card). Add security guidelines in README for configuring parameter filters.
• Medium · Missing Input Validation in Log Data Processing — lib/lograge/formatters/key_value.rb, lib/lograge/formatters/ltsv.rb, lib/lograge/formatters/lines.rb. The formatters process request data that ultimately comes from user input. While Ruby/Rails provides some protections, formatters like key_value.rb and ltsv.rb perform string operations and transformations on user-controlled data without explicit validation, which could theoretically be exploited for log injection attacks. Fix: Add explicit input sanitization for user-controlled fields before formatting. Validate and escape newlines, control characters, and special characters that could break log structure or inject false entries.
• Low · Potential XXE Vulnerability in CEE Formatter — lib/lograge/formatters/cee.rb. The CEE formatter (lib/lograge/formatters/cee.rb) may process XML-like structures. If extended or modified to parse external XML sources, it could be vulnerable to XXE (XML External Entity) attacks, though current implementation appears safe. Fix: If CEE formatter is extended to parse XML input in the future, disable XXE processing. Document that CEE output is for logging only and not for XML parsing.
• Low · No Dependency Version Pinning in Gemfile — Gemfile, lograge.gemspec. Without viewing the Gemfile content, typical Rails libraries may have loose version constraints allowing transitive dependency updates that could introduce vulnerabilities. Fix: Review gemspec version constraints and ensure they are sufficiently restrictive. Use bundle audit regularly to check for known vulnerabilities in dependencies. Consider using Dependabot (already configured) for dependency updates.
• Low · Potential Unvalidated Redirect via Referrer/URL Logging — lib/lograge/log_subscribers/action_controller.rb. If lograge logs HTTP referrer headers or request URLs without validation, this information could be used to track users or identify security issues, though this is a logging concern rather than code vulnerability. Fix: Document that sensitive request metadata (referrer, user-agent with identifying info) should be filtered. Provide examples of custom filters for privacy-sensitive deployments.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.