How to Write - Performance
The Performance section of the content covers performance instrumentation for our SDKs. In most cases, the SDK will adopt the common content, which is stored in /platforms/common/performance/
- feel free to peruse the files in that directory to help answer any questions. However, each SDK will have its own page devoted to what instrumentation is automatic. We do not develop common content for this page, just its structure.
DO NOT change the common content. That change will ripple across all SDKs that rely on the common content. Instead, open an issue on GitHub with questions or suggestions.
Start Here
Determine if the page applies:
- If the content does not apply, add the SDK to
notSupported
list in the frontmatter of the file. This will turn off the display of the content for this SDK. - If the content does apply, add the
include
file to the correct directory as noted for each page. If the code sample is not provided, the page will display a big gray box requesting that customers open an issue for the missing sample.
Set Up
The set up page is where readers may start, though the note at the beginning directs into the instrumentation content, if applicable. The reader path depends on whether the SDK has already been instrumented for performance monitoring in the refreshed Getting Started page. For folks adopting this feature later, this page covers how to set up.
We expect this content to apply to all SDKS, as supported.
This file is index.mdx
. It explains how to install or set up (if appropriate) as well as how to enable
To develop content for this file:
If the SDK is still a work-in-progress and is exposed as an experimental or an early access feature, add the platform to the
<PlatformSection>
wrapping the appropriate alert located at the beginning of the content for the page.If the SDK is expected to be used in a high-throughput environment, add the platform to the following
<PlatformSection>
which advises testing before deploying to production.If automatic instrumentation is still in preview/beta for the SDK, add your platform to the next
<PlatformSection>
that wraps around text that discusses this.If automatic instrumentation is supported, add your platform to the
<PlatformSection>
immediately following Verify which advises users to either use auto or custom (or manual) instrumentation to verify the feature. Either omit the platform from thesupported
list or add the platform to thenotSupported
list if auto instrumentation is not available.Add a code sample to
/src/platform-includes/performance/configure-sample-rate/
that covers how to set sample rates. Make sure to update/platforms/common/configuration/sampling.mdx
and Tracing Options in/platforms/common/configuration/options.mdx
.Do one of the following based on whether automatic instrumentation is available for the SDK or not: a. If automatic instrumentation is supported, add your platform to the
<PlatformSection>
immediately following Verify which advises users to either use auto or custom (a.k.a. manual) instrumentation to verify the feature. Either omit the platform fromsupported
or the platform tonotSupported
.b. If automatic instrumentation is not supported, add your platform to the second
<PlatformSection>
after Verify which advises users to test out tracing using custom (manual) instrumentation. Omit the platform from thesupported
list or add it to thenotSupported
list if automatic instrumentation is available.Determine if the paragraph regarding pageload and navigation applies to the SDK. If so, add the SDK to the
Supported
list in the<PlatformSection>
. If not, either omit the platform from thesupported
list or add the platform to thenotSupported
list, which will prevent the content from displaying for this SDK.
Custom Instrumentation
We expect this content to apply to all SDKS.
This file is performance/instrumentation/custom-instrumentation.mdx
. It explains how to manually instrument transactions.
If custom instrumentation for the SDK is exposed as an experimental or an early access feature, add the platform to the <PlatformSection>
wrapping the appropriate alert located at the beginning of the content for the page.
To develop content for this file, add code samples to these directories:
/src/platform-includes/performance/enable-manual-instrumentation/
/src/platform-includes/performance/add-spans-example/
/src/platform-includes/performance/retrieve-transaction/
If any of the above files are not applicable to your platform, find the <PlatformSection>
wrapping the <PlatformContent>
pointing to the unsupported file, and add your platform to its notSupported
list. If such a <PlatformSection>
doesn't already exist, create one and add your platform to its notSupported
list.
Then, determine whether to provide a code sample illustrating how to connect errors and spans. If so, add the SDK to the Supported
list in the appropriate <PlatformSection>
, then add a code sample /src/platform-includes/performance/connect-errors-spans/
.
Automatic Instrumentation
This page does not use common content. It covers what instrumentation is automatic when
Populate the sdk_name/common/performance/instrumentation/
directory with the file automatic-instrumentation.mdx
.
Troubleshooting
This file is troubleshooting-performance.mdx
. It explains corner cases and how to solve known issues.
Determine if the SDK needs an illustration of how to group transactions. If so, add the SDK to
Supported
list in the<PlatformSection>
, then add a code sample toperformance/group-transaction-example/
. If not, add the SDK tonotSupported
list, which will prevent the Group Transactions heading from displaying for this SDK.Add an example to
src/platform-includes/performance/control-data-truncation/
Sampling
Guidelines TBD.
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").