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/tmm1/stackprof 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 the board

• Last commit 7w ago
• 26+ active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 53% of recent commits

_{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 tmm1/stackprof repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/tmm1/stackprof.

What it runs against: a local clone of tmm1/stackprof — 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 tmm1/stackprof | 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 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 77 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of tmm1/stackprof. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/tmm1/stackprof.git
#   cd stackprof
#
# 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 tmm1/stackprof and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "tmm1/stackprof(\\.git)?\\b" \\
  && ok "origin remote is tmm1/stackprof" \\
  || miss "origin remote is not tmm1/stackprof (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"

# 4. Critical files exist
test -f "ext/stackprof/stackprof.c" \\
  && ok "ext/stackprof/stackprof.c" \\
  || miss "missing critical file: ext/stackprof/stackprof.c"
test -f "lib/stackprof.rb" \\
  && ok "lib/stackprof.rb" \\
  || miss "missing critical file: lib/stackprof.rb"
test -f "lib/stackprof/report.rb" \\
  && ok "lib/stackprof/report.rb" \\
  || miss "missing critical file: lib/stackprof/report.rb"
test -f "lib/stackprof/middleware.rb" \\
  && ok "lib/stackprof/middleware.rb" \\
  || miss "missing critical file: lib/stackprof/middleware.rb"
test -f "bin/stackprof" \\
  && ok "bin/stackprof" \\
  || miss "missing critical file: bin/stackprof"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 77 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~47d)"
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/tmm1/stackprof"
  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).

StackProf is a sampling call-stack profiler for Ruby 2.2+ that uses OS-level signals to periodically capture the call stack, generating CPU and memory profiles without heavy instrumentation overhead. It replaces perftools.rb and is inspired by Google's gperftools, offering CLI reporting, flamegraph visualization, and Rack middleware integration for production profiling. Hybrid Ruby/C architecture: ext/stackprof/stackprof.c contains the low-level signal handler and sampling logic; lib/stackprof.rb is the main Ruby API wrapper; lib/stackprof/middleware.rb provides Rack integration; lib/stackprof/report.rb handles text/flamegraph output formatting. bin/stackprof is the CLI entry point; vendor/ contains bundled flamegraph.pl and gprof2dot.py tools.

Ruby application developers and DevOps engineers who need to identify performance bottlenecks in production or development environments without the overhead of full instrumentation; users of Rails, Sinatra, and other Ruby frameworks who need CPU and memory profiling with minimal impact.

Production-ready and actively maintained. The project has a multi-year history (evidenced by CHANGELOG.md and Rakefile setup), comprehensive test suite (test/*.rb files), CI pipeline (.github/workflows/ci.yml), and both Ruby and C extension implementations. It is the de facto sampling profiler for Ruby after replacing the older perftools.rb.

Low risk for core functionality but single-maintainer risk (tmm1). The C extension (ext/stackprof/stackprof.c) is Linux-only, limiting Windows/macOS usability in production. TruffleRuby support (lib/stackprof/truffleruby.rb) is present but less battle-tested than MRI. Dependency count is minimal (Gemfile shows no heavy dependencies), reducing supply-chain risk.

Unable to determine exact current work from file list alone, but the presence of lib/stackprof/truffleruby.rb suggests recent compatibility work. The CI workflow (ci.yml) indicates ongoing testing across Ruby versions. No explicit PR or milestone data visible in provided structure.

git clone https://github.com/tmm1/stackprof.git
cd stackprof
bundle install
bundle exec rake compile  # Builds the C extension
bundle exec rake test     # Runs test suite

Daily commands: No traditional 'dev server'. Run profiler via: ```ruby StackProf.run(mode: :cpu, out: 'tmp/stackprof-cpu.dump') { your_code }

Then generate reports: ```bash
bundle exec bin/stackprof tmp/stackprof-cpu.dump --text
bundle exec bin/stackprof tmp/stackprof-cpu.dump --flamegraph > tmp/flamegraph
bundle exec bin/stackprof --flamegraph-viewer=tmp/flamegraph

• ext/stackprof/stackprof.c — Core C extension implementing the sampling profiler's signal handler and data collection—the engine of the entire tool.
• lib/stackprof.rb — Main Ruby entry point exposing StackProf.run, StackProf.start/stop, and configuration—every user interaction starts here.
• lib/stackprof/report.rb — Transforms raw profiler data into human-readable reports (text, json, flamegraph)—critical for interpreting profile dumps.
• lib/stackprof/middleware.rb — Rack integration layer enabling profiling in production web applications—key deployment pattern for this gem.
• bin/stackprof — CLI tool for analyzing saved profile dumps—the user-facing interface for reporting and visualization.
• ext/stackprof/extconf.rb — Build configuration for the native extension—ensures the C profiler compiles correctly across platforms.

• C Extension (stackprof.c) (C, Ruby C API, POSIX signals) — Manages OS signal registration, captures call stacks via rb_backtrace, serializes frame data into binary buffer, writes dump files
  • Failure mode: If signal handler crashes or buffer overflows, the entire Ruby process may segfault; incorrect frame unwinding leads to corrupted profiles
• Ruby API (stackprof.rb) (Ruby, native extension binding) — Exposes start/stop/run interfaces, validates config, delegates to C extension, handles autorun via env vars
  • Failure mode: Invalid configuration (negative interval, unknown mode) causes silent failures or exceptions; memory leaks if start/stop not balanced
• Report Generator (report.rb) (Ruby, JSON, HTML/JS) — Parses binary dump format, aggregates frame data, sorts by CPU/memory, generates text/JSON/flamegraph output
  • Failure mode: Malformed dump file causes parse errors; large dumps may consume excessive memory; flamegraph JS fails on missing data
• Rack Middleware (Ruby, Rack interface) — Intercepts requests, maintains persistent StackProf instance, accumulates samples across requests, saves to disk on interval
  • Failure mode: If save_every is too small, disk I/O becomes a bottleneck; if too large, data loss on crash; interference with async frameworks
• CLI Tool (bin/stackprof) (Ruby, OptionParser, shell scripts) — Parses command-line options, loads dumps, invokes report generator, outputs text/visualization
  • Failure mode: Missing dump file or corrupted path causes silent exit; large dumps timeout; missing flamegraph.pl breaks visualization

Add a new profiling mode (e.g., memory, wall-time)

1. Implement the sampling logic in the C extension signal handler and data structure packing (ext/stackprof/stackprof.c)
2. Expose the new mode option in the Ruby wrapper and validate it (lib/stackprof.rb)
3. Add formatting support in the report generator for the new mode's data (lib/stackprof/report.rb)
4. Add CLI flag parsing and output formatting in the bin tool (bin/stackprof)
5. Add test cases to verify the new mode's behavior (test/test_stackprof.rb)

Add a new output format (e.g., protobuf, custom serialization)

1. Implement the serialization logic in the report generator (lib/stackprof/report.rb)
2. Add a format option and parsing in the CLI tool (bin/stackprof)
3. Add deserialization support back in the main module if needed (lib/stackprof.rb)
4. Add integration tests for the new format (test/test_report.rb)

Enable profiling in a new web framework (beyond Rack)

1. Create a new adapter file following the pattern of the existing Rack middleware (lib/stackprof/middleware.rb)
2. Integrate the adapter into the main StackProf module initialization (lib/stackprof.rb)
3. Add framework-specific test cases (test/test_middleware.rb)

• C extension with signal handlers — Sampling profiler requires ultra-low-overhead, precise timing at the OS level; Ruby alone cannot capture SIGPROF efficiently
• SIGPROF/SIGALRM signals — Allows statistical sampling without instrumenting every method call, minimizing overhead in production
• Rack middleware integration — Seamless integration with Ruby web frameworks; allows per-request or periodic profiling without application code changes
• Flamegraph visualization — Interactive, hierarchical visualization of call stacks; industry-standard format understood by ops teams

• Linux-only platform support

  • Why: SIGPROF signal handling and certain APIs are Linux-specific; macOS/Windows support would require platform-specific rewrites
  • Consequence: Limits adoption to Linux-based deployments (servers, containers); development on macOS requires workarounds

• Sampling profiler vs. instrumentation profiler

  • Why: Sampling has lower overhead (~1-2%) vs. instrumentation (~10-30%), enabling use in production without performance tax
  • Consequence: Cannot capture every single call; rare functions may not appear in output; requires longer sampling periods for accuracy

• Single-threaded profiling model

  • Why: Simplifies implementation and data collection; one global signal handler per process
  • Consequence: Multi-threaded apps show aggregate behavior; thread-local profiling would require thread-safe buffers and more complexity

• Binary dump format with JSON export

  • Why: Binary is compact and fast; JSON enables tool interoperability and human inspection
  • Consequence: Requires parsers in multiple languages; version compatibility important for long-term archives

• Does not support real-time profiling (requires offline dump analysis)
• Does not provide method-level granularity on non-MRI Ruby implementations (TruffleRuby shim is best-effort)
• Does not handle Windows or macOS systems (Linux-only requirement stated in README)
• Does not profile garbage collection in detail (only tracks GC pause impact on sampling)
• Does not provide distributed tracing across multiple processes

1. Linux-only: The C extension uses POSIX signals not available on Windows/macOS (MRI-specific); TruffleRuby has its own implementation in lib/stackprof/truffleruby.rb. 2. Requires native compilation: bundle exec rake compile must be run after gem install; fails silently if gcc/Ruby dev headers are missing. 3. Signal handler reentrancy: sampling can interfere with other signal-based libraries (debuggers, some profilers); mode (:cpu vs :wall vs :object) changes sampling behavior significantly. 4. Large dump files: raw: true flag generates verbose traces; parse performance degrades on multi-GB dumps.

• Signal-based sampling (SIGPROF/SIGALRM) — Core profiling mechanism in StackProf: uses OS signals to interrupt execution and capture call stacks at fixed intervals, avoiding instrumentation overhead but requiring careful signal handler design
• Call stack unwinding — The C extension walks the Ruby call stack on each SIGPROF to record which functions are executing; naive unwinding can miss frames or crash if heap is corrupted
• Flamegraph visualization — StackProf outputs a format consumed by Brendan Gregg's flamegraph.pl to generate interactive SVG charts; crucial for identifying hot paths and call tree bottlenecks
• Sampling bias (miss rate) — StackProf reports a 'miss rate' (e.g., 1.09% in README); this reflects samples lost when signal handler reentry is blocked, affecting accuracy of rare call paths
• Rack middleware lifecycle integration — StackProf::Middleware hooks into Rack to start/stop profiling per-request with save_every batching; requires understanding Rack middleware order and state cleanup
• CPU vs Wall-clock vs Object allocation profiling modes — mode: :cpu samples on CPU time (ignores I/O), mode: :wall samples real time (includes I/O/sleep), mode: :object counts object allocations; each answers different performance questions
• Binary dump format and lazy deserialization — StackProf writes compact binary .dump files and deserializes on-demand during report generation; understanding the dump format is critical for tool interoperability and memory efficiency

• ruby-prof/ruby-prof — Alternative Ruby profiler using instrumentation (not sampling); slower but provides per-line granularity; main competitor in Ruby ecosystem
• brendangregg/FlameGraph — Original flamegraph visualization tool (vendored in vendor/FlameGraph); StackProf outputs compatible format for this Perl tool
• perftools/perftools.py — Predecessor inspiration: Google's gperftools profiler for C/C++; StackProf is the Ruby equivalent using similar signal-based sampling strategy
• rails/rails — Primary end-user framework; StackProf Middleware integrates directly into Rails request lifecycle for production profiling
• alisnic/stackprof-webnav — Experimental companion project: web UI for StackProf results navigation; mentioned in README as alternative to CLI reporting

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 Windows support detection and CI workflow for stackprof

The README explicitly states 'Linux-based OS' as a requirement, but there's no CI workflow testing this constraint or gracefully handling Windows. The .github/workflows/ci.yml likely only tests on Linux. Adding a Windows CI job that validates proper error messages when stackprof is used on unsupported platforms would prevent silent failures and improve cross-platform UX.

• [ ] Review current .github/workflows/ci.yml to confirm Windows testing is absent
• [ ] Add Windows job to ci.yml that attempts to install and validate platform detection
• [ ] Add platform validation logic to lib/stackprof.rb that raises clear error on non-Linux systems
• [ ] Add test case in test/test_stackprof.rb for platform detection on non-Linux

Add comprehensive integration tests for StackProf::Middleware with real Rack applications

The test/test_middleware.rb file exists but likely has minimal coverage given the middleware's complexity (enabled flag, mode, interval, save_every parameters). Adding integration tests with a real Rack app would catch issues with the middleware lifecycle, file I/O, and multi-request scenarios.

• [ ] Review existing test/test_middleware.rb to identify coverage gaps
• [ ] Create a minimal test Rack application in test/fixtures/
• [ ] Add integration tests for: middleware initialization, profiling across multiple requests, save_every triggering, file rotation cleanup
• [ ] Add edge case tests: middleware with profiling disabled mid-request, concurrent requests, permissions errors on output directory

Add test coverage and documentation for TruffleRuby-specific behavior

lib/stackprof/truffleruby.rb exists and test/test_truffleruby.rb is present, but TruffleRuby support is likely under-tested compared to MRI. The differences between TruffleRuby and MRI profiling behavior should have dedicated tests and documented limitations in README.

• [ ] Review test/test_truffleruby.rb and identify missing test scenarios
• [ ] Add tests for TruffleRuby-specific modes (e.g., differences in sampling accuracy, GC profiling behavior)
• [ ] Add a 'TruffleRuby Support' section to README.md documenting known limitations and behavioral differences
• [ ] Add CI workflow job or conditional testing for TruffleRuby (if feasible in GitHub Actions)

• Add test coverage for lib/stackprof/flamegraph/viewer.html JavaScript interactions (test/test_stackprof.rb exists but flamegraph viewer JS appears untested based on file list)
• Document the flamegraph.js library in lib/stackprof/flamegraph/ with inline JSDoc comments; currently no README or comments explain the interactive visualization code
• Expand test/test_middleware.rb to cover edge cases: verify Middleware.reset properly clears state between requests, test save_every interval correctness with synthetic timer mocking

StackProf is a sampling profiler with moderate security concerns. The primary risks involve the native C extension (which requires expert review), insufficient authentication controls on the middleware component, and potential information disclosure through unprotected profile dumps. The vendored third-party tools add maintenance burden. Overall, the codebase appears well-maintained but would benefit from enhanced access controls, secure profile handling practices, and formal security code review of the C extension. No hardcoded credentials or obvious SQL injection vulnerabilities were identified.

• High · Native C Extension Without Input Validation — ext/stackprof/stackprof.c. The stackprof.c file implements native C extensions for profiling. Native extensions can be susceptible to memory corruption vulnerabilities (buffer overflows, use-after-free) if not carefully implemented. The extension interfaces directly with Ruby internals and memory management. Fix: Conduct a thorough security code review of the C extension, implement bounds checking, use safe memory management practices, and consider fuzzing the extension with various inputs to identify potential memory safety issues.
• Medium · Middleware Data Collection Without Authentication — lib/stackprof/middleware.rb. The StackProf::Middleware can be enabled on any request without explicit authentication controls. An attacker could potentially gather profiling information about the application's internals, execution times, and call stacks, which could leak sensitive architectural information. Fix: Implement authentication and authorization checks in the middleware. Ensure profiling is only enabled for authenticated administrators and is disabled in production environments by default. Consider restricting profiling to specific IP addresses or request signatures.
• Medium · Unsafe Profile Data Serialization — lib/stackprof.rb, test/fixtures/profile.dump. Profile dump files (test/fixtures/profile.dump) may contain sensitive runtime information including method names, call stacks, and execution patterns. If these files are stored or transmitted insecurely, they could leak application internals. Fix: Ensure profile dumps are stored with restricted file permissions (0600), encrypted at rest, and never committed to version control. Implement access controls for profile data and consider sanitizing sensitive information from dumps before sharing or analyzing.
• Medium · Third-party Flamegraph and gprof2dot Dependencies — vendor/FlameGraph/, vendor/gprof2dot/. The repository includes vendored copies of external tools (FlameGraph and gprof2dot) in the vendor directory. These tools may have their own vulnerabilities and are not being tracked through standard dependency management. Fix: Track vendored dependencies through a dependency scanner, regularly update them to their latest versions, and consider using a package manager instead of vendoring. Review the security advisories for FlameGraph and gprof2dot regularly.
• Low · Web Viewer Without Security Headers — lib/stackprof/flamegraph/viewer.html. The included flamegraph viewer (lib/stackprof/flamegraph/viewer.html) is a web interface but likely lacks security headers such as CSP, X-Frame-Options, and X-Content-Type-Options when served. Fix: If this viewer is served over HTTP, implement proper security headers including Content-Security-Policy, X-Frame-Options: DENY, X-Content-Type-Options: nosniff, and ensure HTTPS is enforced.
• Low · Limited Platform Support May Hide Security Issues — README.md, Requirements section. The profiler is explicitly limited to Linux-based OS. This platform restriction may mask vulnerabilities that could exist on other platforms, and limits the ability to catch cross-platform security issues. Fix: Document the security implications of platform-specific behavior and ensure that security assumptions made on Linux are clearly documented and tested.

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.