mstange/samply

Samply is a cross-platform command-line CPU profiler that records performance data on Windows, macOS, Linux, and Android, then serves the results via a local API for analysis in the Firefox Profiler UI. It features a robust symbolication engine capable of resolving addresses across diverse binary formats and debug sources, including Breakpad, PDB, dSYM, and DWARF. The system also provides utilities for importing external trace formats, disassembling code, and managing cached symbol files.

34 changes.

The project was rebranded from profiler-get-symbols to Samply, shifting from a WebAssembly utility to a full-featured command-line CPU profiler with a Firefox Profiler UI. This period involved a major architectural overhaul, including a Cargo workspace restructuring, the introduction of the wholesym library for cross-platform symbol resolution, and the addition of native profiling support for Linux and macOS alongside Windows ETW capabilities.

14 changes.

This period focused on adding Windows profiling capabilities via Event Tracing for Windows (ETW) and establishing a robust, modular symbolication infrastructure. New crates were introduced to handle binary metadata extraction, disk usage limits for cached symbols, and address-to-source translation, while the core profiler gained enhanced JIT symbolication and dynamic marker schema support.

The API now includes a new \/asm/v1\ endpoint that returns disassembled machine code for a specified library and address range. Clients send a JSON request containing the library identifier (via \debugId\ or \codeId\), the \startAddress\, and the \size\ of the code block to disassemble. The response includes the CPU architecture (\arch\), the disassembly syntax used (e.g., \Intel\), and a list of decoded instructions with their offsets and assembly strings. The endpoint supports an optional \continueUntilFunctionEnd\ flag to extend the disassembly to the end of the containing function, and it resolves branch targets using symbol information when available.

samply-api/src/asm · high confidence

A new \dump\_table\ CLI tool has been added to the \tools/\ directory, allowing users to retrieve and display the symbol table for a given binary. The tool uses the \wholesym\ library to load symbols asynchronously and supports an optional \--full\ flag to print the entire list of symbols. It also handles multi-architecture (fat) archives by prompting the user to specify a specific breakpad ID if multiple architectures are present.

_tools/dump\table · high confidence

A local copy of the \etw-reader\ crate has been added to \samply/src/windows/etw\_reader\ to provide Windows Event Tracing for Windows (ETW) parsing capabilities within Samply. This module includes custom schema definitions for kernel trace events (such as ImageID and DbgID), a parser for decoding event buffers, and utilities for handling TDH (Trace Data Helper) types and SDDL strings. The implementation uses standard library types like \std::cell::OnceCell\ and the \rustc\_hash\ library for performance, ensuring the reader functions correctly even before the published crates.io version is updated.

_samply/src/windows/etw\reader · high confidence

The symbol lookup system now supports Breakpad symbol files (.sym) and the associated .symindex binary format. This change introduces a new \BreakpadIndex\ parser that reads module metadata, symbol addresses, and file/inline origin lists from the index, and a \BreakpadSymbolMap\ implementation that maps addresses to function names and source lines. Users can now debug applications that provide Breakpad-style symbols, with the system automatically generating or consuming pre-built indexes to optimize lookup performance.

samply-symbols/src/breakpad · high confidence

Users can now import performance profiles generated by Linux \perf.data\ and Android \simpleperf\ tools. The new import module handles architecture-specific unwinding for x86\_64 and aarch64, resolves symbols using binary and auxiliary file lookup directories, and correctly processes JIT dump information. It also extracts metadata such as the operating system version, command line arguments, and device information (for simpleperf) to provide richer context in the resulting profile.

samply/src/import · high confidence

Added the new \wholesym-addr2line\ package, which serves as a drop-in replacement for \addr2line\ with support for additional symbol-finding methods. This change includes the package's README documentation and the necessary Apache 2.0 and MIT license files to satisfy release tooling requirements.

wholesym-addr2line · high confidence

A new macOS preload library (libsamply\_mac\_preload.dylib) has been added to support JIT dump forwarding on macOS. The build process creates a universal binary containing x86\_64, arm64, and arm64e variants, targeting macOS 10.12+ for Intel and macOS 11+ for Apple Silicon. The library is compressed and stored within the main samply application resources to minimize footprint.

samply-mac-preload · high confidence

Samply now supports recording performance profiles on Linux. This change introduces the core Linux-specific modules (\samply/src/linux\) including \perf\_event\ for interacting with the kernel's perf subsystem, \perf\_group\ for managing multiple hardware and software events, \proc\_maps\ for parsing process memory maps, \process\ for launching and attaching to child processes, and \profiler\ to orchestrate the recording. Users can now use \samply record\ on Linux to profile launched commands or attach to existing PIDs, with support for CPU cycles, context switches, and stack unwinding.

samply/src/linux · high confidence

Samply now supports recording and importing performance profiles on Windows using Event Tracing for Windows (ETW). This adds a new \samply/src/windows\ module that orchestrates an elevated helper process to run \xperf\, capturing kernel and user-mode data. The implementation includes specific parsers for Chrome and Firefox browser events, support for .NET CoreCLR profiling, and graphics (DXGI) tracing. Users can now record profiles on Windows, which are processed into the standard fxprof format for analysis.

samply/src/windows · high confidence

The \samply-quota-manager\ crate now enforces configurable limits on the disk space and age of cached symbol files. It tracks file metadata in a SQLite database and runs a background task to evict least-recently-used files when the total size exceeds a set threshold or files exceed a maximum age, ensuring that symbol file storage remains bounded.

samply-quota-manager/src · high confidence

A new \query\_api\ CLI tool is added to the \tools\ directory, allowing users to query the Tecken JSON symbolication API (\/symbolicate/v5\) against a local symbol directory. The tool accepts a symbol directory path, an API URL, and request JSON (either directly or via a file path prefixed with \@\), then outputs the resulting JSON response to stdout.

_tools/query\api · high confidence

The \etw-reader\ library is added as a new crate to provide Windows Event Tracing for Windows (ETW) capabilities. It exposes a public API for opening trace log files and processing events via callbacks, along with a \SchemaLocator\ to resolve event schemas from metadata or custom definitions. The crate includes a \Parser\ module to decode event property buffers into typed values (such as strings, integers, and pointers) and defines internal types for TDH properties, event records, and trace control structures.

etw-reader/src · high confidence

A new \wholesym\ crate has been added to provide a unified, asynchronous interface for locating and downloading symbol files. It consolidates support for Breakpad symbol servers and directories, Windows symbol servers (via symsrv), and debuginfod servers into a single \SymbolManager\. The implementation features an asynchronous download pipeline with gzip decompression, configurable retry policies with exponential backoff for transient errors, and an in-memory negative cache to avoid repeated 404s. It also introduces a \DownloaderObserver\ trait for progress reporting and integrates with a new \async\_double\_buffer\ and \AsyncGzipDecoder\ for efficient streaming.

wholesym/src · high confidence

A new command-line tool, wholesym-addr2line, is added to provide a fast, cross-platform equivalent of the standard addr2line utility. It allows users to translate memory addresses from executables into source file paths and line numbers, supporting features such as displaying function names, handling inlined functions, outputting in LLVM-compatible format, and interpreting addresses as relative or file offsets. The tool leverages the wholesym library for symbol resolution and includes options for demangling names and printing base filenames only.

wholesym-addr2line/src · high confidence

A new \wholesym\ crate has been added, providing a library for fetching symbol files and resolving code addresses to symbols and debug information on Windows, macOS, and Linux. The library supports various symbol sources including PDBs, dSYMs, DWARF, Breakpad, and split DWARF (.dwo/.dwp files), and is licensed under Apache-2.0/MIT.

wholesym · high confidence

The API now includes a new \/source/v1\ endpoint that allows clients to retrieve the full source code for files referenced in symbolication results. This feature supports complex debugging workflows, including macOS OSO-stab and ELF DWO (DWARF in Object) files, by implementing a state machine that can chase external file references and resolve source paths. Users can request source files by providing the library's debug name, debug ID, module offset, and the exact file path returned by the \/symbolicate/v5\ endpoint.

samply-api/src/source · high confidence

The \etw-reader/examples\ directory now includes several new demonstration programs that showcase advanced Event Tracing for Windows (ETW) capabilities. \list-processes.rs\ and \list-threads.rs\ demonstrate enumerating running processes and threads, including parsing command lines and thread names. \log-stacks.rs\ and \log-js-stacks.rs\ provide examples for capturing and analyzing kernel and user-mode stack traces, with the latter specifically handling JavaScript/V8 method symbols. \dump.rs\ offers a detailed event dumper that supports filtering by pattern, printing activity IDs, and parsing extended data like TraceLogging schemas and provider traits. Additionally, \list-providers.rs\ shows how to enumerate available ETW providers using \EnumerateTraceGuidsEx\, and \event-types.rs\ counts and displays the frequency of different event types in a trace file.

etw-reader/examples · high confidence

This change introduces the \linux\_shared\ module, providing the core infrastructure for converting Linux profiling data (perf.data, simpleperf) into samply profiles. It includes a new \Converter\ to handle event interpretation and symbolication, support for kernel symbol parsing via \/proc/kallsyms\, and specific workarounds for broken JIT ELF files generated by certain versions of \perf\. The module also adds support for PE mapping correlation on Linux (e.g., for Wine), RSS stat markers, and context switch markers.

_samply/src/linux\shared · high confidence

Added a new \utility\_process\ module that enables the main application to launch and communicate with a separate, elevated helper process on Windows. This helper runs with Administrator privileges (required for tasks like ETW recording) and communicates with the parent via a file-based bidirectional channel using JSON messages, allowing the parent to send commands and receive responses or errors without the helper displaying a console window.

_samply/src/windows/utility\process · high confidence

A new Rust crate, gecko\_profile, has been introduced to generate profiles in the Gecko profiler JSON format. It provides a ProfileBuilder API for constructing profiles, including support for adding libraries, threads, and subprocesses. The crate features a marker system that allows defining custom marker types with specific schemas (e.g., Text, custom markers with fields like URL, latency, allocation size) and serializes them into the profile's marker table and schema metadata. The output is a JSON structure compatible with version 24 of the Gecko profiler format, including metadata like start/end times, intervals, and sample units.

_gecko\profile · high confidence

This change introduces the complete macOS backend for samply, enabling process profiling on macOS. It includes a codesigning setup utility that automatically signs the samply binary with the necessary debugger entitlements to allow attaching to existing processes. The implementation adds low-level Mach IPC bindings, dyld image enumeration to track loaded libraries, and a sampler that captures stack traces and timestamps using Mach absolute time. It also supports launching child processes with a preload library for instrumentation, handling JIT dumps and marker files, and managing thread lifecycles via Mach ports.

samply/src/mac · high confidence

A new \samply-debugid\ crate has been introduced to handle binary identification logic compatible with the \samply\ profiler. It provides a \CodeId\ enum that distinguishes between Windows PE code IDs, macOS/iOS Mach-O UUIDs, and Linux ELF build IDs, allowing users to generate and parse identifiers necessary for symbolication. Additionally, it exposes a \DebugIdExt\ trait that extends the standard \debugid\ crate with methods to create debug IDs from raw identifiers or text section hashes, ensuring compatibility with existing symbol server workflows.

samply-debugid · high confidence

A new \samply-object\ crate has been introduced to provide standalone functions for extracting \DebugId\s, \CodeId\s, and relative base addresses from object files. This library supports ELF, mach-O, and PE/Windows binaries, enabling users to generate the necessary metadata for symbolication and display via \samply load\.

samply-object · high confidence

The \samply/src/shared\ module now provides a suite of new components to enhance profile accuracy and usability. A \ContextSwitchHandler\ simulates off-CPU sampling by accumulating sleep durations and emitting samples when they exceed a threshold, providing a more complete view of thread activity. JIT symbolication is significantly improved via a \JitCategoryManager\ that classifies functions from JSC, V8, and other engines into specific categories (e.g., Baseline, Turbofan, Interpreter) with distinct colors, while a \JitFunctionRecycler\ collapses similar JIT functions across multiple recording iterations to reduce noise. The system now supports reading JIT information from \jitdump\ files and \perf.map\ files, automatically creating synthetic libraries and mapping addresses to symbols. Additionally, new marker support includes \MarkerFile\ parsing for Linux and macOS to import external event traces, and \Cpus\ tracking to generate context-switch markers for CPU and thread tracks. Graceful Ctrl+C handling is also added to allow long-running server operations to be interrupted cleanly.

samply/src/shared · high confidence

The marker module has been split into distinct files to support both static (compile-time) and dynamic (runtime) marker schemas. This introduces the \DynamicSchemaMarker\ trait and \DynamicSchemaMarkerSchema\ struct, allowing users to define marker types and their fields at runtime. The change adds granular field formats (e.g., \Url\, \FilePath\, \Duration\, \Bytes\) and explicit PII categories (\MarkerFieldPIICategory\), enabling the Firefox Profiler to automatically redact sensitive data like URLs and file paths when users sanitize profiles before uploading. It also defines graph types (\Bar\, \Line\, \LineFilled\) and display locations for richer visualization in the profiler UI.

fxprof-processed-profile/src/markers · high confidence

The \samply-mac-preload\ library on macOS now intercepts \open\ and \fopen\ calls to automatically detect and report JIT dump files (matching \jit-\.dump\) and marker files (matching \marker-\.txt\) to the parent process. This enables the profiler to capture JIT-compiled code and custom marker events without requiring manual file path configuration, while also establishing an early Mach IPC connection to coordinate with the parent process.

samply-mac-preload/src · high confidence

The legacy WASM-based symbolication module has been removed. This change deletes the \src/lib.rs\ entry point and the associated \compact\_symbol\_table\, \elf\, and \macho\ modules that previously handled symbol table generation for ELF and Mach-O binaries using the \goblin\ and \object\ crates. Users relying on this specific WASM interface for symbolication will no longer have access to these functions.

src · high confidence

A change to existing behaviour in fixtures/macos-local, fixtures/win64-ci — 1 commit, 10 files.

fixtures/android32-ci, fixtures/macos-local, fixtures/win64-ci, fixtures/win64-local · medium confidence · unverified

The benchmark tool in tools/benchmarks has been updated to exercise the symbolication API using the v5 endpoint (/symbolicate/v5) across Windows, macOS, Linux, and Android platforms. This change replaces previous fixture URLs and benchmark actions to align with the modern API version, ensuring performance metrics reflect the current symbolication implementation.

tools/benchmarks · high confidence

The fxprof-processed-profile crate has been rewritten to support processed profile format versions up to 75, introducing significant structural and API changes. The internal data storage has shifted to a columnar layout using a new ColumnarInterner, which deduplicates and stores table data (such as functions and frames) in column-by-column fashion for improved serialization performance and memory efficiency. A new category system has been added, allowing profiles to define named categories with specific colors and subcategories, which are used to annotate stack frames and markers in the profiler UI. Additionally, support for counters has been introduced, enabling the tracking of numeric quantities over time (like memory usage) with configurable graph types and detailed tooltip formats. The public API has been updated to reflect these changes, including new types for category handling, counter management, and frame addressing, while maintaining compatibility with the Firefox Profiler's processed profile format.

fxprof-processed-profile/src · high confidence

The \samply-api\ crate has been restructured to expose a sans-IO state machine for JSON API queries (such as \/symbolicate/v5\, \/source/v1\, and \/asm/v1\). Instead of direct file access, the API now returns a state machine that signals file-fetching needs (symbol maps, source files, binaries) via a \poll\ method, allowing consumers to drive I/O externally. Error responses are now serialized as structured JSON objects containing a \title\ field rather than plain strings, and the API provides methods to determine the appropriate HTTP status code for both errors and successful results.

samply-api/src · high confidence

The symbolication engine in samply-symbols has been refactored to use a new SymbolMap abstraction, replacing previous internal structures like GenericSymbolMap and partial\_frames. This change introduces a chunked read buffer manager for more efficient file I/O and caching, and updates the BinaryImage and ExternalFile handling to support modern object formats. The refactoring also includes improvements to demangling (supporting Scala Native and OCaml), better handling of ELF debug links and alt-links, and optimized memory usage for symbol tables.

samply-symbols/src · high confidence

The project has been renamed from 'profiler-get-symbols' to 'samply', shifting its identity from a WebAssembly symbol-dumping utility to a full command-line CPU profiler that uses the Firefox Profiler as its UI. This change includes the addition of comprehensive documentation (README.md, API.md, RELEASES.md) detailing installation, usage, and supported platforms (macOS, Linux, Windows). The old WebAssembly test page (index.html) and associated JavaScript bindings (profiler\_get\_symbols.js) have been removed, while the build system has been updated with Nix flake support (flake.nix, flake.lock) and a new distribution configuration (dist-workspace.toml). The repository's licensing has also been updated to reflect Mozilla Foundation copyright.

(repo-wide) · high confidence

The symbolication endpoint in \samply-api/src/symbolicate\ now validates \debug\_filename\ and \debug\_id\ fields in incoming requests, rejecting invalid characters or non-hex IDs to prevent malformed data from causing errors. Additionally, the implementation supports external debug files (such as macOS OSO-stab and ELF DWO), allowing the API to chase frame references across separate symbol files. The response structure has been updated to include \SymbolicateStats\ for observability, and the internal state machine has been refactored to handle these external lookups efficiently.

samply-api/src/symbolicate · high confidence

Samply now features a completely restructured command-line interface with dedicated subcommands for recording, loading, and importing profiles, supporting Windows, macOS, Linux, and Android. The tool can now record profiles on Windows and Linux, import perf.data and ETL files, and automatically presymbolicate profiles before saving. A built-in local server serves the profile and symbols to the Firefox Profiler UI, with support for environment variable overrides (SAMPLY\_SERVER\_URL, PROFILER\_URL) and configurable symbol directories and servers.

samply/src · high confidence

A fix in fixtures/linux64-ci — 1 commit (1 fix), 1 file.

fixtures/linux64-ci · low confidence · unverified

Add dSYM fixture for libmozglue.dylib; Add integration tests for symbol loading and snapshot verification; Add integration tests for the samply-api query and disassembly endpoints; Added fixture for abstract linkage name symbolication; Added fixture for testing debugaltlink symbolication; Added fixture scripts for DWO, DWP, OSO, and dSYM debug formats; Added integration test snapshots for processed profile serialization; Added integration tests for QuotaManager eviction logic; Added integration tests for fxprof-processed-profile; Added integration tests for symbolication and library info; Added non-PIE AArch64 fixture for issue \#776.

The repository has been converted into a Cargo workspace, splitting the codebase into multiple crates including samply, samply-symbols, samply-api, wholesym, and others, while excluding etw-reader from the main workspace. This restructuring is accompanied by significant dependency updates across the manifests, such as upgrading reqwest to 0.13, tokio to 1.52, clap to 4, and object to 0.40, alongside the addition of new crates like samply-quota-manager and samply-object.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 65 → 67 (+1.5)
• Rubric changed (rubric-2026.09.11 → rubric-2026.09.18) — scores are not directly comparable.

• Code Health 85 → 85 (-0.1)
• Architecture 95 → 95 (-0.3)
• Maturity 59 → 59 (+0.0)
• Readiness 66 → 66 (+0.1)
• Security 62 → 69 (+7.2)
• Performance 100 (new)

• Documentation: no installation or build instructions (README.md)
• Documentation: no usage examples (README.md)
• Duplicated block (6 lines × 2) (fxprof-processed-profile/src/func_table.rs)
• Hotspot: samply-symbols/src/macho.rs (samply-symbols/src/macho.rs)
• Hotspot: samply/src/linux_shared/converter.rs (samply/src/linux_shared/converter.rs)

• Confusing separation of concerns between Api.build_query and the specific *ApiQueryState constructors. Api.build_query takes a URL and JSON, while the specific query states (Source, Symbolicate) have from_request_json constructors. It is unclear how Api.build_query relates to these specific states. If Api.build_query is a factory, it should return the appropriate ApiQueryState or a generic builder. The existence of multiple from_request_json methods on different types suggests a lack of a unified entry point for query processing.
• Duplicated block (6 lines × 2) (fxprof-processed-profile/src/native_symbols.rs)
• Hotspot: samply-symbols/src/symbol_map_object.rs (samply-symbols/src/symbol_map_object.rs)
• Inconsistent naming for handle creation. The Profile type uses handle_for_ prefix for creating handles for categories, strings, frames, etc. However, InternalCategory uses index_for_subcategory. This mixes 'handle' and 'index' terminology for similar concepts (identifiers/lookups) within the same domain. Additionally, handle_for_frame_with_label and handle_for_frame_with_address are distinct methods for similar intents (getting a frame handle), which is acceptable, but the lack of a unified handle_for_frame with a discriminator or enum argument increases API complexity.
• Inconsistent naming for property retrieval/access. TraceEventInfoRaw exposes a raw pointer accessor with a generic name info_as_ptr, while the Parser component uses find_property to locate specific data. More critically, TypedEvent and EventSchema both expose property(index: u32): Property, but Parser uses find_property(name: str). This forces consumers to use different methods (find_property vs property) depending on whether they are using the low-level Parser or the higher-level TypedEvent/EventSchema abstractions, despite both ultimately accessing event properties.
• Low cohesion: SymbolManagerConfig (LCOM4 13) (wholesym/src/config.rs)
• Medium vulnerability: RUSTSEC-2026-0285 (Cargo.lock)
• Off the main sequence: fxprof-processed-profile
• Off the main sequence: samply-quota-manager
• Redundant API surface for schema registration. SchemaLocator has an instance method add_custom_schema, but the module-level function etw_reader.add_custom_schemas takes a SchemaLocator as an argument. It is unclear if the module function performs a different operation (e.g., global registration) or if it is a redundant wrapper. If it just calls the instance method, the module function is unnecessary noise. If it does something else, the naming is ambiguous.
• Split samply
• SymbolList::new (cyclomatic 16) (samply-symbols/src/symbol_map_object.rs)

• 17 commits — 17 feature/other, 0 fixes

• fxprof-processed-profile/src — 5 commits
• (repo) — 4 commits
• samply-symbols/src — 4 commits
• fxprof-processed-profile/tests — 2 commits
• (root) — 1 commit
• wholesym/src — 1 commit

• change: Add SymbolMap::set_access_pattern_hint to wholesym.
• change: Add test helpers for looking up objects and columns in JSLB output.
• change: Apply symbol list memory optimization for PLT stubs.
• change: Apply symbol list memory optimization for exports.
• change: Bump mach2 from 0.6.0 to 0.7.0
• change: Bump mach2 from 0.6.0 to 0.7.0 (#877)
• change: Emit processed profile format version 72.
• change: Emit processed profile format version 73.
• change: Emit processed profile format version 74.
• change: Emit processed profile format version 75.
• change: Emit profiles of v75 (#886)
• change: Further reduce SymbolList memory.
• change: Intern frames in two levels: template + address.
• change: Reduce SymbolList memory usage.
• change: Reduce memory for ELF objects with lots of symbols (#878)
• change: Stop splitting the frame table and func table into their own JSON slabs.
• change: Two memory consumption improvements (#879)

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

mstange/samply was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.