From 9381394c889fe8c71b13c301c735e4c0d007cbf6 Mon Sep 17 00:00:00 2001 From: Burak Yigit Kaya Date: Wed, 20 Nov 2024 12:46:07 +0000 Subject: [PATCH 1/2] feat(profilin): Add explanation for lockstep sampling We had this odd sampling frequency value in our docs which looks like a typo but it is not. This PR adds a note box to reassure the readers with some explanation and a reference link to why. --- .../sdk/telemetry/profiles/sample-format-v1.mdx | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/develop-docs/sdk/telemetry/profiles/sample-format-v1.mdx b/develop-docs/sdk/telemetry/profiles/sample-format-v1.mdx index d24c8daf18ddab..01854786dec9f3 100644 --- a/develop-docs/sdk/telemetry/profiles/sample-format-v1.mdx +++ b/develop-docs/sdk/telemetry/profiles/sample-format-v1.mdx @@ -295,6 +295,18 @@ stack ID. You should collect samples at a frequency of 101Hz, or roughly once every 10 milliseconds. + +The 101Hz number above is not a typo. It is intentionally slightly off from 100Hz to avoid a condition +named "lockstep sampling" where the profiling samples occur at the same frequency as a loop in the +application. Ideally, the samples should be much more frequent than any cycles in the application, or +at random intervals, so that the chance it occurs in any particular operation is proportional to the +amount of time that operation takes. But this is often not feasible, so the next best thing is to use +a sampling rate that doesn't coincide with the likely frequency of program cycles. + +This explanation is an excerpt from [this awesome StackOverflow answer](https://stackoverflow.com/a/45471031/1181370) +which has more details and a nice analogy for the issue. + + `samples` : *List, required* Contains a list of sample object captured during execution. From 2c8f18da0c9c24c0b5bda40d09f3b67733acd35e Mon Sep 17 00:00:00 2001 From: Burak Yigit Kaya Date: Wed, 20 Nov 2024 20:23:37 +0000 Subject: [PATCH 2/2] prime context Co-authored-by: Andrew McKnight --- develop-docs/sdk/telemetry/profiles/sample-format-v1.mdx | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/develop-docs/sdk/telemetry/profiles/sample-format-v1.mdx b/develop-docs/sdk/telemetry/profiles/sample-format-v1.mdx index 01854786dec9f3..fddbbf7b2afdf8 100644 --- a/develop-docs/sdk/telemetry/profiles/sample-format-v1.mdx +++ b/develop-docs/sdk/telemetry/profiles/sample-format-v1.mdx @@ -301,7 +301,10 @@ named "lockstep sampling" where the profiling samples occur at the same frequenc application. Ideally, the samples should be much more frequent than any cycles in the application, or at random intervals, so that the chance it occurs in any particular operation is proportional to the amount of time that operation takes. But this is often not feasible, so the next best thing is to use -a sampling rate that doesn't coincide with the likely frequency of program cycles. +a sampling rate that doesn't coincide with the likely frequency of program cycles. + +We also chose 101 for its primality, whereas 1 below 100–99–is evenly divisible by several +smaller numbers, which could lead to similar lockstep behavior. This explanation is an excerpt from [this awesome StackOverflow answer](https://stackoverflow.com/a/45471031/1181370) which has more details and a nice analogy for the issue.