--- title: "How to Write - Performance" url: https://docs.sentry.io/contributing/approach/sdk-docs/write-performance/ --- # How 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//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. ## [Start Here](https://docs.sentry.io/contributing/approach/sdk-docs/write-performance.md#start-here) Determine if the page applies: * If the content **does not apply**, add the guide to `notSupported` list 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 `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](https://docs.sentry.io/contributing/approach/sdk-docs/write-performance.md#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 tracing. To develop content for this file: 1. 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 `` wrapping the appropriate alert located at the beginning of the content for the page. 2. If the guide is expected to be used in a high-throughput environment, add the platform to the following `` which advises testing before deploying to production. 3. If automatic instrumentation is still in preview/beta for the guide, add your platform to the next `` that wraps around text that discusses this. 4. If automatic instrumentation is supported, add your platform to the `` 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 `/docs/platforms//common/configuration/sampling.mdx` and **Tracing Options** in `/docs/platforms//common/configuration/options.mdx`. 6. 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 `` 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 `` 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 guide. If so, add the guide to the `Supported` list in the ``. If not, either omit the guide from the `supported` list or add the guide to the `notSupported` list, which will prevent the content from displaying for this guide. ### [Custom Instrumentation](https://docs.sentry.io/contributing/approach/sdk-docs/write-performance.md#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 framework is exposed as an experimental or an early access feature, add the guide to the `` 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 `` wrapping the `` pointing to the unsupported file, and add your guide to its `notSupported` list. If such a `` 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 ``, then add a code sample `/src/platform-includes/performance/connect-errors-spans/`. ### [Automatic Instrumentation](https://docs.sentry.io/contributing/approach/sdk-docs/write-performance.md#automatic-instrumentation) Populate the `sdk_name/common/performance/instrumentation/` directory with the file `automatic-instrumentation.mdx`. ### [Troubleshooting](https://docs.sentry.io/contributing/approach/sdk-docs/write-performance.md#troubleshooting) This file is `troubleshooting-performance.mdx`. It explains corner cases and how to solve known issues. 1. Determine if the framework needs an illustration of how to group transactions. If so, add the framework to `Supported` list in the ``, then add a code sample to `performance/group-transaction-example/`. If not, add the framework to `notSupported` list, which will prevent the **Group Transactions** heading from displaying for this framework. 2. Add an example to `src/platform-includes/performance/control-data-truncation/` ### [Sampling](https://docs.sentry.io/contributing/approach/sdk-docs/write-performance.md#sampling) Guidelines TBD.