feat(cli): add walltime unwinding mode and stack sample size options by not-matthias · Pull Request #586 · CodSpeedHQ/codspeed

not-matthias · 2026-10-13T15:38:14Z

Summary

Add --walltime-unwinding-mode / CODSPEED_WALLTIME_UNWINDING_MODE and --walltime-stack-sample-size / CODSPEED_WALLTIME_STACK_SAMPLE_SIZE.
Keep --perf-unwinding-mode / CODSPEED_PERF_UNWINDING_MODE as a hidden, deprecated alias. The new option wins when both are set.
perf: use the explicit stack size instead of the inferred one (default stays 8192 bytes).
samply (Linux): forward --unwinding-mode and --unwinding-stack-size.

Notes

Depends on feat(linux): support frame-pointer-only recording samply-codspeed#12. The samply submodule must be bumped to include it; until then samply rejects these flags when the options are set.

Add --walltime-unwinding-mode (CODSPEED_WALLTIME_UNWINDING_MODE) and --walltime-stack-sample-size (CODSPEED_WALLTIME_STACK_SAMPLE_SIZE) so the call-stack collection can be tuned for both walltime profilers, perf and samply. --perf-unwinding-mode / CODSPEED_PERF_UNWINDING_MODE stays as a hidden, deprecated alias so existing setups keep working; the new option wins when both are set. perf: the explicit stack size overrides the size inferred from the command (default 8192 bytes). samply: on Linux, forward the options as --unwinding-mode and --stack-size.

Match the option name added to samply-codspeed.

codspeed · 2026-10-13T15:47:49Z

Merging this PR will not alter performance

⚠️

Unknown Walltime execution environment detected

Using the Walltime instrument on standard Hosted Runners will lead to inconsistent data.

For the most accurate results, we recommend using CodSpeed Macro Runners: bare-metal machines fine-tuned for performance measurement consistency.

⚠️

8 benchmarks spent significant time in system calls

System calls cannot be consistently instrumented, so they are not included in the measure, which understates the real cost. Please switch to the Walltime instrument to accurately measure system calls.

Measurement and system calls

encode_events_realistic[4]

encode_events_realistic[8]

encode_events_realistic[2]

encode_events_realistic[1]

find_module_events[1000000]

encode_events_realistic[16]

sleep 1

find_module_events_with_stacks[1000000]

✅ 41 untouched benchmarks
⏩ 6 skipped benchmarks¹

_{Comparing cod-3877-expose-stack-sampling-size-in-cli (3b356c9) with main (aa52796)}

6 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

greptile-apps · 2026-10-13T15:49:47Z

Confidence Score: 4/5

[Medium impact] Renames profiler configuration options and adds stack sample size tuning.

The reviewed changes appear safe to merge once the author’s stated samply prerequisite is met; the warning and test feedback are non-blocking.

Findings

Deprecation warning never appears ▶
Option rules lack tests ▶

Fix with agent prompt

### Issue 1
src/cli/shared.rs:258-260
Both `codspeed run` and `codspeed exec` call `resolve_unwinding_mode()` while building the config, before `Orchestrator::new()` installs the logger. This drops the warning, so users of `--perf-unwinding-mode` or `CODSPEED_PERF_UNWINDING_MODE` never learn about the replacement. Emit it after logger setup or use the existing startup-warning approach.

### Issue 2
src/cli/shared.rs:254-261
The new precedence and stack-size overrides have no tests. Add focused cases for the old option alone, both options together, flag/environment combinations, and an explicit size overriding both the default and Python's inferred size. These are the main promises of this change; tests would catch later edits that silently send the wrong value to the profiler.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

Adds walltime unwinding and stack-size options to run and exec.

Walltime profiler settings now choose unwinding mode and stack size.
The perf profiler now uses the requested DWARF stack size.
Linux samply runs now use the chosen unwinding settings.

Acknowledgment: not-matthias explicitly deferred bundled samply support and instructed that this PR wait for CodSpeedHQ/samply-codspeed#12. The known rejection of the new flags is not reported again.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A["run / exec flags and environment"] --> B["WalltimeRunArgs"]
  B --> C["resolve_unwinding_mode: new option wins"]
  B --> D["walltime_stack_sample_size"]
  C --> E["OrchestratorConfig"]
  D --> E
  E --> F["ExecutorConfig"]
  F --> G["perf: --call-graph"]
  F --> H["Linux samply: --unwinding-mode / --stack-size"]

_{Reviews (1) · Last reviewed commit: "feat(cli): add walltime unwinding mode a..." · Reviewed by Greptile}

greptile-apps · 2026-10-13T15:49:50Z

+        log::warn!(
+            "CODSPEED_PERF_UNWINDING_MODE / --perf-unwinding-mode is deprecated; use CODSPEED_WALLTIME_UNWINDING_MODE / --walltime-unwinding-mode instead."
+        );


Deprecation warning never appears

Both codspeed run and codspeed exec call resolve_unwinding_mode() while building the config, before Orchestrator::new() installs the logger. This drops the warning, so users of --perf-unwinding-mode or CODSPEED_PERF_UNWINDING_MODE never learn about the replacement. Emit it after logger setup or use the existing startup-warning approach.

Prompt To Fix With AI

This is a comment left during a code review. Path: src/cli/shared.rs Line: 258-260 Comment: **Deprecation warning never appears** Both `codspeed run` and `codspeed exec` call `resolve_unwinding_mode()` while building the config, before `Orchestrator::new()` installs the logger. This drops the warning, so users of `--perf-unwinding-mode` or `CODSPEED_PERF_UNWINDING_MODE` never learn about the replacement. Emit it after logger setup or use the existing startup-warning approach. --- For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

@not-matthias, this is a legit thing, and it's extremely annoying.
We may want to have a first logger before the full environment parsing at some point, or queue the logs until we've initialized the logger.

We could create a dedicated issue and just eprintln!() here

greptile-apps · 2026-10-13T15:49:50Z

+    pub fn resolve_unwinding_mode(&self) -> Option<UnwindingMode> {
+        let Some(legacy) = self.perf_unwinding_mode else {
+            return self.walltime_unwinding_mode;
+        };
+        log::warn!(
+            "CODSPEED_PERF_UNWINDING_MODE / --perf-unwinding-mode is deprecated; use CODSPEED_WALLTIME_UNWINDING_MODE / --walltime-unwinding-mode instead."
+        );
+        Some(self.walltime_unwinding_mode.unwrap_or(legacy))


Option rules lack tests

The new precedence and stack-size overrides have no tests. Add focused cases for the old option alone, both options together, flag/environment combinations, and an explicit size overriding both the default and Python's inferred size. These are the main promises of this change; tests would catch later edits that silently send the wrong value to the profiler.

Prompt To Fix With AI

This is a comment left during a code review. Path: src/cli/shared.rs Line: 254-261 Comment: **Option rules lack tests** The new precedence and stack-size overrides have no tests. Add focused cases for the old option alone, both options together, flag/environment combinations, and an explicit size overriding both the default and Python's inferred size. These are the main promises of this change; tests would catch later edits that silently send the wrong value to the profiler. --- For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

I don't think we really care for this one

Fair point — these tests are useful for regression protection but not essential to this change, so I’m withdrawing the suggestion. No action needed.

GuillaumeLagrange

some few quirks to make sure we handle properly

GuillaumeLagrange · 2026-10-16T12:44:32Z

+    /// Size in bytes of the user stack copied with each sample for DWARF unwinding.
+    /// Larger values produce deeper call stacks but bigger profiles.


we could provide the default value per language here if we expect users/agents to use this now

GuillaumeLagrange · 2026-10-16T12:46:25Z

+        log::warn!(
+            "CODSPEED_PERF_UNWINDING_MODE / --perf-unwinding-mode is deprecated; use CODSPEED_WALLTIME_UNWINDING_MODE / --walltime-unwinding-mode instead."
+        );


@not-matthias, this is a legit thing, and it's extremely annoying.
We may want to have a first logger before the full environment parsing at some point, or queue the logs until we've initialized the logger.

We could create a dedicated issue and just eprintln!() here

GuillaumeLagrange · 2026-10-16T12:46:42Z

+    pub fn resolve_unwinding_mode(&self) -> Option<UnwindingMode> {
+        let Some(legacy) = self.perf_unwinding_mode else {
+            return self.walltime_unwinding_mode;
+        };
+        log::warn!(
+            "CODSPEED_PERF_UNWINDING_MODE / --perf-unwinding-mode is deprecated; use CODSPEED_WALLTIME_UNWINDING_MODE / --walltime-unwinding-mode instead."
+        );
+        Some(self.walltime_unwinding_mode.unwrap_or(legacy))


I don't think we really care for this one

GuillaumeLagrange · 2026-10-16T12:48:12Z

+    /// Stack unwinding mode for the walltime profiler (if None, inferred from the command)
+    pub walltime_unwinding_mode: Option<UnwindingMode>,
+    /// User stack size in bytes copied per sample for DWARF unwinding (if None, profiler default)
+    pub walltime_stack_sample_size: Option<u32>,


I understand the separate flags for the cli, but here we could have them grouped? Cause technically the sample size makes no sense for fp etc, so even for clap it could make sense to parse it as an enum with two variants

FramePointer
and
Dwarf(Option<u32>) with the Option being here to see if we have an explicit setting or if we should default

GuillaumeLagrange · 2026-10-16T12:53:20Z

+            if let Some(mode) = config.walltime_unwinding_mode {
+                let mode = match mode {
+                    UnwindingMode::FramePointer => "fp",
+                    UnwindingMode::Dwarf => "dwarf",
+                };
+                args.extend(["--unwinding-mode".into(), mode.into()]);
+            }
+            if let Some(size) = config.walltime_stack_sample_size {
+                args.extend(["--unwinding-stack-size".into(), size.to_string().into()]);
+            }


You may want to check the implementation, but I'm 95% sure that in our samply fork we do both, so we should make sure we're not introducing unexpected behavior here

GuillaumeLagrange · 2026-10-16T12:54:06Z


        // Infer the unwinding mode from the benchmark cmd
-        let (cg_mode, stack_size) = if let Some(mode) = config.perf_unwinding_mode {
+        let (cg_mode, stack_size) = if let Some(mode) = config.walltime_unwinding_mode {


For the python/cargo/go tests:
We should not override specific stack size from cli IMO.
AND if we override it, we should DEFINITELY print a warning, but I think we should just outright take explicit cli over anything else

not-matthias marked this pull request as ready for review October 13, 2026 15:45

not-matthias requested a review from GuillaumeLagrange October 13, 2026 15:45

fix(samply): pass stack sample size as --unwinding-stack-size

3b356c9

Match the option name added to samply-codspeed.

greptile-apps Bot reviewed Oct 13, 2026

View reviewed changes

GuillaumeLagrange requested changes Oct 16, 2026

View reviewed changes

		/// Size in bytes of the user stack copied with each sample for DWARF unwinding.
		/// Larger values produce deeper call stacks but bigger profiles.

Conversation

not-matthias commented Oct 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Notes

Uh oh!

codspeed Bot commented Oct 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging this PR will not alter performance

Footnotes

Uh oh!

greptile-apps Bot commented Oct 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Confidence Score: 4/5

Findings

Summary

Diagram

Uh oh!

greptile-apps Bot Oct 13, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot Oct 13, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot Oct 16, 2026

Choose a reason for hiding this comment

Uh oh!

GuillaumeLagrange left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

not-matthias commented Oct 13, 2026 •

edited

Loading

codspeed Bot commented Oct 13, 2026 •

edited

Loading

greptile-apps Bot commented Oct 13, 2026 •

edited

Loading