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.

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:

1. 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.

2. 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.

3. 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.

4. 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 the supported list or add the platform to the notSupported list if auto instrumentation is not available.

5. 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.

6. 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 from supported or the platform to notSupported.

   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 the supported list or add it to the notSupported list if automatic instrumentation is available.

7. 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 the supported list or add the platform to the notSupported 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

is enabled for this SDK.

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.

1. 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 to performance/group-transaction-example/. If not, add the SDK to notSupported list, which will prevent the Group Transactions heading from displaying for this SDK.

2. Add an example to src/platform-includes/performance/control-data-truncation/

Sampling

Guidelines TBD.