Ask A BotHow to Write - Performance
The Performance section of the content covers performance instrumentation for our SDKs. A new framework can adopt the common content, which is stored in /docs/platforms/<SDK>/common/performance - feel free to peruse the files in that directory to help answer any questions.
Don't change the common content. That change will ripple across all guides that rely on the common content. Instead, open an issue on GitHub with questions or suggestions.
Determine if the page applies:
- If the content does not apply, add the guide to
notSupportedlist in the frontmatter of the file. This will turn off the display of the content for this guide. - If the content does apply, add the
includefile 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.
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 tracing.
To develop content for this file:
If the guide 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 guide 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 guide, 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 thesupportedlist or add the platform to thenotSupportedlist 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/docs/platforms/<SDK>/common/configuration/sampling.mdxand Tracing Options in/docs/platforms/<SDK>/common/configuration/options.mdx.Do one of the following based on whether automatic instrumentation is available for the guide 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 fromsupportedor 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 thesupportedlist or add it to thenotSupportedlist if automatic instrumentation is available.Determine if the paragraph regarding pageload and navigation applies to the guide. If so, add the guide to the
Supportedlist in the<PlatformSection>. If not, either omit the guide from thesupportedlist or add the guide to thenotSupportedlist, which will prevent the content from displaying for this guide.
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 framework is exposed as an experimental or an early access feature, add the guide 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 framework, find the <PlatformSection> wrapping the <PlatformContent> pointing to the unsupported file, and add your guide to its notSupported list. If such a <PlatformSection> doesn't already exist, create one and add your guide 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/.
Populate the sdk_name/common/performance/instrumentation/ directory with the file automatic-instrumentation.mdx.
This file is troubleshooting-performance.mdx. It explains corner cases and how to solve known issues.
Determine if the framework needs an illustration of how to group transactions. If so, add the framework to
Supportedlist in the<PlatformSection>, then add a code sample toperformance/group-transaction-example/. If not, add the framework tonotSupportedlist, which will prevent the Group Transactions heading from displaying for this framework.Add an example to
src/platform-includes/performance/control-data-truncation/
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").