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/mstange/samply 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 today
• 7 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 78% 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 mstange/samply repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/mstange/samply.

What it runs against: a local clone of mstange/samply — 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 mstange/samply | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

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

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

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

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

# 4. Critical files exist
test -f "samply/src/main.rs" \\
  && ok "samply/src/main.rs" \\
  || miss "missing critical file: samply/src/main.rs"
test -f "samply/Cargo.toml" \\
  && ok "samply/Cargo.toml" \\
  || miss "missing critical file: samply/Cargo.toml"
test -f "samply-symbols/src/lib.rs" \\
  && ok "samply-symbols/src/lib.rs" \\
  || miss "missing critical file: samply-symbols/src/lib.rs"
test -f "samply-object/src/lib.rs" \\
  && ok "samply-object/src/lib.rs" \\
  || miss "missing critical file: samply-object/src/lib.rs"
test -f "fxprof-processed-profile/src/lib.rs" \\
  && ok "fxprof-processed-profile/src/lib.rs" \\
  || miss "missing critical file: fxprof-processed-profile/src/lib.rs"

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

samply is a command-line sampling profiler for macOS, Linux, and Windows that records CPU profiles with stack traces and outputs them to the Firefox Profiler UI. It uses platform-specific sampling mechanisms (perf events on Linux, perf_event_open syscalls, ETW on Windows) to collect stack traces at configurable intervals (default 1kHz) and generates profiles viewable in profiler.firefox.com with integrated symbol resolution and source code display. Monorepo with workspace members in Cargo.toml: core samply/ crate provides the CLI entry point; etw-reader/ (Windows-specific) handles ETW trace parsing; samply-symbols/ and wholesym/ resolve debug symbols; fxprof-processed-profile/ and gecko_profile/ format output for Firefox Profiler; samply-api/ and samply-quota-manager/ manage local webserver and profile state. Platform-specific code is in samply/src/ with conditional compilation gates.

Systems engineers, performance researchers, and developers on macOS/Linux/Windows who need to analyze where their applications spend CPU time—particularly those profiling C++/Rust applications (like Firefox and other Mozilla projects) and wanting browser-based UI without shipping profiles to external servers.

Production-ready and actively maintained. The project has a structured release pipeline (release.yml CI, semantic versioning in RELEASES.md), comprehensive cross-platform support with GitHub Actions testing (rust.yml), and is distributed via multiple channels (shell installers, cargo, prebuilt binaries). Recent commits and dependency management via Cargo.lock and dependabot.yml indicate active development.

Low risk overall but has platform-specific brittleness: Linux perf_event access requires kernel configuration (perf_event_paranoid tuning), Windows profiling depends on symbol servers (MSDL, Breakpad) being available, and macOS may require security/privacy permissions. Single maintainer (mstange) is a potential bus factor, though Mozilla involvement provides some institutional backing. ETW-reader is Windows-only and excluded from workspace compilation on other platforms.

Active release cycle with v0.13.1 tagged; CI pipelines validate across macOS, Linux, and Windows; Nix packaging via nix-packaging.yml workflow indicates effort to improve distribution. Dependabot monitors dependencies. The project integrates Windows ETW support via the etw-reader subcrate and maintains symbol server support for Windows (MSDL, Breakpad, Chrome symsrv).

git clone https://github.com/mstange/samply
cd samply
cargo build --release
./target/release/samply record ./my-application my-arguments

For development: cargo build (debug) or cargo build --release (optimized). On Linux, optionally set echo '-1' | sudo tee /proc/sys/kernel/perf_event_paranoid for full profiling access.

Daily commands: Development: cargo build outputs to target/debug/samply; cargo test runs tests. Recording a profile: ./samply record <cmd> spawns subprocess and opens profiler.firefox.com when done. Local symbol server starts automatically on a random port. No external service dependencies; all data stays local until manual upload.

• samply/src/main.rs — Main entry point for the samply CLI tool; orchestrates profiling recording, symbol resolution, and profile output.
• samply/Cargo.toml — Root workspace and primary package manifest; defines all dependencies and platform-specific build configuration for profiler functionality.
• samply-symbols/src/lib.rs — Core symbol resolution and debuginfo parsing; enables stack frame interpretation across macOS (DWARF), Linux (ELF/DWARF), and Windows (PDB) formats.
• samply-object/src/lib.rs — Object file abstraction layer; unifies handling of Mach-O, ELF, and PE binaries for symbol and debuginfo extraction.
• fxprof-processed-profile/src/lib.rs — Firefox Profiler format serializer; converts collected samples and stack traces into the standard Firefox profiler JSON format.
• gecko_profile/src/lib.rs — Gecko profile schema and profile data structures; defines the in-memory representation of profiling samples and metadata.
• etw-reader/src/lib.rs — Windows ETW (Event Tracing for Windows) reader; abstracts low-level kernel event capture for Windows profiling backend.

Add Support for a New Binary Debug Format

1. Define binary file format parsing in samply-object/src/lib.rs by adding a new enum variant to represent the format. (samply-object/src/lib.rs)
2. Implement symbol extraction for the new format by extending the Object trait implementations. (samply-object/src/lib.rs)
3. Add DWARF/debuginfo parsing in wholesym-addr2line/src/lib.rs if the format uses DWARF, or create a new module for custom formats. (wholesym-addr2line/src/lib.rs)
4. Register the format in samply-symbols/src/lib.rs to integrate it into the symbol resolution pipeline. (samply-symbols/src/lib.rs)
5. Add test fixture binaries and integration tests in fixtures/ and samply/tests/ directories. (fixtures/other)

Add Symbol Server Support for a New Online Service

1. Extend the symbol server client in wholesym/src/lib.rs to recognize and handle the new service URL. (wholesym/src/lib.rs)
2. Implement HTTP client logic for the symbol server's API (e.g., SymSrv protocol, or custom REST endpoint). (wholesym/src/lib.rs)
3. Add debug ID matching and fallback logic if the new service requires custom symbol identifier formats. (samply-debugid/src/lib.rs)
4. Update CLI documentation in samply/src/main.rs to document the new --*-symbol-server flag and usage. (samply/src/main.rs)

Add a New Profiling Event Type or Metric

1. Define the new event/metric structure in gecko_profile/src/lib.rs (e.g., a new Sample field or Profile metadata). (gecko_profile/src/lib.rs)
2. Extend the platform-specific sampling code in samply/src/ to capture the new event from the OS kernel interface. (samply/src/main.rs)
3. Update the serializer in fxprof-processed-profile/src/lib.rs to include the new field in Firefox Profiler JSON output. (fxprof-processed-profile/src/lib.rs)
4. Add integration tests with fixture binaries to verify the new metric is correctly collected and serialized. (fixtures)

Improve Symbol Resolution Caching or Fallback Strategy

1. Review the caching logic in samply-symbols/src/lib.rs and identify the cache data structure. (samply-symbols/src/lib.rs)
2. Extend the fallback resolver in wholesym/src/lib.rs to add new resolution strategies (e.g., local symbol server, git commit-based lookup). (wholesym/src/lib.rs)
3. Add quota management in samply-quota-manager/src/lib.rs if the new strategy may consume significant memory or I/O. (samply-quota-manager/src/lib.rs)
4. Test with fixture binaries in fixtures/ and measure performance impact using tools/benchmarks. (tools/benchmarks)

• Rust — Memory safety, performance, and cross-platform compatibility; critical for low-level profiling instrumentation and symbol resolution without GC latency.
• Firefox Profiler format (JSON + streaming) — Provides rich, browser-based UI for profile visualization; standard interchange format for profiling tools; reduces need for custom UI development.
• perf (Linux), dtrace/exc (macOS), ETW (Windows) — Only standardized, low-overhead OS-level profiling mechanisms available on each platform; kernel-level precision for CPU sampling.
• DWARF, PDB, Mach-O debuginfo standards — Universal debug format support required for symbol resolution across heterogeneous ecosystems (Firefox, Chrome, custom binaries, Linux distros).

• Separate symbol resolution caching from sample collection

  • Why: Avoids blocking the hot sampling loop on I/O or DWARF parsing; enables parallel resolution.
  • Consequence: Additional complexity in cache management; potential for stale symbols if binary updated during profiling.

• Quota enforcement (memory + time) rather than unlimited buffering

  • Why: Prevents OOM on long-running profiling sessions with many samples or large binaries.
  • Consequence: Users may lose fine-grained samples if quota exceeded; trade-off between fidelity and resource usage.

• Multi-layer symbol fallback (local binary → symbol server → addr2line)

  • Why: Maximizes symbol availability across different deployment scenarios (CI, local builds, shipped binaries).
  • Consequence: Increased network latency if symbol server unavailable; non-deterministic symbol quality depending on available sources.

• undefined

  • Why: undefined
  • Consequence: undefined

Linux perf_event_paranoid: Default kernel setting blocks non-root perf; users must manually run echo '-1' | sudo tee /proc/sys/kernel/perf_event_paranoid or samply will fail silently or with permission errors. Windows symbol servers: Must be reachable; malformed URLs in --windows-symbol-server or --breakpad-symbol-server flags can silently drop symbols without clear error messages. macOS sandboxing: May require disabling System Integrity Protection or running from /usr/local/bin for full process introspection. ETW-reader excluded from non-Windows: etw-reader is in workspace exclude list in Cargo.toml; attempting cargo build -p etw-reader on macOS/Linux will fail. Port conflicts: Local profiler webserver picks random port; no explicit retry logic if port is occupied.

• Perf events (perf_event_open syscall) — Core sampling mechanism on Linux; understanding perf_event_paranoid, ring buffers, and sampling frequency is critical for debugging Linux profiling failures in samply
• Event Tracing for Windows (ETW) — Windows-specific sampling backend; ETW trace format parsing is entirely isolated in etw-reader crate and uses custom schema definitions for stack unwinding
• Stack unwinding and DWARF debugging information — samply-symbols must resolve debug symbols from DWARF (ELF), dSYM (Mach-O), and PDB (PE) formats to map instruction pointers to source locations; mismatches cause 'unknown function' frames
• Symbol server protocols (MSDL, Breakpad, symsrv) — Windows profiling relies on remote symbol servers for Windows system libraries (MSDL) and third-party binaries (Breakpad, Chrome); samply abstracts server communication via --windows-symbol-server and --breakpad-symbol-server flags
• Firefox Profiler JSON schema (processed profile format) — samply's output must conform to profiler.firefox.com's JSON schema; violations break visualization; fxprof-processed-profile crate encodes this contract
• Breakpad symbol format (.sym files) — Third-party and some Mozilla binaries use Breakpad format instead of native debug symbols; etw-reader and samply-symbols must parse these stacks correctly for cross-vendor profiling
• Ring buffers and memory-mapped I/O for trace reading — Both perf_event (Linux) and ETW (Windows) deliver samples via ring buffers; efficient lock-free reading is critical for not dropping samples under high contention

• mozilla/gecko-dev — Firefox's own profiling infrastructure; samply outputs to profiler.firefox.com which is built by Mozilla and shares symbol/source integration patterns
• brendangregg/FlameGraph — Earlier flame graph visualization approach; samply modernizes profiler UX by delegating rendering to Firefox Profiler instead of static SVG generation
• gperftools/gperftools — Alternative CPU profiling library (libprofiler) with similar goals but requires code instrumentation; samply is sampling-based and non-invasive
• jvm-profiling-tools/async-profiler — JVM-focused sampling profiler; samply's architecture (platform sampling + symbol resolution + web UI) parallels async-profiler for Java/JVM workloads
• mozilla/profiler — The Firefox Profiler web frontend that samply uses for visualization; understanding its schema (via fxprof-processed-profile crate) is essential for output compatibility

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 integration tests for etw-reader Windows ETW parsing

The etw-reader crate has multiple parser modules (parser.rs, schema.rs, tdh.rs) but no test fixtures or integration tests. Given that Windows ETW parsing is complex and platform-specific, adding integration tests with real ETW event samples would catch regressions and validate the parser against actual Windows trace files.

• [ ] Create fixtures/etw-traces/ directory with sample .etl trace files
• [ ] Add integration test in etw-reader/tests/ that parses sample traces and validates event parsing
• [ ] Test etw-reader/src/parser.rs against real ETW event structures from tdh_types.rs
• [ ] Document how to generate test fixtures in etw-reader/README.md

Add platform-specific unit tests for symbol resolution in samply-symbols

The samply-symbols crate handles symbol resolution across macOS (dSYM), Linux (debug sections), and Windows (PDB/breakpad), but there are no per-platform unit tests validating symbol lookup. The fixtures/ directory has platform-specific binaries (macos-ci/libmozglue.dylib.dSYM, linux64-ci/firefox, etc.) that should be used in automated tests.

• [ ] Create samply-symbols/tests/macos_symbols_test.rs to test dSYM parsing against fixtures/macos-ci/libmozglue.dylib.dSYM
• [ ] Create samply-symbols/tests/linux_symbols_test.rs to test DWARF section parsing against fixtures/linux64-ci/firefox
• [ ] Add test for 32-bit symbol resolution using fixtures/android32-ci/libmozglue.so.dbg
• [ ] Document expected symbol lookup results for each fixture in samply-symbols/README.md

Create CI workflow for binary artifact compatibility testing

The repo has release.yml but no automated testing against the fixture binaries to ensure profiler output remains valid across platforms. The fixtures/other/ directory contains edge cases (non-PIE binaries in issue-776-nonpie-aarch64, fallback symbols) that should be validated in CI.

• [ ] Create .github/workflows/fixture-validation.yml that runs samply record against fixtures/other/simple-example on each commit
• [ ] Add a test that validates profiler output for the non-PIE aarch64 case (fixtures/other/issue-776-nonpie-aarch64)
• [ ] Add step to verify Firefox profile JSON output is valid against schema for fixtures/other/ls-linux/ls-profile.json
• [ ] Document expected profile output format in API.md for each fixture type

• Add integration tests for samply-symbols symbol resolution against real debuginfo files in fixtures/ directory (linux64-ci/firefox, macos-ci/libmozglue.dylib); currently no test coverage visible for cross-platform symbol lookup.
• Document the Windows symbol server URL format and retry behavior in API.md and README.md; current docs only show example URLs without explaining fallback behavior or timeout tuning.
• Add a samply show <profile.json> subcommand that pretty-prints recorded profile statistics (function counts, thread distribution, sample time range) without opening the browser; useful for CI/automation workflows.

The samply profiler codebase demonstrates reasonable security practices overall. It's a legitimate command-line profiling tool with multi-platform support. The main concerns are: (1) Platform-specific code (Windows ETW) requiring dedicated security review, (2) Security-sensitive operations documented without sufficient security guidance (Linux privilege escalation, symbol server configuration), and (3) Lack of formal security policy documentation. No evidence of hardcoded credentials, SQL injection, XSS, or critical infrastructure misconfigurations was found. The inclusion of binary fixtures in the repository presents a minor supply chain risk. Recommended actions: establish a security policy, improve security guidance in documentation, and ensure platform-specific code receives appropriate security audits.

• Medium · ETW-Reader Component Excluded from Standard Build — Cargo.toml (workspace root). The etw-reader crate is explicitly excluded from the workspace build on non-Windows platforms (see Cargo.toml: exclude = ["etw-reader"]). While this is intentional for cross-platform compatibility, it suggests platform-specific code that may not receive consistent security review across all build configurations. The etw-reader interacts with Windows ETW (Event Tracing for Windows) APIs which handle sensitive system-level tracing data. Fix: Ensure etw-reader receives regular security audits focused on Windows API interactions, buffer handling, and privilege escalation risks. Document the security considerations for Windows-specific profiling functionality.
• Medium · Incomplete Hardcoded Symbol Server URLs in Documentation — README.md. The README contains hardcoded symbol server URLs including Microsoft's Symbol Server and Mozilla's symbol server. While these are legitimate public services, documenting symbol server configuration in plaintext may expose users to MITM attacks if they copy-paste without verifying HTTPS, or may be exploited if documentation is compromised. Fix: Document symbol server configuration with explicit security warnings about HTTPS verification. Recommend using environment variables or config files for symbol server URLs rather than command-line arguments to prevent accidental exposure in process listings or shell history.
• Medium · Elevated Privileges Required on Linux — README.md. The README instructs users to set /proc/sys/kernel/perf_event_paranoid to -1 using sudo to enable profiling. While necessary for perf event tracing, this guidance could be exploited if a user follows it without understanding the security implications. This grants broad access to system profiling capabilities. Fix: Document security implications more clearly. Recommend using capability-based restrictions (CAP_PERFMON or CAP_SYS_ADMIN) via setcap instead of kernel-wide paranoid settings. Provide a secure setup script that uses least-privilege approaches.
• Low · Test Fixtures Contain Binary Debug Symbols — fixtures/ directory. The fixtures directory contains multiple binary files and debug symbol files (.dbg, .dSYM, DWARF sections) that could potentially contain sensitive information or be vectors for supply chain attacks if the repository is compromised. Fix: Consider moving large binary fixtures to a separate repository or CI-managed download. If fixtures must remain, implement integrity verification (checksums/signatures) and document their source and security status.
• Low · Missing SECURITY.md Policy — Repository root. No SECURITY.md or security policy file is present in the repository. This makes it difficult for security researchers to report vulnerabilities responsibly. Fix: Create a SECURITY.md file documenting responsible disclosure procedures, supported versions, and security contact information.
• Low · Dependabot Configuration Present but Not Visible — .github/dependabot.yml. A dependabot.yml configuration exists (.github/dependabot.yml), which is good practice, but the actual configuration content is not provided for review. Ensure dependency updates are properly configured with security focusing on Cargo dependencies. Fix: Verify that dependabot is configured to: check for security vulnerabilities in Rust crates, enable auto-merge for patch updates, and require review for minor/major updates.

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.