Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(js): Update profiling docs #12161

Open
wants to merge 10 commits into
base: master
Choose a base branch
from
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ title: BrowserProfiling
description: "Capture profiling data for the Browser."
notSupported:
- javascript.cordova
- javascript.capacitor
- javascript.node
- javascript.aws-lambda
- javascript.azure-functions
Expand Down
83 changes: 83 additions & 0 deletions docs/platforms/javascript/common/profiling/browser-profiling.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
---
title: Browser Profiling
sidebar_order: 5000
supported:
- javascript
notSupported:
- javascript.bun
- javascript.cordova
- javascript.capacitor
- javascript.deno
- javascript.cloudflare
- javascript.node
- javascript.aws-lambda
- javascript.azure-functions
- javascript.connect
- javascript.express
- javascript.fastify
- javascript.gcp-functions
- javascript.hapi
- javascript.koa
- javascript.nestjs
description: "Collect & view performance insights for JavaScript programs with Sentry’s JavaScript Profiling integration. Get started with browser profiling here."
JonasBa marked this conversation as resolved.
Show resolved Hide resolved
---

<Note>

Browser Profiling is currently in beta. Beta features are still in progress and may have bugs. We recognize the irony.

</Note>

The browser profiling integration is built using [JS Self-Profiling API](https://wicg.github.io/js-self-profiling/) and will likely only move out of beta once the specification progresses and gains adoption. See platform [status](https://chromestatus.com/feature/5170190448852992).
JonasBa marked this conversation as resolved.
Show resolved Hide resolved

Note that since the profiling API is currently only exposed in Chromium, profiles collected only include that demographic. This is obvious, but should not be forgotten when analyzing the data collected. We hope that as the API gains adoption, other browsers will implement it as well.
JonasBa marked this conversation as resolved.
Show resolved Hide resolved

<PlatformContent includePath="profiling/index/why-profiling" />

## Prerequisites

To get started with JavaScript browser profiling, you'll need to:

- Install the <PlatformSdkPackageName fallback="@sentry/browser"/> SDK, minimum version 7.60.0
- Configure the document response header to include `Document-Policy: js-profiling`
- Configure the SDK to use the `BrowserProfilingIntegration` and set `profilesSampleRate`

## Step 1: Install the <PlatformOrGuideName/> SDK

<PlatformSection notSupported={["javascript.electron"]}>

Install our <PlatformOrGuideName/> SDK using either `yarn` or `npm`, the minimum version that supports profiling is **7.60.0**.

</PlatformSection>

<PlatformSection supported={["javascript.electron"]}>

Install our Electron SDK using either `yarn` or `npm`, the minimum version that supports profiling is **4.16.0**.

</PlatformSection>

<PlatformContent includePath="profiling/automatic-instrumentation-intro" />

## Step 2: Add Document-Policy: js-profiling header

For the JavaScript browser profiler to start, the document response header needs to include a `Document-Policy` header key with the `js-profiling` value.

<PlatformContent includePath="profiling/automatic-instrumentation-headers" />

## Step 3: Configure the <PlatformOrGuideName/> SDK

Configuration should happen as early as possible in your application's lifecycle. Once this is done, Sentry's JavaScript SDK will capture all unhandled exceptions and transactions.

<PlatformContent includePath="profiling/automatic-instrumentation-setup" />

## The Difference Between DevTools & Sentry's JavaScript Browser Profiler

What does Sentry's JavaScript browser profile offer that Chrome DevTools does not?

- Sentry JavaScript profiler runs in production and captures real user data, showing real-world performance. DevTools runs locally on your machine and only shows profiles of what's running on your machine.
JonasBa marked this conversation as resolved.
Show resolved Hide resolved
- Sentry runs at a lower sampling rate of 100Hz with a 10ms sample period versus a sampling rate of 1000Hz and a 1ms sample period for DevTools.
- Sentry supports deobfuscation, making it so that all the function names in your code are correct. Typically, when you run JavaScript code, it's minified, meaning that all the function names are replaced with machine-generated abbreviations.

Please note, that since the browser profiling API is currently only implemented in Chromium-based browsers, the profiles collected with Sentry's JavaScript browser profiling will inherently be biased toward that demographic. This is something that you'll need to consider if you're basing your decisions on the data collected.

We hope that as the Javascript browser profiling API gains adoption, other browsers will implement it as well. If you find the browser profiling feature helpful and would like to see it gain further adoption, please consider supporting the spec at the official WICG repository.
65 changes: 3 additions & 62 deletions docs/platforms/javascript/common/profiling/index.mdx
Original file line number Diff line number Diff line change
@@ -1,72 +1,13 @@
---
title: Set Up Profiling
sidebar_order: 5000
supported:
- javascript
description: "Collect & view performance insights for JavaScript programs with Sentry's Profiling integrations. Get started with browser and Node.js profiling to understand your application's performance."
notSupported:
- javascript.bun
- javascript.cordova
- javascript.capacitor
- javascript.deno
- javascript.cloudflare
description: "Collect & view performance insights for JavaScript programs with Sentry’s JavaScript Profiling integration. Get started with browser profiling here."
---

<Note>

Browser Profiling is currently in beta. Beta features are still in progress and may have bugs. We recognize the irony.

</Note>

The browser profiling integration is built using [JS Self-Profiling API](https://wicg.github.io/js-self-profiling/) and will likely only move out of beta once the specification progresses and gains adoption. See platform [status](https://chromestatus.com/feature/5170190448852992).

Note that since the profiling API is currently only exposed in Chromium, profiles collected only include that demographic. This is obvious, but should not be forgotten when analyzing the data collected. We hope that as the API gains adoption, other browsers will implement it as well.

<PlatformContent includePath="profiling/index/why-profiling" />

## Prerequisites

To get started with JavaScript browser profiling, you'll need to:

- Install the <PlatformSdkPackageName fallback="@sentry/browser"/> SDK, minimum version 7.60.0
- Configure the document response header to include `Document-Policy: js-profiling`
- Configure the SDK to use the `BrowserProfilingIntegration` and set `profilesSampleRate`

## Step 1: Install the <PlatformOrGuideName/> SDK

<PlatformSection notSupported={["javascript.electron"]}>

Install our <PlatformOrGuideName/> SDK using either `yarn` or `npm`, the minimum version that supports profiling is **7.60.0**.

</PlatformSection>

<PlatformSection supported={["javascript.electron"]}>

Install our Electron SDK using either `yarn` or `npm`, the minimum version that supports profiling is **4.16.0**.

</PlatformSection>

<PlatformContent includePath="profiling/automatic-instrumentation-intro" />

## Step 2: Add Document-Policy: js-profiling header

For the JavaScript browser profiler to start, the document response header needs to include a `Document-Policy` header key with the `js-profiling` value.

<PlatformContent includePath="profiling/automatic-instrumentation-headers" />

## Step 3: Configure the JavaScript SDK

Configuration should happen as early as possible in your application's lifecycle. Once this is done, Sentry's JavaScript SDK will capture all unhandled exceptions and transactions.

<PlatformContent includePath="profiling/automatic-instrumentation-setup" />

## The Difference Between DevTools & Sentry's JavaScript Browser Profiler

What does Sentry's JavaScript browser profile offer that Chrome DevTools does not?

- Sentry JavaScript profiler runs in production and captures real user data, showing real-world performance. DevTools runs locally on your machine and only shows profiles of what's running on your machine.
- Sentry runs at a lower sampling rate of 100Hz with a 10ms sample period versus a sampling rate of 1000Hz and a 1ms sample period for DevTools.
- Sentry supports deobfuscation, making it so that all the function names in your code are correct. Typically, when you run JavaScript code, it's minified, meaning that all the function names are replaced with machine-generated abbreviations.

Please note, that since the browser profiling API is currently only implemented in Chromium-based browsers, the profiles collected with Sentry's JavaScript browser profiling will inherently be biased toward that demographic. This is something that you'll need to consider if you're basing your decisions on the data collected.

We hope that as the Javascript browser profiling API gains adoption, other browsers will implement it as well. If you find the browser profiling feature helpful and would like to see it gain further adoption, please consider supporting the spec at the official WICG repository.
<PageGrid />
Original file line number Diff line number Diff line change
@@ -1,7 +1,22 @@
---
title: Set Up Profiling
title: Node Profiling
sidebar_order: 5000
description: "Learn more about how to configure our Profiling integration and start profiling your code."
supported:
- javascript.nextjs
- javascript.sveltekit
- javascript.remix
- javascript.astro
- javascript.node
- javascript.aws-lambda
- javascript.azure-functions
- javascript.connect
- javascript.express
- javascript.fastify
- javascript.gcp-functions
- javascript.hapi
- javascript.koa
- javascript.nestjs
---

By default, Sentry error events will not get trace context unless you configure the scope with the transaction, as illustrated in the example below.
Expand All @@ -14,43 +29,25 @@ If you're adopting Profiling in a high-throughput environment, we recommend test

## Installation

<Note>

Node profiling is available starting in `@sentry/profiling-node` version `0.3.0`.
You have to have the `@sentry/nestjs` package installed.

</Note>

```bash {tabTitle:npm}
npm install @sentry/nestjs @sentry/profiling-node --save
```

```bash {tabTitle:yarn}
yarn add @sentry/nestjs @sentry/profiling-node
```

```bash {tabTitle:pnpm}
pnpm add @sentry/nestjs @sentry/profiling-node
```
You have to have the <PlatformSdkPackageName fallback="@sentry/node"/> (minimum version `7.44.1`) package installed.

## Enabling Profiling

To enable profiling, import `@sentry/profiling-node`, add `ProfilingIntegration` to your `integrations`, and set the `profilesSampleRate`.

To enable profiling, add `@sentry/profiling-node` to your imports and set up `nodeProfilingIntegration` in your Sentry config.

```javascript
const Sentry = require("@sentry/nestjs");
```javascript {diff}
const { nodeProfilingIntegration } = require("@sentry/profiling-node");

Sentry.init({
dsn: "___PUBLIC_DSN___",
integrations: [
// Add our Profiling integration
nodeProfilingIntegration(),
+ nodeProfilingIntegration(),
],
tracesSampleRate: 1.0,
// Set sampling rate for profiling - this is relative to tracesSampleRate
profilesSampleRate: 1.0,
+ // Set sampling rate for profiling - this is relative to tracesSampleRate
+ profilesSampleRate: 1.0,
});

// Profiling happens automatically after setting it up with `Sentry.init()`.
Expand Down
85 changes: 0 additions & 85 deletions docs/platforms/javascript/guides/aws-lambda/profiling/index.mdx

This file was deleted.

Loading
Loading