diff --git a/docs/concepts/key-terms/dsn-explainer.mdx b/docs/concepts/key-terms/dsn-explainer.mdx index e14ce0d6b20100..dcece8b5cbd955 100644 --- a/docs/concepts/key-terms/dsn-explainer.mdx +++ b/docs/concepts/key-terms/dsn-explainer.mdx @@ -68,4 +68,4 @@ For example, if you have a React frontend and an Express backend, whether they'r - Set up distributed tracing to follow requests across your frontend and backend - Assign responsibility to specific teams -To learn more about setting up multiple projects for distributed tracing, see [Create Frontend and Backend Sentry Projects](/product/sentry-basics/distributed-tracing/create-new-project/). For general guidance on how many projects to create, see [How Many Projects Should I Create?](/organization/getting-started/#how-many-projects-should-i-create) +To learn more about setting up multiple projects for distributed tracing, see [Create Frontend and Backend Sentry Projects](/product/sentry-basics/getting-started-tutorial/create-new-project/). For general guidance on how many projects to create, see [How Many Projects Should I Create?](/organization/getting-started/#how-many-projects-should-i-create) diff --git a/docs/concepts/key-terms/tracing/distributed-tracing.mdx b/docs/concepts/key-terms/tracing/distributed-tracing.mdx index 138a0c6a2a4564..64735cc558a5c8 100644 --- a/docs/concepts/key-terms/tracing/distributed-tracing.mdx +++ b/docs/concepts/key-terms/tracing/distributed-tracing.mdx @@ -74,7 +74,7 @@ Applications consist of interconnected components or services. For example, a mo Each component can be instrumented individually using a Sentry SDK to capture error data or crash reports, but this doesn't provide the full picture. Distributed tracing ties all the data together. -Distributed tracing allows you to follow a request from the [frontend](/product/sentry-basics/integrate-frontend/) to the [backend](/product/sentry-basics/integrate-backend/) and back, pulling in data from any background tasks or notification jobs that request creates. This helps correlate Sentry error reports and gain insights into which services may negatively impact your application's performance. +Distributed tracing allows you to follow a request from the [frontend](/product/sentry-basics/getting-started-tutorial/initialize-sentry-sdk-frontend/) to the [backend](/product/sentry-basics/getting-started-tutorial/initialize-sentry-sdk-backend/) and back, pulling in data from any background tasks or notification jobs that request creates. This helps correlate Sentry error reports and gain insights into which services may negatively impact your application's performance. ## Traces, Transactions, and Spans diff --git a/docs/product/dashboards/sentry-dashboards/backend/queries.mdx b/docs/product/dashboards/sentry-dashboards/backend/queries.mdx index 4872f0f7459925..1056239ef9aef6 100644 --- a/docs/product/dashboards/sentry-dashboards/backend/queries.mdx +++ b/docs/product/dashboards/sentry-dashboards/backend/queries.mdx @@ -95,7 +95,7 @@ Query Sources are currently supported in Sentry's [Laravel](/platforms/php/guide -A query's source is the location in your application's code that triggered the query. Sentry automatically determines the query source by examining the [stack trace](/product/sentry-basics/integrate-frontend/upload-source-maps/) and attaches the source to the query data. +A query's source is the location in your application's code that triggered the query. Sentry automatically determines the query source by examining the [stack trace](/product/sentry-basics/getting-started-tutorial/enable-readable-stack-traces/) and attaches the source to the query data. You can see the query's source underneath the query description on the **Query Details** dashboard, as shown in the image below. If you have a [source code management integration](/integrations/source-code-mgmt/) enabled, Sentry will also show a link to open the query's source in the relevant repository. diff --git a/docs/product/explore/session-replay/mobile/index.mdx b/docs/product/explore/session-replay/mobile/index.mdx index b2ce6a1917e754..26a3ca85806a13 100644 --- a/docs/product/explore/session-replay/mobile/index.mdx +++ b/docs/product/explore/session-replay/mobile/index.mdx @@ -29,7 +29,7 @@ Every replay has a detailed view that contains the embedded video player and ric The below list shows the breakdown of each component and why it’s valuable: -- **Activity:** The **Activity** tab shows when key user interactions took place, specifically: user taps with the relevant component, navigations, when the user put the app in background or foreground, and [custom breadcrumbs](/product/sentry-basics/integrate-backend/configuration-options/#breadcrumbs) set by your organization. It also provides insight into the device of a given user session at particular timestamps: +- **Activity:** The **Activity** tab shows when key user interactions took place, specifically: user taps with the relevant component, navigations, when the user put the app in background or foreground, and [custom breadcrumbs](/platforms/javascript/enriching-events/breadcrumbs/) set by your organization. It also provides insight into the device of a given user session at particular timestamps: - `device battery` (when battery level or charging status changes) - `orientation` (when the user rotates the device) - `connectivity` (when this status changes between wifi, cellular, and offline). diff --git a/docs/product/explore/session-replay/replay-details.mdx b/docs/product/explore/session-replay/replay-details.mdx index ef762354b066a1..1f6e78765bcad6 100644 --- a/docs/product/explore/session-replay/replay-details.mdx +++ b/docs/product/explore/session-replay/replay-details.mdx @@ -37,11 +37,11 @@ Sentry now provides **AI-powered replay summaries** that automatically analyze w The **Activity** tab shows when key user interactions took place during the replay. Entries are synced with the replay player and will auto-scroll as the video plays. **Both web and mobile replays include:** -- **Custom Breadcrumbs:** Learn more about configuring [custom breadcrumbs](/product/sentry-basics/integrate-backend/configuration-options/#breadcrumbs) +- **Custom Breadcrumbs:** Learn more about configuring [custom breadcrumbs](/platforms/javascript/enriching-events/breadcrumbs/) **Web-specific activity includes:** - **User Clicks:** including [rage clicks](/product/issues/issue-details/replay-issues/rage-clicks/) and [dead clicks](/product/issues/issue-details/replay-issues/rage-clicks/#detection-criteria) -- **Navigations and Page Loads:** [Learn more about spans](/product/sentry-basics/distributed-tracing/) +- **Navigations and Page Loads:** [Learn more about spans](/product/sentry-basics/getting-started-tutorial/) - **Web Vitals:** and an overall performance score [Learn more](/product/dashboards/sentry-dashboards/frontend/web-vitals/) **Mobile-specific activity includes:** diff --git a/docs/product/index.mdx b/docs/product/index.mdx index 31b8c796aea049..a02190550b129c 100644 --- a/docs/product/index.mdx +++ b/docs/product/index.mdx @@ -18,7 +18,7 @@ Sentry's error monitoring capabilities make it possible to quickly get to the ro Sentry automatically captures unhandled exceptions (errors). It then groups similar errors into [issues](/product/issues/), making it possible to triage and manage them more efficiently. -- If you're monitoring a web project, you can [**replay**](/product/explore/session-replay/) what the user experienced on your app and connect that error to the problematic line of code with [**source maps**](/product/sentry-basics/integrate-frontend/upload-source-maps/). +- If you're monitoring a web project, you can [**replay**](/product/explore/session-replay/) what the user experienced on your app and connect that error to the problematic line of code with [**source maps**](/product/sentry-basics/getting-started-tutorial/enable-readable-stack-traces/). - If you set up Sentry for both your frontend and backend, you'll be able to use [**distributed tracing**](/product/sentry-basics/concepts/tracing/distributed-tracing/) to see the sequence of events (both frontend and backend) that led up to the event of interest. - Additionally, you can set up [**integrations**](/integrations/source-code-mgmt/) to link your source code so that Sentry can surface [**suspect commits**](/product/issues/suspect-commits/) and [**stack traces**](/integrations/source-code-mgmt/github/#stack-trace-linking) to show the problematic line of code, as well as [**suggest assignees**](/integrations/source-code-mgmt/github/#suspect-commits-and-suggested-assignees) for issues based on commit authors. diff --git a/docs/product/projects/index.mdx b/docs/product/projects/index.mdx index 79f7288de21941..912e279fae4367 100644 --- a/docs/product/projects/index.mdx +++ b/docs/product/projects/index.mdx @@ -6,7 +6,7 @@ description: "View all the projects associated with teams that you're a member o A _Project_ represents your service or application in Sentry. For example, you might have separate projects for your API server and frontend client. -When you first [create a project](/product/sentry-basics/integrate-frontend/create-new-project/), you also assign a team to it. All members of the assigned team have access to the project. Additional teams can be added in your project's [Project Teams](https://sentry.io/orgredirect/organizations/:orgslug/settings/projects/:projectId/teams/) settings. +When you first [create a project](/product/sentry-basics/getting-started-tutorial/create-new-project/), you also assign a team to it. All members of the assigned team have access to the project. Additional teams can be added in your project's [Project Teams](https://sentry.io/orgredirect/organizations/:orgslug/settings/projects/:projectId/teams/) settings. You can create more projects to reflect your application landscape with finer granularity (for example, a separate project for each repo, mapping components and micro-services to the teams that own them). For most pages in Sentry, including **Issues** and **Discover**, the top-level filter bar defaults to showing information for your projects, so that you only see what's relevant to you and your team(s). How you set up your projects can go a long way in reducing noise and improving productivity. Learn more about best practices for setting up projects in our [account setup documentation](/organization/getting-started/#4-create-projects). diff --git a/docs/product/sentry-basics/distributed-tracing/img/frontend-screenshot.png b/docs/product/sentry-basics/distributed-tracing/img/frontend-screenshot.png deleted file mode 100644 index 1b5de1303d79e6..00000000000000 Binary files a/docs/product/sentry-basics/distributed-tracing/img/frontend-screenshot.png and /dev/null differ diff --git a/docs/product/sentry-basics/distributed-tracing/index.mdx b/docs/product/sentry-basics/distributed-tracing/index.mdx deleted file mode 100644 index 3951607b22f4ac..00000000000000 --- a/docs/product/sentry-basics/distributed-tracing/index.mdx +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Distributed Tracing Tutorial -sidebar_order: 1 -description: "Follow this tutorial to set up Sentry error monitoring and distributed tracing for a sample fullstack JavaScript application. By the end, you'll be able to trigger an error and a trace and see it in Sentry.io." ---- - -This step-by-step tutorial walks you through setting up Sentry in both a frontend (React) and backend (Express) sample application. After completing this tutorial you'll be able to trace the source and impact of your issues across projects and platforms. As part of this tutorial, you will: - -- Configure the Sentry SDK on a sample React and Node/Express app. -- Trigger a sample front-end error that in turn triggers a sample back-end error. -- Go to the [Traces](https://sentry.io/orgredirect/organizations/:orgslug/traces/) page in Sentry and see a detailed view of your entire trace. - -This tutorial uses a [sample React application](https://github.com/getsentry/tracing-tutorial-frontend) on the frontend as well as a sample [Express API](https://github.com/getsentry/tracing-tutorial-backend) on the backend. Some familiarity with JavaScript will help you follow along. If you'd prefer, you can also apply the same steps to your own project, assuming you're running React on the frontend and Express on the backend. - -## Prerequisites - -- A [Sentry](https://sentry.io) account, or [sign up](https://sentry.io/signup/) for one -- A [GitHub](https://github.com/) account, or [sign up](https://github.com/join) for one -- [Node 18+](https://nodejs.org/en/download/) - -## Next - -[Create your Sentry Projects](/product/sentry-basics/distributed-tracing/create-new-project/) diff --git a/docs/product/sentry-basics/distributed-tracing/initialize-sentry-sdk-backend.mdx b/docs/product/sentry-basics/distributed-tracing/initialize-sentry-sdk-backend.mdx deleted file mode 100644 index 25b2a41d8438b0..00000000000000 --- a/docs/product/sentry-basics/distributed-tracing/initialize-sentry-sdk-backend.mdx +++ /dev/null @@ -1,164 +0,0 @@ ---- -title: Add the Sentry SDK to Your Backend Project -sidebar_order: 4 -description: "Learn how to add the Sentry SDK to your backend codebase." ---- - -This section walks you through how to import the sample application into your local development environment, add the Sentry SDK, and initialize it. - -If you're using your own source code, you can skip this section. Instead: - -- Select your [platform](/platforms/) and follow its **Getting Started** guide to add the Sentry SDK to your code. -- Then, skip to the [next step](/product/sentry-basics/distributed-tracing/generate-first-error/). - -## 1. Clone the Sample Application - -The sample application is a basic backend application using Express and Node. - -1. Fork the [sample application's repository](https://github.com/getsentry/tracing-tutorial-backend) on GitHub. - -1. Clone the forked repository to your local environment: - - ```bash - git clone git@github.com:/tracing-tutorial-backend.git - ``` - -1. Open the `tracing-tutorial-backend` project in your preferred code editor. - -## 2. Add the Sentry Node SDK - -Sentry captures data by using a platform-specific SDK that you add to your application's runtime. To use the SDK, import and configure it in your source code. This demo project uses [Sentry's Node SDK](https://github.com/getsentry/sentry-javascript/tree/master/packages/node). - -1. Navigate to the `tracing-tutorial-backend` project folder and install the Sentry Express SDK using NPM. - - ```bash {tabTitle:npm} - npm install --save @sentry/node @sentry/profiling-node - ``` - - ```bash {tabTitle:yarn} - yarn add @sentry/node @sentry/profiling-node - ``` - - ```bash {tabTitle:pnpm} - pnpm add @sentry/node @sentry/profiling-node - ``` - -1. Create a file at the root level of your project and call it `instrument.js`. Import and initialize the SDK using the following code: - - ```javascript {filename:instrument.js} - const Sentry = require("@sentry/node"); - const { nodeProfilingIntegration } = require("@sentry/profiling-node"); - - Sentry.init({ - dsn: "sample_DSN_key", - integrations: [nodeProfilingIntegration()], - // Tracing - // Capture 100% of the transactions - tracesSampleRate: 1.0, - - // Set sampling rate for profiling - this is relative to tracesSampleRate - profilesSampleRate: 1.0, - }); - ``` - - It's important to import and initialize the SDK as early as possible in your application's lifecycle so Sentry can capture errors throughout the lifecycle. - -1. Add your DSN key to the Sentry SDK configuration. - - Paste in the DSN key value you copied from the project created in the [previous section](/product/sentry-basics/distributed-tracing/create-new-project/). NOTE: This DSN key should be **different** from the one you used to configure Sentry on your frontend project. Your frontend and backend projects should each have a unique DSN. - - ```javascript {filename:instrument.js} - Sentry.init({ - dsn: "", - // ... - }); - ``` - -1. Save the file. - - The options set in `Sentry.init()` are called the SDK's configuration. The only required configuration option is the DSN. However, the SDK supports many other configuration options. Learn more in our [Configuration](/platforms/javascript/guides/react/configuration/) docs. - - The configuration above enables Sentry's error monitoring feature, as well as its [**Tracing**](/product/tracing/) and [**Session Replay**](/platforms/javascript/guides/react/session-replay) features. - - -1. Import `instrument.js` at the top of your `server.js` file. Then import `Sentry` and set up the error handler after all controllers and before any other middleware: - -```javascript diff {filename:server.js} -+ // IMPORTANT: Make sure to import `instrument.js` at the top of your file. -+ // If you're using ECMAScript Modules (ESM) syntax, use `import "./instrument.js";` -+ require("./instrument.js"); - -+ // All other imports below -+ // Import with `import * as Sentry from "@sentry/node"` if you are using ESM - const Sentry = require("@sentry/node"); - const express = require("express"); - const productsRoute = require('./routes/products'); - const cors = require('cors') - - const app = express(); - - app.use(express.static('public')); - app.use(cors()); - - app.get('/', (req, res) => { - res.send('

Hello, Express.js Server here!

'); - }); - - app.get("/products/debug-sentry", (req, res) => { - console.log("Sentry Error thrown!"); - throw new Error("My first Sentry error!"); - }); - -+ // The error handler must be registered before any other error middleware and after all controllers -+ Sentry.setupExpressErrorHandler(app); - -+ // Optional fallthrough error handler -+ app.use(function onError(err, req, res, next) { -+ // The error id is attached to `res.sentry` to be returned -+ // and optionally displayed to the user for support. -+ console.log('500 error thrown!'); -+ res.statusCode = 500; -+ res.end(res.sentry + "\n"); -+ }); - - app.use('/products', productsRoute); - - const port = 3001; - - app.listen(port, () => { - console.log(`Server is running on port 3001`); - }); - -``` - -## 3. Build and Run the Sample Application - -In the `tracing-tutorial-backend` project folder: - -1. Install project dependencies. - - ```bash - npm install - ``` - -1. Start the application in develop mode: - - ```bash - node server.js - ``` - - Once the application starts, you'll see a confirmation message similar to this one in your terminal: - - ```bash - Server is running on port 3001 - ``` - -> **Troubleshooting tip**: If the application fails to start due to syntax errors or errors for missing dependencies/modules, make sure you're using Node 18+ and install dependencies again. If you're using [nvm](https://github.com/nvm-sh/nvm), ensure you are on the right node version with `nvm use 18` and then `npm install`. - -1. Open the sample application in your browser. - - The sample app should be running at [http://localhost:3001/](http://localhost:3001/) or the URL output in your terminal in the last step. - -## Next - -Well done! You now have a sample Express backend app running with the Sentry SDK initialized. Next, [Generate your first cross-project error](/product/sentry-basics/distributed-tracing/generate-first-error/) to start using Sentry's Distributed Tracing feature. diff --git a/docs/product/sentry-basics/distributed-tracing/initialize-sentry-sdk-frontend.mdx b/docs/product/sentry-basics/distributed-tracing/initialize-sentry-sdk-frontend.mdx deleted file mode 100644 index 0a8cd85c66df9c..00000000000000 --- a/docs/product/sentry-basics/distributed-tracing/initialize-sentry-sdk-frontend.mdx +++ /dev/null @@ -1,130 +0,0 @@ ---- -title: Add the Sentry SDK to Your Frontend Project -sidebar_order: 3 -description: Learn how to add the Sentry SDK to your frontend codebase. -og_image: >- - /og-images/product-sentry-basics-distributed-tracing-initialize-sentry-sdk-frontend.png ---- - -This section walks you through how to import the sample application into your local development environment, add the Sentry SDK, and initialize it. - -If you're using your own source code, you can skip this section. Instead: - -- Select your [platform](/platforms/) and follow its **Getting Started** guide to add the Sentry SDK to your code. -- Then, skip to the [next step](/product/sentry-basics/distributed-tracing/initialize-sentry-sdk-backend/). - -## 1. Clone the Sample Application - -The sample application is a basic frontend-only application using React and webpack. - -1. Fork the [sample application's repository](https://github.com/getsentry/tracing-tutorial-frontend) on GitHub. - -1. Clone the forked repository to your local environment: - - ```bash - git clone git@github.com:/tracing-tutorial-frontend.git - ``` - -1. Open the `tracing-tutorial-frontend` project in your preferred code editor. - -## 2. Add the Sentry React SDK - -Sentry captures data by using a platform-specific SDK that you add to your application's runtime. To use the SDK, import and configure it in your source code. This demo project uses [Sentry's React SDK](https://github.com/getsentry/sentry-javascript/tree/develop/packages/react). - -1. Install the Sentry React SDK using NPM. - - Make sure you're in the `tracing-tutorial-frontend` project folder. - - ```bash {tabTitle:npm} - npm install @sentry/react --save - ``` - - ```bash {tabTitle:yarn} - yarn add @sentry/react - ``` - - ```bash {tabTitle:pnpm} - pnpm add @sentry/react - ``` - -1. Import and initialize the SDK. - - Open `src/index.js` and add the following lines of code below the last import statement: - - ```javascript {filename:src/index.js} {12} - import * as Sentry from "@sentry/react"; - - Sentry.init({ - dsn: "your_DSN_key", - integrations: [ - Sentry.browserTracingIntegration(), - Sentry.replayIntegration(), - ], - // Tracing - tracesSampleRate: 1.0, // Capture 100% of the transactions - // Set 'tracePropagationTargets' to control for which URLs distributed tracing should be enabled - tracePropagationTargets: ["localhost", /^https:\/\/yourserver\.io\/api/], - // Session Replay - replaysSessionSampleRate: 0.1, // This sets the sample rate at 10%. You may want to change it to 100% while in development and then sample at a lower rate in production. - replaysOnErrorSampleRate: 1.0, // If you're not already sampling the entire session, change the sample rate to 100% when sampling sessions where errors occur. - }); - ``` - - It's important to import and initialize the SDK as early as possible in your application's lifecycle so Sentry can capture errors throughout the lifecycle. - -1. Add your DSN key to the Sentry SDK configuration. - - Paste in the DSN key value you copied from the project created in the [previous section](/product/sentry-basics/distributed-tracing/create-new-project/). - - ```javascript {filename:src/index.js} - Sentry.init({ - dsn: "", - // ... - }); - ``` - -1. Save the file. - -The options set in `Sentry.init()` are called the SDK's configuration. The only required configuration option is the DSN. However, the SDK supports many other configuration options. Learn more in our [Configuration](/platforms/javascript/guides/react/configuration/) docs. - -The configuration above enables Sentry's error monitoring feature, as well as [**Tracing**](/product/tracing/) and [**Session Replay**](/platforms/javascript/guides/react/session-replay) features. Take note of the `tracePropagationTargets` option, this is required to enable tracing on any urls your projects are running on. Since both of this tutorial's projects are running on `localhost`, we are all set. - - -## 3. Build and Run the Sample Application - -In the `tracing-tutorial-frontend` project folder: - -1. Install project dependencies. - - ```bash - npm install - ``` - -1. Start the application in develop mode. - - ```bash - npm start - ``` - - Once the application starts, you'll see a confirmation message similar to this one in your terminal: - - ```bash - Compiled successfully! - - You can now view tracing-demo in the browser. - - Local: http://localhost:3000 - On Your Network: http://10.0.0.39:3000 - ``` - - > **Troubleshooting tip**: If the application fails to start due to syntax errors or errors for missing dependencies/modules, make sure you're using Node 18+ and install dependencies again. If you're using [nvm](https://github.com/nvm-sh/nvm), ensure you are on the right node version with `nvm use 18` and then `npm install`. - -1. Open the sample application in your browser. - - The sample app should be running at [http://localhost:3000/](http://localhost:3000/) or the URL output in your terminal in the last step. You should see a sample e-commerce page; the buttons on this page won't work correctly and will trigger an uncaught runtime error until you get your backend up and running. - - ![img/frontend-screenshot.png](img/frontend-screenshot.png) - -## Next - -Nicely done! You now have a sample React app running with the Sentry SDK initialized. Next, [Add the Sentry SDK to Your Backend Project](/product/sentry-basics/distributed-tracing/initialize-sentry-sdk-backend/) to get Sentry running across the entire stack of your platform. diff --git a/docs/product/sentry-basics/distributed-tracing/create-new-project.mdx b/docs/product/sentry-basics/getting-started-tutorial/create-new-project.mdx similarity index 68% rename from docs/product/sentry-basics/distributed-tracing/create-new-project.mdx rename to docs/product/sentry-basics/getting-started-tutorial/create-new-project.mdx index 1410f8d07030ea..29587a308662c4 100644 --- a/docs/product/sentry-basics/distributed-tracing/create-new-project.mdx +++ b/docs/product/sentry-basics/getting-started-tutorial/create-new-project.mdx @@ -4,6 +4,10 @@ sidebar_order: 2 description: "Learn how to create your Sentry projects, which will scope events to distinct pieces of your application landscape." --- +**Step 1 of 5** + + + In order to capture errors and other events, you need to have a project set up in Sentry. In this walkthrough we'll be creating a frontend project in React and a separate backend project in Express. Because you can create a Sentry Project for _each_ language or framework used in your application (for example, you might have separate projects for your API server and frontend client), a single application might have multiple projects associated with it. Once you've set up all the projects that correspond to different parts of your application in Sentry, you'll be able to scope events to a distinct application in your organization and assign responsibility to specific users and teams. For more information, see [best practices for creating projects](/organization/getting-started/#4-create-projects). @@ -14,21 +18,21 @@ Follow the steps below to create a new Sentry project for a sample React applica 1. Log in to your [Sentry organization](https://sentry.io). -1. Select **Projects** from the left side navigation menu. +1. Click on your organization's icon in the top left navigation, and select **Projects** from the menu. 1. Click "Create Project" and configure it as appropriate for your application: - - **Choose your platform**: Select the language or framework for your project based on the code you wish to monitor. In this case, choose **React**. + - **Choose your platform**: Select the language or framework for your project, in this case, choose **React**. - - **Set your alert frequency**: For the purpose of this tutorial, select **Alert me on high priority issues**. + - **Set your alert frequency**: For this tutorial, select **Alert me on high priority issues**. > If you're wary of alert fatigue, learn more about how to set up your alerts in [Alerts Best Practices](/product/monitors-and-alerts/alerts/#alerts-best-practices). - **Name your project and assign it a team**: Name your project in the **Project name** field and assign a team by selecting one in the **Team** dropdown (or click **+** to create a new team). - - Click **Create Project**. This takes you to the quick Configure React SDK guide, which provides an overview of how to configure the SDK. This tutorial covers the SDK setup in more detail. + - Click **Create Project**. This takes you to the quick Configure React SDK guide, which provides an overview of how to configure the SDK. - - You'll notice that the Sentry React SDK setup code has come pre-populated with the project's unique DSN (Data Source Name). The DSN tells the SDK where to send events, so events are associated with the right project. You'll need to paste the DSN key into the SDK configuration code later in the tutorial. You can make a note of it now, or you can also find a project's DSN anytime in **[Project] > Settings > SDK Setup > Client Keys (DSN)** + - You'll notice that the Sentry React SDK setup code comes pre-populated with the project's unique DSN (Data Source Name). The DSN tells the SDK where to send events, so events are associated with the right project. You'll need to paste the DSN key into the SDK configuration code later in the tutorial. You can make a note of it now, or you can also find a project's DSN anytime in **[Project] > Settings > SDK Setup > Client Keys (DSN)** 1. Click **Take me to Issues** to go to your new project's **Issues** page. @@ -36,19 +40,16 @@ Follow the steps below to create a new Sentry project for a sample React applica The interactive demo below walks through how to create a new project in the UI. - + ## Create a Backend Project -Next, follow the steps below to create a new Sentry project for a sample Backend application: - -1. Log in to your [Sentry organization](https://sentry.io). - -1. Select **Projects** from the left side navigation menu to display the list of all your projects. +Next, follow these steps for the sample Backend app: +1. Head back to the [Projects page](https://sentry.io/orgredirect/organizations/:orgslug/projects/) 1. Click "Create Project" and configure it as appropriate for your application: - - **Choose your platform**: In this case, choose **Express**. + - **Choose your platform**: In this case,**Express**. - **Set your alert frequency**: Once again, select **Alert me on high priority issues**. @@ -62,10 +63,12 @@ Next, follow the steps below to create a new Sentry project for a sample Backend 1. Click **Take me to Issues** to go to your new project's **Issues** page. +{/* TODO: Screenshot of the Projects list showing both the frontend and backend projects. */} + ### UI Walkthrough - + ## Next -Now that you have your Sentry projects set up, you can [Add the Sentry SDK to Your Frontend Project](/product/sentry-basics/distributed-tracing/initialize-sentry-sdk-frontend/). +Now that you have your Sentry projects set up, you can [Add the Sentry SDK to Your Frontend Project](/product/sentry-basics/getting-started-tutorial/initialize-sentry-sdk-frontend/). diff --git a/docs/product/sentry-basics/getting-started-tutorial/enable-readable-stack-traces.mdx b/docs/product/sentry-basics/getting-started-tutorial/enable-readable-stack-traces.mdx new file mode 100644 index 00000000000000..30ccbe2926ed74 --- /dev/null +++ b/docs/product/sentry-basics/getting-started-tutorial/enable-readable-stack-traces.mdx @@ -0,0 +1,168 @@ +--- +title: Enable Readable Stack Traces +sidebar_order: 6 +description: "Learn how to upload source maps to Sentry so your stack traces show real source code instead of minified output." +--- + +**Step 5 of 5** (optional) + + + + + +You've already set up distributed tracing across your stack in the previous steps. This step is an optional enhancement — worth doing, but not required. + + + +When you ship JavaScript to production, your code is transformed — bundled, minified, and sometimes transpiled — to make it smaller and faster in the browser. That transformation makes stack traces unreadable: instead of the line of code that failed, you see something like `a.b.c at index-J_blQJy.js:1:21834`. + +Source maps are the bridge back. They tell Sentry how to map the minified output to your original source. In this step, you'll generate source maps for the frontend app, upload them to Sentry, and trigger another error to see the difference. + +{/* TODO: Screenshot showing a minified "before" stack trace next to a readable "after" stack trace. */} + +The sample frontend app uses [Vite](https://vite.dev/) as its build tool, and the [Sentry Vite plugin](/platforms/javascript/guides/react/sourcemaps/uploading/vite/) both generates source maps and uploads them as part of your production build. + +> Using a different bundler? Use the [Sentry Wizard](/platforms/javascript/sourcemaps/#uploading-source-maps) to configure source maps for webpack, Rollup, esbuild, Next.js, and others, then skip to step 3. + +## 1. Install the Sentry Vite Plugin + +In the `tracing-tutorial-frontend` project folder, install the plugin as a dev dependency: + +```bash {tabTitle:npm} +npm install @sentry/vite-plugin --save-dev +``` + +```bash {tabTitle:yarn} +yarn add @sentry/vite-plugin --dev +``` + +```bash {tabTitle:pnpm} +pnpm add @sentry/vite-plugin --save-dev +``` + +## 2. Add an Auth Token + +To upload source maps, the plugin needs an _auth token_ — a secret key that tells Sentry the upload is coming from you. You'll keep this token in a separate file instead of writing it directly into your code, so it stays private. + + + +The Sentry Vite plugin automatically reads your token from a file named exactly `.env.sentry-build-plugin`. Create that file now: + +1. In the **root** of the `tracing-tutorial-frontend` folder (the same folder that contains `package.json`), create a new file named exactly `.env.sentry-build-plugin` — including the leading dot. + +1. Add your auth token to the file, replacing `___ORG_AUTH_TOKEN___` with the token you generated above: + + ```bash {filename:.env.sentry-build-plugin} + SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___ + ``` + +1. Save the file. The sample project's `.gitignore` already lists `.env.sentry-build-plugin`, so your token won't be committed to git — keep it that way. Auth tokens should never be shared or pushed to a repository. + +## 3. Configure the Plugin + +Next, tell the plugin which Sentry **organization** and **project** to upload your source maps to. You'll need two values, both of which are _slugs_ — the short, lowercase names Sentry uses in URLs. + +Here's how to find each one in Sentry: + +- **Organization slug**: look at your Sentry URL — it's the part right before `.sentry.io`. For example, in `https://acme-inc.sentry.io/`, the organization slug is `acme-inc`. You can also find it under **Settings > General Settings**. +- **Project slug**: in the left sidebar, go to **Settings > Projects**, then click the **frontend** project you created earlier (not the backend one). The project slug is shown at the top of that project's settings page and in the page's URL. + +Now open `vite.config.js` and add `sentryVitePlugin` as shown below, replacing `___ORG_SLUG___` and `___PROJECT_SLUG___` with the two values you just found: + +```javascript {filename:vite.config.js} +import { defineConfig } from "vite"; +import react from "@vitejs/plugin-react"; +import { sentryVitePlugin } from "@sentry/vite-plugin"; + +export default defineConfig({ + build: { + sourcemap: true, + }, + plugins: [ + react(), + sentryVitePlugin({ + org: "___ORG_SLUG___", + project: "___PROJECT_SLUG___", + }), + ], + server: { + port: 3000, + }, +}); +``` + + + +Your `org` and `project` here must point to the **same frontend project** as the DSN in `src/main.jsx`. Source maps are matched within a project — if your maps upload to one project but your errors report to another, Sentry won't be able to un-minify them. + + + +By default, the plugin deletes the source map files from your build output after uploading them, so they're not served to your users in production. + +## 4. Trigger the Error Again + +1. Stop your dev server with `Ctrl + C` and create a production build: + + ```bash {tabTitle:npm} + npm run build + ``` + + ```bash {tabTitle:yarn} + yarn build + ``` + + ```bash {tabTitle:pnpm} + pnpm build + ``` + + Look for the `Source Map Upload Report` in the output — it confirms the maps reached Sentry and lists each file by debug ID: + + ```bash + > Analyzing 2 sources + > Adding source map references + > Bundling files for upload + > Uploaded files to Sentry + > Successfully uploaded source maps to Sentry + ``` + +2. Serve the production build: + + ```bash {tabTitle:npm} + npm run preview + ``` + + ```bash {tabTitle:yarn} + yarn preview + ``` + + ```bash {tabTitle:pnpm} + pnpm preview + ``` + +3. Open the app (make sure the backend is still running on `http://localhost:3001`), open your browser's dev console, and right-click the reload button, then select 'Empty Cache and Hard Reload' so the new build is served. Then trigger the cross-project error again by clicking the **Nonfat Water** button. + +4. Go to the **Issues** page in Sentry and open the new issue. + +{/* TODO: Arcade walking through the rebuilt error and the un-minified stack trace. */} + +The stack trace should now include file names, function names, line numbers, and the surrounding source code — the actual code that failed, instead of minified output. + +![A readable stack trace in Sentry showing the exact file, line number, and source code that threw the error.](img/readable-stack-trace.png) + +## What's Next + +Congrats — you've built a fully instrumented fullstack app with Sentry. You now have: + +- Cross-project distributed tracing from your frontend to your backend +- Readable stack traces with source code context + +To go deeper, explore: + +- [Suspect commits & stack trace linking](/product/issues/suspect-commits/) — connect the [GitHub integration](/integrations/source-code-mgmt/github/) so Sentry can point to the commit that likely caused an error and link each stack frame straight to your source on GitHub. +- [Seer](/product/ai-in-sentry/seer/) — Sentry's AI debugging agent. Connect your GitHub or GitLab repo and Seer can analyze issues, find the root cause, and even open a pull request with a fix. (Seer is a paid add-on; see [Seer pricing](/pricing/#seer-pricing).) +- [Session Replay](/product/explore/session-replay/) — see a video-like reproduction of what the user did before the error +- [Alerts](/product/monitors-and-alerts/alerts/) — get notified in Slack or Discord about the issues you care about +- [Dashboards](/product/dashboards/sentry-dashboards/) — track error and performance trends across your services +- [Releases](/product/releases/) — monitor release health over time + +To set up Sentry on a project that isn't the sample app, head to the [Platforms](/platforms/) page and pick your stack. diff --git a/docs/product/sentry-basics/distributed-tracing/generate-first-error.mdx b/docs/product/sentry-basics/getting-started-tutorial/generate-first-error.mdx similarity index 58% rename from docs/product/sentry-basics/distributed-tracing/generate-first-error.mdx rename to docs/product/sentry-basics/getting-started-tutorial/generate-first-error.mdx index 4bfcef6c4e559f..15f4a52ba76ba7 100644 --- a/docs/product/sentry-basics/distributed-tracing/generate-first-error.mdx +++ b/docs/product/sentry-basics/getting-started-tutorial/generate-first-error.mdx @@ -4,9 +4,13 @@ sidebar_order: 5 description: "Learn how to capture your first error and view it in Sentry." --- +**Step 4 of 5** + + + Now that the sample apps are up and running on your local environment and integrated with the Sentry SDKs, you're ready to generate the first error. Please ensure you have BOTH apps running (on http://localhost:3000 and http://localhost:3001). -You should see the 'One-Stop Shop' site running on http://localhost:3000. Clicking on any of the product buttons will trigger a call to the backend for product info. As long as your Express server is running, you should see titles, images, and descriptions for each product. +You should see the 'One-Stop Shop' site running on http://localhost:3000. Clicking **View details** on any product card triggers a call to the backend for that product's info. As long as your Express server is running, you should see a title, image, and description for each product. ## 1. Trigger an Error @@ -14,20 +18,24 @@ To start using Sentry's error monitoring feature, you need some errors first. Le If you're using your own source code, skip this step. Instead, select your [platform](/platforms/) and follow its **Verify** step inside the **Getting Started** guide to introduce an error. -1. In the `tracing-tutorial-frontend` repo, open `src/App.js` and update the `onClick` handler by replacing the string passed to the `getProduct()` function from `nonfat-water` to `debug-sentry`. - -```jsx diff {filename:App.js} -
- -
-
+1. In the `tracing-tutorial-frontend` repo, open `src/App.jsx` and find the **Nonfat Water** product card. Update its `onClick` handler by replacing the string passed to the `getProduct()` function from `nonfat-water` to `debug-sentry`. + +```jsx diff {filename:src/App.jsx} +
+
🤡
+

Clown Shoes

+ +
+
+
💧
+

Nonfat Water

- -
+ View details + + ``` There's a middleware function handling the `/products/debug-sentry` route in the `server.js` file of the `tracing-tutorial-backend` repo that throws a sample error: @@ -41,7 +49,7 @@ app.get("/products/debug-sentry", (req, res) => { 1. Save the file. -1. Go back to the browser window and try clicking on the **Nonfat Water** button again, you will no longer see the expected product information. Instead, you'll see a `500 error` message displayed. +1. Go back to the browser window and click the **View details** button on the **Nonfat Water** card again. You'll no longer see the expected product information — instead the request fails with a `500` error. 1. Open the terminal window that's running the `tracing-tutorial-backend` server. Here, you'll see a log letting you know that an error has occurred: @@ -65,8 +73,12 @@ Now that you've triggered an error, let's see what it looks like in Sentry. The interactive demo below walks through how to view a distributed trace in Sentry. - + ## Next -Congrats, you're done! You've verified that Sentry is providing distributed tracing across your projects. You can now dig in to issues to find the original source of the issue that's causing a problem so you can diagnose and fix it in less time. +Congrats — you've set up Sentry with distributed tracing across your frontend and backend. That's the core of this tutorial. + +There's one optional step that makes your setup even more powerful: + +- [Enable Readable Stack Traces](/product/sentry-basics/getting-started-tutorial/enable-readable-stack-traces/) — the frontend error's stack trace is currently _minified_ and barely readable. Upload source maps so Sentry shows you exactly which line in which file caused the error. diff --git a/docs/product/sentry-basics/getting-started-tutorial/img/frontend-screenshot.png b/docs/product/sentry-basics/getting-started-tutorial/img/frontend-screenshot.png new file mode 100644 index 00000000000000..cc7542207903ce Binary files /dev/null and b/docs/product/sentry-basics/getting-started-tutorial/img/frontend-screenshot.png differ diff --git a/docs/product/sentry-basics/getting-started-tutorial/img/readable-stack-trace.png b/docs/product/sentry-basics/getting-started-tutorial/img/readable-stack-trace.png new file mode 100644 index 00000000000000..cdb2223545b02e Binary files /dev/null and b/docs/product/sentry-basics/getting-started-tutorial/img/readable-stack-trace.png differ diff --git a/docs/product/sentry-basics/getting-started-tutorial/index.mdx b/docs/product/sentry-basics/getting-started-tutorial/index.mdx new file mode 100644 index 00000000000000..598ecdf002b145 --- /dev/null +++ b/docs/product/sentry-basics/getting-started-tutorial/index.mdx @@ -0,0 +1,43 @@ +--- +title: Getting Started Tutorial +sidebar_order: 1 +description: "Follow this step-by-step tutorial to set up Sentry error monitoring and distributed tracing for a sample fullstack JavaScript app. You'll learn how to trace errors from your frontend through to your backend, see readable stack traces, and pinpoint the commit that caused them." +--- + + By the end of this tutorial, you'll be able to: + +- See errors as they happen in both apps and get notified about them. +- Follow a single error across the network boundary from frontend to backend in one distributed trace. +- Read un-minified stack traces that point to the exact line of source code that caused an error. + + + +This tutorial takes about **45 minutes**. Steps 1–4 set up distributed tracing across your stack (roughly 30 minutes). Step 5 is optional and builds on that foundation. + + + +{/* TODO: Screenshot or Arcade showing the final trace view with both projects highlighted as the hero image. */} + +## What You'll Build + +You'll start with two sample apps — one frontend, one backend — and instrument the Sentry SDK into each. You'll then trigger an error from the UI that fails on the backend, and watch Sentry stitch both halves of the failure into a single distributed trace. + +This tutorial uses a [sample React app](https://github.com/getsentry/tracing-tutorial-frontend) on the frontend and a [sample Express API](https://github.com/getsentry/tracing-tutorial-backend) on the backend. Some familiarity with JavaScript will help you follow along. You can also apply the same steps to your own project, as long as you're running React on the frontend and Express on the backend. + +## Prerequisites + +- A [Sentry](https://sentry.io) account — [sign up](https://sentry.io/signup/) if you don't have one +- A [GitHub](https://github.com/) account — [sign up](https://github.com/join) if you don't have one +- [Node 18+](https://nodejs.org/en/download/) + +## Tutorial Steps + +1. [Create Frontend and Backend Sentry Projects](/product/sentry-basics/getting-started-tutorial/create-new-project/) +2. [Add the Sentry SDK to Your Frontend Project](/product/sentry-basics/getting-started-tutorial/initialize-sentry-sdk-frontend/) +3. [Add the Sentry SDK to Your Backend Project](/product/sentry-basics/getting-started-tutorial/initialize-sentry-sdk-backend/) +4. [Capture Your First Distributed Tracing Error](/product/sentry-basics/getting-started-tutorial/generate-first-error/) +5. [Enable Readable Stack Traces](/product/sentry-basics/getting-started-tutorial/enable-readable-stack-traces/) _(optional)_ + +## Next + +[Create your Sentry projects](/product/sentry-basics/getting-started-tutorial/create-new-project/) diff --git a/docs/product/sentry-basics/getting-started-tutorial/initialize-sentry-sdk-backend.mdx b/docs/product/sentry-basics/getting-started-tutorial/initialize-sentry-sdk-backend.mdx new file mode 100644 index 00000000000000..385a9b592e4c4c --- /dev/null +++ b/docs/product/sentry-basics/getting-started-tutorial/initialize-sentry-sdk-backend.mdx @@ -0,0 +1,173 @@ +--- +title: Add the Sentry SDK to Your Backend Project +sidebar_order: 4 +description: "Learn how to add the Sentry SDK to your backend codebase." +--- + +**Step 3 of 5** + + + +This section walks you through how to import the sample app into your local dev environment, then add and initialize the Sentry SDK. +If you're using your own source code, you can skip this section. Instead: + +- Select your [platform](/platforms/) and follow its **Getting Started** guide to add the Sentry SDK to your code. +- Then, skip to the [next step](/product/sentry-basics/getting-started-tutorial/generate-first-error/). + +## 1. Clone the Sample App + +The sample app is a backend API built with Express and Node, using ECMAScript Modules (ESM). + +1. Fork the [sample application's repository](https://github.com/getsentry/tracing-tutorial-backend) on GitHub. + +1. Clone the forked repository to your local environment: + + If you have SSH set up: + + ```bash + git clone git@github.com:/tracing-tutorial-backend.git + ``` + + Otherwise: + + ```bash + git clone https://github.com//tracing-tutorial-backend.git + ``` + +1. Open the `tracing-tutorial-backend` project in your preferred code editor. + +## 2. Add the Sentry Node SDK + +Sentry captures data by using a platform-specific SDK that you add to your app's runtime. To use the SDK, import and configure it in your source code. This demo project uses [Sentry's Node SDK](https://github.com/getsentry/sentry-javascript/tree/master/packages/node). + +1. Navigate to the `tracing-tutorial-backend` project folder and install the Sentry Node SDK. + + ```bash {tabTitle:npm} + npm install --save @sentry/node + ``` + + ```bash {tabTitle:yarn} + yarn add @sentry/node + ``` + + ```bash {tabTitle:pnpm} + pnpm add @sentry/node + ``` + +1. Create a file at the root level of your project and call it `instrument.js`. Import and initialize the SDK using the following code: + + ```javascript {filename:instrument.js} + import * as Sentry from "@sentry/node"; + + Sentry.init({ + dsn: "", + // Capture 100% of transactions for tracing. + tracesSampleRate: 1.0, + }); + ``` + + It's important to import and initialize the SDK as early as possible in your application's lifecycle so Sentry can capture errors throughout it. + +1. Add your DSN key to the Sentry SDK configuration. + + Replace `` in the code above with the DSN key value you copied from the backend project you created in the [previous section](/product/sentry-basics/getting-started-tutorial/create-new-project/). This DSN should be **different** from the one you used on your frontend project — each project has its own unique DSN. + +1. Save the file. + + The options set in `Sentry.init()` are called the SDK's configuration. The only required option is the DSN; the SDK supports many others, which you can read about in our [Configuration](/platforms/javascript/guides/node/configuration/) docs. The configuration above enables Sentry's error monitoring and [**Tracing**](/product/tracing/) features. + +1. Open your `server.js` file, import `Sentry`, and set up the error handler after all controllers and before any other error middleware. You don't import `instrument.js` here — you'll load it with Node's `--import` flag when you start the app (in the next step): + +```javascript diff {filename:server.js} ++ import * as Sentry from "@sentry/node"; + import express from "express"; + import cors from "cors"; + import productsRoute from "./routes/products.js"; + + const app = express(); + + app.use(express.static("public")); + app.use(cors()); + + app.get("/", (req, res) => { + res.send("

Hello, Express.js Server here!

"); + }); + + app.get("/products/debug-sentry", (req, res) => { + console.log("Sentry Error thrown!"); + throw new Error("My first Sentry error!"); + }); + + app.use("/products", productsRoute); + ++ // The error handler must be registered before any other error middleware and after all controllers. ++ Sentry.setupExpressErrorHandler(app); + ++ // Optional fallthrough error handler ++ app.use(function onError(err, req, res, next) { ++ // The error id is attached to `res.sentry` to be returned ++ // and optionally displayed to the user for support. ++ console.log("500 error thrown!"); ++ res.statusCode = 500; ++ res.end(res.sentry + "\n"); ++ }); + + const port = 3001; + + app.listen(port, () => { + console.log(`Server is running on port ${port}`); + }); + +``` + +## 3. Build and Run the Sample Application + +In the `tracing-tutorial-backend` project folder: + +1. Install project dependencies. + + ```bash {tabTitle:npm} + npm install + ``` + + ```bash {tabTitle:yarn} + yarn + ``` + + ```bash {tabTitle:pnpm} + pnpm install + ``` + +1. Start the application: + + ```bash {tabTitle:npm} + npm start + ``` + + ```bash {tabTitle:yarn} + yarn start + ``` + + ```bash {tabTitle:pnpm} + pnpm start + ``` + + The sample app's `start` script runs `node --import ./instrument.js server.js`. The `--import` flag runs `instrument.js` (your `Sentry.init()` call) _before_ the rest of the app loads — which is required for Sentry to instrument an ESM app correctly. If you adapt this to your own ESM project, start it the same way. + + Once the application starts, you'll see a confirmation message similar to this one in your terminal: + + ```bash + Server is running on port 3001 + ``` + +> **Troubleshooting tip**: If the application fails to start due to syntax errors or errors for missing dependencies/modules, make sure you're using Node 18+ and install dependencies again. + +1. Open the sample application in your browser. + + The sample app should be running at [http://localhost:3001/](http://localhost:3001/) or the URL output in your terminal in the last step. You should see the "Hello, Express.js Server here!" message. + +{/* TODO: Arcade or screenshot of the running backend confirming it's live. */} + +## Next + +Well done! You now have a sample Express backend app running with the Sentry SDK initialized. Next, [Capture Your First Distributed Tracing Error](/product/sentry-basics/getting-started-tutorial/generate-first-error/) to start using Sentry's distributed tracing. diff --git a/docs/product/sentry-basics/getting-started-tutorial/initialize-sentry-sdk-frontend.mdx b/docs/product/sentry-basics/getting-started-tutorial/initialize-sentry-sdk-frontend.mdx new file mode 100644 index 00000000000000..7764f59d2d2489 --- /dev/null +++ b/docs/product/sentry-basics/getting-started-tutorial/initialize-sentry-sdk-frontend.mdx @@ -0,0 +1,137 @@ +--- +title: Add the Sentry SDK to Your Frontend Project +sidebar_order: 3 +description: Learn how to add the Sentry SDK to your frontend codebase. +--- + +**Step 2 of 5** + + + +This section walks you through how to import the sample app into your local dev environment, then add and initialize the Sentry SDK. + +If you're using your own source code, you can skip this section. Instead: + +- Select your [platform](/platforms/) and follow its **Getting Started** guide to add the Sentry SDK to your code. +- Then, skip to the [next step](/product/sentry-basics/getting-started-tutorial/initialize-sentry-sdk-backend/). + +## 1. Clone the Sample Application + +The sample application is a frontend app built with React and [Vite](https://vite.dev/). + +1. Fork the [sample application's repository](https://github.com/getsentry/tracing-tutorial-frontend) on GitHub. + +1. Clone the forked repository to your local environment: + + ```bash + git clone git@github.com:/tracing-tutorial-frontend.git + ``` + +1. Open the `tracing-tutorial-frontend` project in your preferred code editor. + +## 2. Add the Sentry React SDK + +Sentry captures data using a platform-specific SDK that you add to your app's runtime. To use the SDK, import and configure it in your source code. This demo project uses [Sentry's React SDK](https://github.com/getsentry/sentry-javascript/tree/develop/packages/react). + +1. Install the Sentry React SDK. + + Make sure you're in the `tracing-tutorial-frontend` project folder. + + ```bash {tabTitle:npm} + npm install @sentry/react --save + ``` + + ```bash {tabTitle:yarn} + yarn add @sentry/react + ``` + + ```bash {tabTitle:pnpm} + pnpm add @sentry/react + ``` + +1. Import and Initialize the SDK. + + Open `src/main.jsx` and add the following lines of code below the last import statement. It's important to import and initialize the SDK as early as possible in your app's lifecycle so Sentry can capture errors throughout it. + + ```javascript {filename:src/main.jsx} + import * as Sentry from "@sentry/react"; + + Sentry.init({ + dsn: "", + integrations: [ + Sentry.browserTracingIntegration(), + Sentry.replayIntegration(), + ], + // Capture 100% of transactions for tracing. + tracesSampleRate: 1.0, + // Enable distributed tracing for requests to these targets. + tracePropagationTargets: ["localhost", /^https:\/\/yourserver\.io\/api/], + // Session Replay sample rates. + replaysSessionSampleRate: 0.1, + replaysOnErrorSampleRate: 1.0, + }); + ``` + +1. Add your DSN key to the Sentry SDK configuration. + + Replace `` in the sample above with the DSN key value you copied from the frontend project you created in the [previous section](/product/sentry-basics/getting-started-tutorial/create-new-project/). + +1. Save the file. + +The options set in `Sentry.init()` are called the SDK's configuration. The only required option is the DSN; the SDK supports many others, which you can read about in our [Configuration](/platforms/javascript/guides/react/configuration/) docs. + +The configuration above enables Sentry's error monitoring, [**Tracing**](/product/tracing/), and [**Session Replay**](/platforms/javascript/guides/react/session-replay/) features. The `tracePropagationTargets` option controls which URLs distributed tracing is enabled for. Since both of this tutorial's apps run on `localhost`, you're all set. + + +## 3. Build and Run the Sample Application + +In the `tracing-tutorial-frontend` project folder: + +1. Install project dependencies. + + ```bash {tabTitle:npm} + npm install + ``` + + ```bash {tabTitle:yarn} + yarn + ``` + + ```bash {tabTitle:pnpm} + pnpm install + ``` + +1. Start the application in development mode. + + ```bash {tabTitle:npm} + npm run dev + ``` + + ```bash {tabTitle:yarn} + yarn dev + ``` + + ```bash {tabTitle:pnpm} + pnpm dev + ``` + + Once the application starts, you'll see a confirmation message similar to this one in your terminal: + + ```bash + VITE v8.1.2 ready in 312 ms + + ➜ Local: http://localhost:3000/ + ➜ Network: use --host to expose + ``` + + > **Troubleshooting tip**: If the application fails to start due to syntax errors or missing dependencies/modules, make sure you're using Node 18+ and install dependencies again. + +1. Open the sample application in your browser. + + The sample app should be running at [http://localhost:3000/](http://localhost:3000/) or the URL output in your terminal in the last step. You should see a sample e-commerce page. Click the buttons on this page to trigger an uncaught runtime error. The buttons won't work correctly until you get your backend up and running. You can follow along with what's happening in the browser by opening your browser's dev tools. + + ![The One-Stop Shop sample app running in the browser, showing the product cards.](img/frontend-screenshot.png) + +## Next + +Nicely done! You now have a sample React app running with the Sentry SDK initialized. Next, [Add the Sentry SDK to Your Backend Project](/product/sentry-basics/getting-started-tutorial/initialize-sentry-sdk-backend/) to get Sentry running across your entire stack. diff --git a/docs/product/sentry-basics/index.mdx b/docs/product/sentry-basics/index.mdx index 05b9ecacb18a72..cf536059e1081f 100644 --- a/docs/product/sentry-basics/index.mdx +++ b/docs/product/sentry-basics/index.mdx @@ -12,14 +12,14 @@ Sentry is a developer-first error tracking and performance monitoring platform. There are three things we recommend you do to get the most out of Sentry: -- **Connect your codebase**, making sure you've also set up [source code management integrations](/integrations/source-code-mgmt/) and [source maps](/product/sentry-basics/integrate-frontend/upload-source-maps/) (if applicable). This will allow Sentry to link errors and performance issues directly to the problematic line of code via readable stack traces and suspect commits. +- **Connect your codebase**, making sure you've also set up [source code management integrations](/integrations/source-code-mgmt/) and [source maps](/product/sentry-basics/getting-started-tutorial/enable-readable-stack-traces/) (if applicable). This will allow Sentry to link errors and performance issues directly to the problematic line of code via readable stack traces and suspect commits. - **Set up [alerts](/product/monitors-and-alerts/alerts/)** to make sure you know when things you care about are going wrong. You can choose to be alerted via one of our chat integrations like [Slack](/integrations/notification-incidents/slack/) or [Discord](/integrations/notification-incidents/discord/). Check out our [alert best practices](/product/monitors-and-alerts/alerts/#alerts-best-practices) to learn how to only get relevant notifications. - **Customize [Discover](/product/explore/discover-queries/), [Dashboards](/product/dashboards/), and [queries](/product/explore/discover-queries/query-builder/)** to better control the kinds of insights you get when things are going wrong in your app. Lastly, create [custom tags](/concepts/search/searchable-properties/#custom-tags) tailored to your use case for more granular searching and querying. **Want a TL;DR for getting started? Download our ["Developer Quick Reference Guide"](/pdfs/developer-quick-reference-guide.pdf)** -## Tutorials: Distributed Tracing, Frontend and Backend Error Monitoring +## Tutorials -Learn how to set up Sentry by following along with a step-by-step distributed tracing, frontend or backend tutorial. +Learn how to set up Sentry by following along with our step-by-step getting started tutorial. diff --git a/docs/product/sentry-basics/integrate-backend/capturing-errors.mdx b/docs/product/sentry-basics/integrate-backend/capturing-errors.mdx deleted file mode 100644 index 40d46edda95c5f..00000000000000 --- a/docs/product/sentry-basics/integrate-backend/capturing-errors.mdx +++ /dev/null @@ -1,145 +0,0 @@ ---- -title: Capturing Errors -sidebar_order: 3 -description: >- - Learn how Sentry captures unhandled errors and handled errors to enrich your - event data. -og_image: /og-images/product-sentry-basics-integrate-backend-capturing-errors.png ---- - -Once initialized in your code, the Sentry SDK will capture errors and various types of events to notify you about them in real-time, depending on the alert rules you've configured. With the Django app already running on your [localhost](http://localhost:8000/), let's try them out. - - - -If you're using your own source code, follow the [Getting Started](/platforms/python/integrations/django/) instructions to introduce an error into your app. - - - -## Unhandled Errors - -The Sentry SDK will automatically capture and report any _unhandled error_ that occurs in your application runtime without any additional configuration or explicit handling. Generally, unhandled errors are errors that aren't caught by a `try/except` clause. - -To trigger an unhandled error: - -1. Run the local Django app. - -2. Point your browser to `http://localhost:8000/unhandled`. - -2. If you've set up an [alert rule](/product/monitors-and-alerts/alerts/), you should be notified about the error. Otherwise, open the [**Issues**](https://sentry.io/orgredirect/organizations/:orgslug/issues/) page in your Sentry account. - -3. You should see the unhandled exception in the list of issues. - - ![Unhandled Issue](./img/unhandled_issue.png) - -4. Click on the issue, to open the **Issue Details** page. - - ![Issue Details Page](./img/error_with_all_tags.png) - -5. Notice that the event: - - - Is tagged with the `environment` and `release` options we've set in the previous tutorial with the tag `handled:no`, marking this event as an unhandled error. - - Contains a suspect commit, made possible because of the commit-tracking feature we enabled earlier. - - Contains the custom breadcrumb we added through the SDK. - - ![Unhandled Breadcrumbs](./img/unhandled_issue_breadcrumbs.png) - -## Handled Errors - -The Sentry SDK contains several methods that you can use to **explicitly** report errors, events, and custom messages in except clauses, critical areas of your code, and so on. - -### Capture Exception - -1. Open the `views.py` file. Notice that we import `sentry_sdk` lib which contains the `capture_exception` method: - - ```python {filename: myapp/views.py} - import sentry_sdk - ``` - -2. The method is used to capture the exception handled by the except clause in `HandledErrorView`: - - ```python {filename: myapp/views.py} - class HandledErrorView(APIView): - def get(self, request): - ... - try: - '2' + 2 - except Exception as err: - sentry_sdk.capture_exception(err) - - return Response() - ``` - -3. To try it out on your localhost, trigger the following endpoint: `http://localhost:8000/handled`. - -4. Similar to what we did with the unhandled error, open the new issue's detail page. - -5. Notice that the event is tagged with the same `environment` and `release` configuration options. Hover over the "i" icon in the release tag to reveal the release information and the commits associated with it. - - ![Handled release](./img/handled_release.png) - -6. Click on the release's "i" icon to navigate to the release page. - -### Capture Message - -Typically, `capture_message` is not emitted, but there are times when a developer may want to add a simple message within their app for debugging purposes, and `capture_message` is great for that. - -1. In the `views.py` file, the `capture_message` method is made available through the `sentry_sdk` lib import. - -2. You can use it anywhere within your app. In our example, we've created a dedicated view class, `CaptureMessageView`, to trigger and capture a message we want to track: - - ```python {filename: myapp/views.py} - sentry_sdk.capture_message("You caught me!") - ``` - -3. To try it out on your localhost, trigger the following endpoint: `http://localhost:8000/message`. - -4. As before, open the new issue’s detail page from the **Issues** page. - - You'll need to remove the `"issue.priority is high or medium"` filter from the "Custom Search" field on the [**Issues**](https://sentry.io/orgredirect/organizations/:orgslug/issues/) page to see all the issue types in the list. - - - - ![Import and Configure SDK](./img/capture_message.png) - - > By default, captured messages are marked with a severity level tag `level:info`, as reflected in the tags section. However, the `capture_message` methods accept an **optional** severity level parameter. - -5. In the `views.py` file, change the `capture_message` method to: - - ```python {filename: myapp/views.py} - sentry_sdk.capture_message("You caught me!", "fatal") - ``` - -6. Save the changes and trigger the `/message` endpoint again. Changes should be applied immediately through `StateReloader`. - -7. Notice that the severity level tag on the new event now shows `level:fatal`. - -## Enriching your Event Data - -You can enrich your event and error data through the Sentry SDK by adding custom tags and user context attributes. In addition to providing more context to your errors, enriched data will expand your options to search, filter, and query through your event metadata. Learn more about the advantages of enriching your data in [Event Data](/product/sentry-basics/enrich-data/). - -To enrich the data of the message events we've captured with `capture_message`: - -1. In the `views.py` file, locate the line that triggers `sentry_sdk.capture_message`. - -2. Replace that line with the following code: - - ```python {filename: myapp/views.py} - sentry_sdk.set_tag("my-tag", "my value") - sentry_sdk.user = { "email" : "my.email@your.domain.com" } - sentry_sdk.set_extra("someVariable", "some data") - - sentry_sdk.capture_message("You caught me!", "fatal") - ``` - -3. Save your changes and trigger the `/message` endpoint again. - -4. Open the issue’s detail page from the [**Issues**](https://sentry.io/orgredirect/organizations/:orgslug/issues/) page. - -5. Notice that: - - - The **user email** is now displayed on the details page and the number of unique users impacted by this event is reflected in the issue's header. - - The **custom tag** is now available (and searchable) in the list of tags. - ![Enriched Event Data](./img/enriched_data_1.png) - - - The **extra data** we set on the SDK is reflected in the "ADDITIONAL DATA" context. - ![Enriched Event Data 2](./img/enriched_data_2.png) diff --git a/docs/product/sentry-basics/integrate-backend/configuration-options.mdx b/docs/product/sentry-basics/integrate-backend/configuration-options.mdx deleted file mode 100644 index bda342daf0f1de..00000000000000 --- a/docs/product/sentry-basics/integrate-backend/configuration-options.mdx +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: Configuration Options -sidebar_order: 2 -description: >- - Learn how to configure releases, breadcrumbs, and environments to enhance the - SDK's functionality. -og_image: /og-images/product-sentry-basics-integrate-backend-configuration-options.png ---- - -Sentry has various configuration options to help enhance the SDK functionality. The options can help provide additional data needed to debug issues even faster or to help control what's sent to Sentry by filtering. Learn more in [Configuration](/platforms/python/configuration/). - -## Releases - -A _release_ is a version of your code that's deployed to an environment. Configuring the release helps you figure out if there's a regression in your code, ensure accountability, resolve issues within Sentry, and stay up-to-date with your deployments. Releases need to be configured within your SDK and then managed through the [sentry-cli](/cli/). - -Sentry currently supports integrations with GitHub, Bitbucket, Azure DevOps, GitLab, and others. For a complete list of our integrations, check out our [Integrations documentation](/integrations/). - -To set up the release in this project: - -1. Open the file `settings.py`. Notice that we add the `release` configuration option when initializing the SDK: - - ```python {filename: myproject/settings.py} - sentry_sdk.init( - ... - release=os.environ.get("VERSION"), - ... - ) - ``` - -2. Open the `Makefile` you ran in the previous tutorial. - - ![Makefile](./img/makefile.png) - -3. Notice that we're setting the release version name as an environment variable that's then used in the application's runtime. We're letting the CLI propose a release version name, but you probably want to apply your own naming conventions: - - ```Makefile {filename: Makefile} - VERSION=`sentry-cli releases propose-version` - ``` - -4. We then create a new release for our project with the proposed or selected name. - - ```Makefile {filename: Makefile} - create_release: - sentry-cli releases -o $(SENTRY_ORG) new -p $(SENTRY_PROJECT) $(VERSION) - ``` - -5. In the previous tutorial, we configured the GitHub integration and added the code repository for commit tracking. Now we can associate commits from that repository to the new release by running the command: - - ```Makefile {filename: Makefile} - associate_commits: - sentry-cli releases -o $(SENTRY_ORG) -p $(SENTRY_PROJECT) \ - set-commits $(VERSION) --auto - ``` - -## Breadcrumbs - -_Breadcrumbs_ are the trail of events that led up to an error. They're very useful for reproducing an issue. Depending on the platform, the SDK will track various types of breadcrumbs by default (for backend SDKs these are DB queries, network events, logging, and others). You can also add your own custom breadcrumbs. - -To add breadcrumbs to our app: - -1. Open the file `myapp > view.py`. - -2. Notice that we import the `sentry_sdk` lib, which contains the `add_breadcrumb` method: - - ```python {filename: myapp/views.py} - import sentry_sdk - ``` - -3. We then create a custom breadcrumb for each method-handler in the view classes. This breadcrumb gets added to the trail of breadcrumbs associated with any error triggered through these method call flows. For instance, under `HandledErrorView.get`: - - ```python {filename: myapp/views.py} - sentry_sdk.add_breadcrumb( - category='URL Endpoints', - message='In the handled function', - level='info', - ) - ``` - -## Environment - -_Environment_ is a powerful configuration option that enables developers using Sentry to perform various workflows, (such as filtering issues and triggering alerts) in the context of the deployment environment in which the errors occurred. - -1. Open the `settings.py` file. - -2. Notice that we initialize the SDK with the `environment` configuration option. Any event that's subsequently captured by the SDK will be tagged with the configured environment value. - - ```python {filename: myproject/settings.py} - sentry_sdk.init( - ... - environment="Production" - ... - ) - ``` - - > Environment values are freeform strings. Neither the Sentry SDK nor [sentry.io](https://sentry.io) will limit you to any specific value or format. In this example, we hardcoded the value. In a real-life app, the value would probably be determined dynamically through a properties file, system, or environment variable. - -## Next - -[Capturing Errors](/guides/integrate-backend/capturing-errors/) diff --git a/docs/product/sentry-basics/integrate-backend/getting-started.mdx b/docs/product/sentry-basics/integrate-backend/getting-started.mdx deleted file mode 100644 index 017dedbee37555..00000000000000 --- a/docs/product/sentry-basics/integrate-backend/getting-started.mdx +++ /dev/null @@ -1,159 +0,0 @@ ---- -title: Getting Started -sidebar_order: 1 -description: >- - Learn how to add and initialize the Sentry SDK for a sample backend - application. -og_image: /og-images/product-sentry-basics-integrate-backend-getting-started.png ---- - -In this tutorial, you'll import the backend app source code into your local development environment, add the Sentry SDK, and initialize it. - - - -If you're using your own source code, you can skip this tutorial and either: - -- Follow the instructions in the [Getting Started](/platforms/python/) docs. -- Go directly to [the next step](/guides/integrate-backend/configuration-options/). - - - -## Prerequisites - -1. The demo app source code requires a Python development environment to build, install, and run the application. Make sure that you have the following in place: - - - A source code editor (like [VS-Code](https://code.visualstudio.com)) - - [Python](https://www.python.org/) - - [Sentry-CLI](/cli/) - -2. To start monitoring errors in your application you'll need to create a new project in your Sentry account. - -## Step 1: Create a Project - -Follow the steps below to create a new Sentry project for a sample Django application: - -1. Log in to your [Sentry organization](https://sentry.io). - -1. Select **Projects** from the left side navigation menu to display the list of all your projects. - -1. Click "Create Project" and configure it as appropriate for your application: - - - **Choose your platform**: Select the language or framework for your project based on the code you wish to monitor. In this case, choose **Django**. - - - **Set your alert frequency**: For the purpose of this tutorial, select **I'll create my own alerts later**. - - > If you're wary of alert fatigue, learn more about how to set up your alerts in [Alerts](/product/monitors-and-alerts/alerts/). - - - **Name your project and assign it a team**: Name your project in the **Project name** field and assign a team by selecting one in the **Team** dropdown (or click **+** to create a new team). - - - Click **Create Project**. This takes you to the quick Configure Django SDK guide, which provides an overview of how to configure the SDK. This tutorial covers the SDK setup in more detail. - -1. Copy the DSN key and keep it handy. Each project has a unique DSN (Data Source Name). The DSN tells the SDK where to send events, so events are associated with the right project. You'll need to paste the DSN key into your source code later so the errors generated in this tutorial go to your new project. - - > You can also find a project's DSN anytime in [Client Keys (DSN)](https://sentry.io/orgredirect/organizations/:orgslug/settings/projects/:projectId/keys/). - -## Step 2: Get the Code - -1. Open the sample [code repository](https://github.com/sentry-tutorials/backend-monitoring) on GitHub. - -2. Click on "Fork" and select the target GitHub account you wish this repository to be forked into. - -3. Once the fork is complete, click on "Clone or download" and copy the repository URL. You can do this using HTTPS, SSH or via GitHub CLI. - - ![Clone Repository](./img/fork_n_clone.png) - -4. Clone the forked repository to your local environment: - - ```bash - > git clone - ``` - -5. Now that the sample code is available locally, open the `backend-monitoring` project in your preferred code editor. - -## Step 3: Enable Commit Tracking for Your Repository - -Sentry can help you resolve your errors faster by suggesting a [suspect commit](/product/sentry-basics/integrate-frontend/configure-scms/) that might have introduced the error into your codebase. This is enabled by configuring _commit tracking_. Integrating your source code management solution and adding your code repositories is required to enable commit tracking. Learn more in our [releases documentation](/product/releases/?platform=node/suspect-commits/). - -1. Open your Sentry account and navigate to **Settings > Integrations** to enable the GitHub integration and add your `backend-monitoring` repository. For more detailed information, follow the steps described in [our GitHub documentation](/integrations/source-code-mgmt/github/). - -## Step 4: Install the SDK - -Sentry captures data by using a platform-specific SDK within your application runtime. To use the SDK, import, initialize, and configure it in your source code. - -1. Install the `sentry-sdk` by defining the dependency in the `requirements.txt` file. The SDK documentation and release information are available in the [Sentry SDK](https://github.com/getsentry/sentry-python) GitHub repository. - -2. Open the `settings.py` file (located under `./backend-monitoring/myproject/settings.py`). This is where we import, initialize, and configure the Sentry SDK in our application. - - - ```python {filename: myproject/settings.py} - import sentry_sdk - - sentry_sdk.init( - dsn="YOUR_DSN", # replace with your DSN - ... - ) - ``` - > In `settings.py` replace `YOUR_DSN` with the `DSN` key value you copied from the project created in the [project creation tutorial](/guides/integrate-frontend/create-new-project/). - - -## Step 5: Install Dependencies and Run the Demo App - -To build and run the demo application on your localhost: - -1. Open a shell terminal and change your directory to the `backend-monitoring` project root folder. - -2. If you haven't installed Python, do so by running the following: - - ```bash - brew install python - ``` - -3. Create a Python virtual environment in the project root. - - ```bash - python -m venv .venv - ``` - - > You can name the virtual environment whatever you like. We named our ".venv". - -4. To activate the virtual environment, run: - - ```bash - source .venv/bin/activate - ``` - -5. Install Sentry's command-line tool to use release tracking and GitHub integration for commit data: - - ```bash - python -m pip install "sentry-cli" - ``` - -6. Open the `Makefile` included in the project's root folder. The file is used here to mimic a CI/CD flow. - -7. Follow the `deploy` target execution flow. - -Commands mentioned within the `Makefile` will be explained in detail in the next part of the tutorial, [Configuration Options](/product/sentry-basics/integrate-backend/configuration-options/). - - -In addition to installing Python requirements and running the server, we also use the `sentry-cli` to create a new Sentry release and associate commits to that release. Sentry will look through these commits when flagging a suspect commit. - - -8. To execute the `sentry-cli` commands, follow these [instructions](/product/sentry-basics/integrate-frontend/upload-source-maps/#step-1-prepare-the-build-environment) to obtain the values for your `SENTRY_AUTH_TOKEN`, `SENTRY_ORG`, and `SENTRY_PROJECT` environment variables. - - ![Makefile Config](./img/makefile_config.png) - - > The `sentry-cli` can be configured by providing these values either through environment variables or through a dedicated configuration file. Learn more in [Sentry CLI: Configuration and Authentication](/cli/configuration/). - -9. Run the following command to install the required Python libraries, set up the Sentry Release, and run the Django server: - - ```bash - make deploy - ``` - - ![Deploy & Serve](./img/run_django_server.png) - - > Notice that a new release is created in the terminal and commits are associated with it. Once the deploy finishes successfully, you'll see the confirmation in your terminal. - -## Next - -[Configuration Options](/guides/integrate-backend/configuration-options/) diff --git a/docs/product/sentry-basics/integrate-backend/img/capture_message.png b/docs/product/sentry-basics/integrate-backend/img/capture_message.png deleted file mode 100644 index 5307ae42c27b0b..00000000000000 Binary files a/docs/product/sentry-basics/integrate-backend/img/capture_message.png and /dev/null differ diff --git a/docs/product/sentry-basics/integrate-backend/img/enriched_data_1.png b/docs/product/sentry-basics/integrate-backend/img/enriched_data_1.png deleted file mode 100644 index cb72b29b450d78..00000000000000 Binary files a/docs/product/sentry-basics/integrate-backend/img/enriched_data_1.png and /dev/null differ diff --git a/docs/product/sentry-basics/integrate-backend/img/enriched_data_2.png b/docs/product/sentry-basics/integrate-backend/img/enriched_data_2.png deleted file mode 100644 index 5f3bd33d207dec..00000000000000 Binary files a/docs/product/sentry-basics/integrate-backend/img/enriched_data_2.png and /dev/null differ diff --git a/docs/product/sentry-basics/integrate-backend/img/error_with_all_tags.png b/docs/product/sentry-basics/integrate-backend/img/error_with_all_tags.png deleted file mode 100644 index b01f7f82d4af1d..00000000000000 Binary files a/docs/product/sentry-basics/integrate-backend/img/error_with_all_tags.png and /dev/null differ diff --git a/docs/product/sentry-basics/integrate-backend/img/fork_n_clone.png b/docs/product/sentry-basics/integrate-backend/img/fork_n_clone.png deleted file mode 100644 index 6c37dd29ec48c9..00000000000000 Binary files a/docs/product/sentry-basics/integrate-backend/img/fork_n_clone.png and /dev/null differ diff --git a/docs/product/sentry-basics/integrate-backend/img/handled_release.png b/docs/product/sentry-basics/integrate-backend/img/handled_release.png deleted file mode 100644 index ce84a3de82659b..00000000000000 Binary files a/docs/product/sentry-basics/integrate-backend/img/handled_release.png and /dev/null differ diff --git a/docs/product/sentry-basics/integrate-backend/img/makefile.png b/docs/product/sentry-basics/integrate-backend/img/makefile.png deleted file mode 100644 index 218ee641b754f2..00000000000000 Binary files a/docs/product/sentry-basics/integrate-backend/img/makefile.png and /dev/null differ diff --git a/docs/product/sentry-basics/integrate-backend/img/makefile_config.png b/docs/product/sentry-basics/integrate-backend/img/makefile_config.png deleted file mode 100644 index eaa8cf5a7d6ce1..00000000000000 Binary files a/docs/product/sentry-basics/integrate-backend/img/makefile_config.png and /dev/null differ diff --git a/docs/product/sentry-basics/integrate-backend/img/run_django_server.png b/docs/product/sentry-basics/integrate-backend/img/run_django_server.png deleted file mode 100644 index cd63aa4f239ab7..00000000000000 Binary files a/docs/product/sentry-basics/integrate-backend/img/run_django_server.png and /dev/null differ diff --git a/docs/product/sentry-basics/integrate-backend/img/unhandled_issue.png b/docs/product/sentry-basics/integrate-backend/img/unhandled_issue.png deleted file mode 100644 index 9c762f1d1e6f93..00000000000000 Binary files a/docs/product/sentry-basics/integrate-backend/img/unhandled_issue.png and /dev/null differ diff --git a/docs/product/sentry-basics/integrate-backend/img/unhandled_issue_breadcrumbs.png b/docs/product/sentry-basics/integrate-backend/img/unhandled_issue_breadcrumbs.png deleted file mode 100644 index 6fad93c943e58e..00000000000000 Binary files a/docs/product/sentry-basics/integrate-backend/img/unhandled_issue_breadcrumbs.png and /dev/null differ diff --git a/docs/product/sentry-basics/integrate-backend/index.mdx b/docs/product/sentry-basics/integrate-backend/index.mdx deleted file mode 100644 index a11f1ee53c6490..00000000000000 --- a/docs/product/sentry-basics/integrate-backend/index.mdx +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Backend Error Monitoring Tutorial -sidebar_order: 40 -description: "Follow this tutorial to set up Sentry to monitor errors for a sample Python backend application. By the end, you'll be able to configure the SDK for your needs and enrich your event data." ---- - -This step-by-step tutorial walks you through the flow of setting up and configuring your Sentry account to monitor errors in your Python backend application. As part of this tutorial, you will: - -- Add basic configurations to the Sentry SDK -- Monitor various types of events and errors to Sentry -- Implement error tracing between your frontend and backend applications - -This tutorial uses a [sample Django application](https://github.com/sentry-tutorials/backend-monitoring). This allows us to streamline the steps required to getting the maximum value out of integrating Sentry into your development workflow. - -Alternatively, you can follow this guide as a reference and apply the relevant changes directly to your source code. - -## Prerequisites - -- A [Sentry](https://sentry.io) account, or [sign up](https://sentry.io/signup/) for one -- A [GitHub](https://github.com/) account, or [sign up](https://github.com/join) for one - -## Next - -[Getting Started](/guides/integrate-backend/getting-started/) diff --git a/docs/product/sentry-basics/integrate-frontend/configure-scms.mdx b/docs/product/sentry-basics/integrate-frontend/configure-scms.mdx deleted file mode 100644 index 9b0425a5885ca5..00000000000000 --- a/docs/product/sentry-basics/integrate-frontend/configure-scms.mdx +++ /dev/null @@ -1,186 +0,0 @@ ---- -title: Enable Suspect Commits & Stack Trace Linking -sidebar_order: 5 -description: >- - Learn how to integrate your source code with Sentry, so that Sentry can track - commits and surface suspect commits and suggested assignees to help you - resolve issues faster. -og_image: /og-images/product-sentry-basics-integrate-frontend-configure-scms.png ---- - - - -Sentry uses commit metadata from your source code repositories to help you resolve your issues faster. This is done by suggesting _suspect commits_ that might have introduced an error right in your **Issue Details** page. It also allows Sentry to display _suggested assignees_ — the list of the authors of those commits — and suggest their assignment to resolve the issue. - -Now that you've created a release, you can tell Sentry which commits are associated with this latest version of your code; this is called _commit tracking_. - -## 1. Integrate Your GitHub Account and Repository - -Use Sentry's GitHub integration to link your source code repository to your Sentry project. This enables Sentry to use commit metadata to help you streamline issue triaging. - -1. To integrate GitHub with your Sentry org, follow the [GitHub Integration Install instructions](/integrations/source-code-mgmt/github/#install). Be sure to give the integration access to the appropriate repository — in this case, the `frontend-tutorial` repo you forked. - - After you've added the integration, you should be redirected to a page showing your GitHub repositories in Sentry. Verify that the right repos have been added. - -1. Go to the "Code Mappings" tab. - -1. Click "Add Code Mapping". - -1. Fill out the information requested to add a code mapping between your Sentry project and the `frontend-tutorial` repository's `main` or `master` branch. Tell Sentry that your components live in the `src/` directory: - - ![Add code mapping](./img/configure-scms-09.png) - -### UI Walkthrough - -Follow along with the interactive demo below to see how to integrate your GitHub account and repository. - - - -## 2. Set Up Commit Tracking - -A _release_ is a version of your code deployed to an environment. See the [Releases](/product/releases/) documentation to learn more. Sentry uses releases to match up your source maps and source code. Releases can also be used to enable Sentry's [Suspect Commits](/product/issues/suspect-commits/) feature. - -The Sentry webpack plugin can automatically configure release information and send it to Sentry when you create a new build of your project. Let's enable this feature. - -1. Go back to your `frontend-tutorial` project and stop it with `Ctrl + C`. - -1. Create a Sentry auth token: - - - - ```bash {filename:.env} - SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___ - ``` - - You'll need to pass your auth token to your build command later on. We recommend storing it inside an environment variable. Auth tokens should always stay secret, so avoid storing yours inside your version control. - -1. To start associating commits and releases, add the following lines of code to `webpack.config.js` in your Sentry webpack plugin config: - - - ```javascript {filename:webpack.config.js} - sentryWebpackPlugin({ - org: "___ORG_SLUG___", - project: "___PROJECT_SLUG___", - authToken: process.env.SENTRY_AUTH_TOKEN, - - // Enable automatically creating releases and associating commits - release: { - create: true, - setCommits: { - auto: true, - }, - }, - }), - ``` - -1. Save the file. - -## 3. Create a New Error and Commit - -Now that releases are set up to track commits, tweak the error and create a new commit to verify that this works. - -1. In `src/components/App.js`, edit line 97. This will make sure Sentry recognizes a new error that it can associate with the release you will create. - - ```javascript {filename:src/components/App.js} - this.myCodeIsMorePerfect(); - ``` - -1. Save the file. - -1. Add all your changes to git with: - - ```bash - git commit -am 'Added a new error and some other stuff' - git push - ``` - -1. Create another production build. During this process, the webpack plugin will create a new release and associate your commit to that release. - - ```bash - npm run build - ``` - -1. Run your production build: - - ```bash - npx serve build - ``` - -1. Create a new issue for Sentry by generating another error in your app. Open the URL your app is running in, add products to your cart, and click "Checkout". You should soon see a new issue in Sentry. - -## 4. Verify Suspect Commits and Suggested Assignees - -Now suspect commits and suggested assignees should start appearing on the **Issue Details** page. Sentry determines these using files observed in the stack trace, authors of those files, and ownership rules. - -1. Check your email for the alert about the new error. Notice that a new "Suspect Commits" section has been added to the email. - - ![Suspect Commits email](./img/issue_email_suspect_commits.png) - -1. Click "View on Sentry" to open the **Issue Details** page. - -1. Verify that the "Suspect Commits" section now points to the suspected commit that likely introduced the error. You can click on the commit link to see the actual commit details on GitHub. - -1. In the right side panel, click under "Assigned To" to open the dropdown to see suggested assignees. You'll see that the author of the suspect commit is listed as a suggested assignee for this issue. - - ![Suggested Assignees](./img/suggested_assignees.png) - - You can assign the issue to the suggested assignee by clicking on their email. Alternatively, you can choose to assign the issue to other users or teams associated with the project. - -### UI Walkthrough - -The interactive demo below shows how to view suspect commits and suggested assignees for an issue. - - - -## 5. Verify Release Configuration - -Verify that releases have been configured correctly. - -1. In the main panel's "Tags" section, find the `release` tag and hover over the release ID link. You should see in the popup that the release now contains commit data. - -1. Click on the release ID link to open the **Release Details** page. - -1. Select the "Commits" tab. Notice that release now contains the associated list of commits. - -### UI Walkthrough - -The interactive demo below shows how to view commits associated with the release. - - - -## 6. Use Stack Trace Links - -Stack trace links allows you to jump from a stack trace in [sentry.io](https://sentry.io) to the corresponding file in your source code provider. This is done by matching the file path in the stack trace to the file path in your source code provider. - -1. Go to the **Issue Details** page for the error you generated in the previous step. - -1. Click "Tell us where your source code is" so Sentry can verify your code mapping. - -1. In the popup, verify or enter the file path and the correct GitHub URL. - -1. Click "Save". You should now see that the stack trace is linked to the code file in GitHub. - -1. Click "Open this line in GitHub" to go directly to the line of code causing the error. - -### UI Walkthrough - -The interactive demo below walks through how to set up and view stack trace links in the UI. - - - -## More Information - -With GitHub integrated and your releases linked to your sources and commits, you can use Sentry's suspect commits, suggested assignees, and stack trace links to help you triage and resolve issues faster. To learn more about how to get the most value out of releases and integrations, check out these resources: - -- [Create Release and Associate Commits](/product/releases/setup/) -- [Global Integrations](/integrations/) - -## Next Steps - -You should now have Sentry's error monitoring set up with source maps and suspect commits working. - -On top of error monitoring, Sentry offers other features to help you detect and fix problems with your apps, like: - -- [Session Replay](/product/explore/session-replay/) to view a a video-like reproduction of your user sessions when errors occur. -- [pre-built Sentry Dashboards](/product/dashboards/sentry-dashboards/) to track application performance and errors across services. -- [Profiling](/product/explore/profiling/) to get deeper level of visibility on top of traditional tracing. diff --git a/docs/product/sentry-basics/integrate-frontend/create-new-project.mdx b/docs/product/sentry-basics/integrate-frontend/create-new-project.mdx deleted file mode 100644 index 9ba5e0982b7a17..00000000000000 --- a/docs/product/sentry-basics/integrate-frontend/create-new-project.mdx +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Create a Sentry Project -sidebar_order: 1 -description: "Learn how to create a Sentry project, which scopes events to a distinct piece of your application landscape." ---- - -This section walks you through how to create a new project in your Sentry account. You need to have a project set up in Sentry in order to capture errors and other events. - -_Projects_ allow you to scope events to a distinct application in your organization and assign responsibility to specific users and teams. You can create a project for a particular language or framework used in your application. For example, you might have separate projects for your API server and frontend client. For more information, see [best practices for creating projects](/organization/getting-started/#4-create-projects). - -## Create a Project - -Follow the steps below to create a new Sentry project for a sample React application: - -1. Log in to your [Sentry organization](https://sentry.io). - -1. Select **Projects** from the left side navigation menu to display the list of all your projects. - -1. Click "Create Project" and configure it as appropriate for your application: - - - **Choose your platform**: Select the language or framework for your project based on the code you wish to monitor. In this case, choose **React**. - - - **Set your alert frequency**: For the purpose of this tutorial, select **Alert me on high priority issues**. - - > If you're wary of alert fatigue, learn more about how to set up your alerts in [Alerts](/product/monitors-and-alerts/alerts/). - - - **Name your project and assign it a team**: Name your project in the **Project name** field and assign a team by selecting one in the **Team** dropdown (or click **+** to create a new team). - - - Click **Create Project**. This takes you to the quick Configure React SDK guide, which provides an overview of how to configure the SDK. This tutorial covers the SDK setup in more detail. - -1. Copy the DSN key and keep it handy. Each project has a unique DSN (Data Source Name). The DSN tells the SDK where to send events, so events are associated with the right project. You'll need to paste the DSN key into your source code later so the errors generated in this tutorial go to your new project. - - > You can also find a project's DSN anytime in [Client Keys (DSN)](https://sentry.io/orgredirect/organizations/:orgslug/settings/projects/:projectId/keys/). - -1. Click **Take me to Issues** to go to your new project's **Issues** page. - -### UI Walkthrough - -The interactive demo below walks through how to create a new project in the UI. - - - -## Next - -Now that you have a Sentry project set up, you can [Add the Sentry SDK to Your Project](/product/sentry-basics/integrate-frontend/initialize-sentry-sdk/). diff --git a/docs/product/sentry-basics/integrate-frontend/generate-first-error.mdx b/docs/product/sentry-basics/integrate-frontend/generate-first-error.mdx deleted file mode 100644 index 3370bce69490d7..00000000000000 --- a/docs/product/sentry-basics/integrate-frontend/generate-first-error.mdx +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: Capture Your First Error -sidebar_order: 3 -description: Learn how to capture your first error and view it in Sentry. -og_image: /og-images/product-sentry-basics-integrate-frontend-generate-first-error.png ---- - -Now that the sample app is up and running on your local environment integrated with the Sentry SDK, you're ready to generate the first error. - -## 1. Trigger an Error - -To start using Sentry's error monitoring feature, you need some errors first. Let's add in an obvious error that will be easy to see in Sentry. - -If you're using your own source code, skip this step. Instead, select your [platform](/platforms/) and follow its **Verify** step inside the **Getting Started** guide to introduce an error. - -1. Open `src/components/App.js` and uncomment line 97. - - ```javascript {filename:src/components/App.js} - this.myCodeIsPerfect(); - ``` - - The function `myCodeIsPerfect()` isn't defined, so this will throw an error. - -1. Save the file. - -1. Refresh your browser and open the browser developer console. - - The app is running in develop mode, so the change to your app should work after a refresh. You shouldn't see any errors in the console yet. - -1. Click on any of the "Buy!"" buttons to add products to your shopping cart. - -1. Click the "Checkout" button on the right panel to generate an error. - - - - Notice that: - - - An error message "Something went wrong" displays in the app. - - The error appears in the browser console. - - ![Import and Configure SDK](./img/generate-first-error-01.png) - - - An alert is sent to your email address configured on Sentry notifying you about an error that occurred in your app. - - ![Alert Email](./img/new_issue_email.png) - -## 2. View the Error in Sentry - -Now that you've triggered an error, let's see what it looks like in Sentry. - -1. Open the **Issues** page in [Sentry.io](https://sentry.io/). Make sure your project is selected in the projects dropdown. - -2. Select the error from the issues list to to view the full details and context of this error. - - Note that Sentry aggregates similar errors (events) into one [Issue](/product/issues/). If you trigger this error multiple times, you won't see more issues appear. Instead, you'll see the number of events for that issue increase. - -3. On the [Issue Details](/product/issues/issue-details/) page, scroll down to the stack trace. - - Notice that the stack trace is _minified_. JavaScript is typically minified to reduce to the size of the source code. This means you can't see the actual lines of code from your app in the stack trace. - - With a little configuration, Sentry can unminify your code back to its readable form and display your source code in each stack frame. You'll set this up in the next section. - -### UI Walkthrough - -The interactive demo below walks through how to view error details in Sentry. - - - -## Next - -At this point, you've verified that Sentry is monitoring errors for your app. So you know there's an issue, but where do you go to fix it? In the next section, you'll learn how to [Enable Readable Stack Traces in Your Errors](/product/sentry-basics/integrate-frontend/upload-source-maps/) so Sentry can show you exactly which line in which file is causing the issue. diff --git a/docs/product/sentry-basics/integrate-frontend/img/FE-tutorial-demo-app.png b/docs/product/sentry-basics/integrate-frontend/img/FE-tutorial-demo-app.png deleted file mode 100644 index e4896b8b0dc0fc..00000000000000 Binary files a/docs/product/sentry-basics/integrate-frontend/img/FE-tutorial-demo-app.png and /dev/null differ diff --git a/docs/product/sentry-basics/integrate-frontend/img/configure-scms-09.png b/docs/product/sentry-basics/integrate-frontend/img/configure-scms-09.png deleted file mode 100644 index 9d088413271c2d..00000000000000 Binary files a/docs/product/sentry-basics/integrate-frontend/img/configure-scms-09.png and /dev/null differ diff --git a/docs/product/sentry-basics/integrate-frontend/img/generate-first-error-01.png b/docs/product/sentry-basics/integrate-frontend/img/generate-first-error-01.png deleted file mode 100644 index 4b289e64b90fb8..00000000000000 Binary files a/docs/product/sentry-basics/integrate-frontend/img/generate-first-error-01.png and /dev/null differ diff --git a/docs/product/sentry-basics/integrate-frontend/img/issue_email_suspect_commits.png b/docs/product/sentry-basics/integrate-frontend/img/issue_email_suspect_commits.png deleted file mode 100644 index 598359f1dffb0d..00000000000000 Binary files a/docs/product/sentry-basics/integrate-frontend/img/issue_email_suspect_commits.png and /dev/null differ diff --git a/docs/product/sentry-basics/integrate-frontend/img/new_issue_email.png b/docs/product/sentry-basics/integrate-frontend/img/new_issue_email.png deleted file mode 100644 index 8868525d5d6add..00000000000000 Binary files a/docs/product/sentry-basics/integrate-frontend/img/new_issue_email.png and /dev/null differ diff --git a/docs/product/sentry-basics/integrate-frontend/img/suggested_assignees.png b/docs/product/sentry-basics/integrate-frontend/img/suggested_assignees.png deleted file mode 100644 index b8b9a4ebba5013..00000000000000 Binary files a/docs/product/sentry-basics/integrate-frontend/img/suggested_assignees.png and /dev/null differ diff --git a/docs/product/sentry-basics/integrate-frontend/img/upload-source-maps-08.png b/docs/product/sentry-basics/integrate-frontend/img/upload-source-maps-08.png deleted file mode 100644 index 0a59572a8f2abb..00000000000000 Binary files a/docs/product/sentry-basics/integrate-frontend/img/upload-source-maps-08.png and /dev/null differ diff --git a/docs/product/sentry-basics/integrate-frontend/index.mdx b/docs/product/sentry-basics/integrate-frontend/index.mdx deleted file mode 100644 index 82ac4cea5fbd95..00000000000000 --- a/docs/product/sentry-basics/integrate-frontend/index.mdx +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Frontend Error Monitoring Tutorial -sidebar_order: 30 -description: "Follow this tutorial to set up Sentry for a sample React frontend application. By the end, you'll be able to monitor errors and view readable stack traces and suspect commits to help you identify and debug." ---- - -This step-by-step tutorial walks you through setting up Sentry in a React project to monitor errors in a frontend application. After completing this tutorial you'll be able to: - -- Receive alerts when errors occur in your code -- View a readable stack trace with source code context -- View suspect commits and suggested assignees based on commit information and stack traces - -This tutorial uses a [sample React application](https://github.com/getsentry/frontend-tutorial). You can follow along with the provided sample code or apply the same steps to your own project. - -## Prerequisites - -- A [Sentry](https://sentry.io) account, or [sign up](https://sentry.io/signup/) for one -- A [GitHub](https://github.com/) account, or [sign up](https://github.com/join) for one -- [Node 18+](https://nodejs.org/en/download/) - -## Next - -[Create a Sentry Project](/product/sentry-basics/integrate-frontend/create-new-project/) diff --git a/docs/product/sentry-basics/integrate-frontend/initialize-sentry-sdk.mdx b/docs/product/sentry-basics/integrate-frontend/initialize-sentry-sdk.mdx deleted file mode 100644 index 51ffb4d11a5521..00000000000000 --- a/docs/product/sentry-basics/integrate-frontend/initialize-sentry-sdk.mdx +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: Add the Sentry SDK to Your Project -sidebar_order: 2 -description: Learn how to add the Sentry SDK to your frontend codebase. -og_image: /og-images/product-sentry-basics-integrate-frontend-initialize-sentry-sdk.png ---- - -This section walks you through how to import the sample application into your local development environment, add the Sentry SDK, and initialize it. - -If you're using your own source code, you can skip this section. Instead: - -- Select your [platform](/platforms/) and follow its **Getting Started** guide to add the Sentry SDK to your code. -- Then, skip to the [next step](/guides/integrate-frontend/generate-first-error/). - -## 1. Clone the Sample Application - -The sample application is a basic frontend-only application using React and webpack. - -1. Fork the [sample application's repository](https://github.com/getsentry/frontend-tutorial) on GitHub. - -1. Clone the forked repository to your local environment: - - ```bash - git clone git@github.com:/frontend-tutorial.git - ``` - -1. Open the `frontend-tutorial` project in your preferred code editor. - -## 2. Add the Sentry React SDK - -Sentry captures data by using a platform-specific SDK that you add to your application's runtime. To use the SDK, import and configure it in your source code. This demo project uses [Sentry's React SDK](https://github.com/getsentry/sentry-javascript/tree/develop/packages/react). - -1. Install the Sentry React SDK using a package manager. - - Make sure you're in the `frontend-tutorial` project folder. - - ```bash {tabTitle:npm} - npm install @sentry/react --save - ``` - - ```bash {tabTitle:yarn} - yarn add @sentry/react - ``` - - ```bash {tabTitle:pnpm} - pnpm add @sentry/react - ``` - -1. Import and initialize the SDK. - - Open `src/index.js` and add the following lines of code below the last import statement: - - ```javascript {filename:src/index.js} - import * as Sentry from "@sentry/react"; - - Sentry.init({ - dsn: "", - integrations: [Sentry.browserTracingIntegration(), Sentry.replayIntegration()], - - // Set tracesSampleRate to 1.0 to capture 100% - // of transactions for performance monitoring. - // Learn more at - // https://docs.sentry.io/platforms/javascript/configuration/options/#traces-sample-rate - tracesSampleRate: 1.0, - - // Capture Replay for 10% of all sessions, - // plus for 100% of sessions with an error - // Learn more at - // https://docs.sentry.io/platforms/javascript/session-replay/configuration/#general-integration-configuration - replaysSessionSampleRate: 0.1, - replaysOnErrorSampleRate: 1.0, - }); - ``` - - It's important to import and initialize the SDK as early as possible in your application's lifecycle so Sentry can capture errors throughout the lifecycle. - -1. Add your DSN key to the Sentry SDK configuration. - - Paste in the DSN key value you copied from the project created in the [previous section](/product/sentry-basics/integrate-frontend/create-new-project/). - - ```javascript {filename:src/index.js} - Sentry.init({ - dsn: "", - // ... - }); - ``` - -1. Save the file. - -The options set in `Sentry.init()` are called the SDK's configuration. The only required configuration option is the DSN. However, the SDK supports many other configuration options. Learn more in our [Configuration](/platforms/javascript/guides/react/configuration/) docs. - -The configuration above enables Sentry's error monitoring feature, as well as its [Performance](/platforms/javascript/guides/react/performance) (tracing) and [Session Replay](/platforms/javascript/guides/react/session-replay) features. - -## 3. Build and Run the Sample Application - -In the `frontend-tutorial` project folder: - -1. Install project dependencies. - - ```bash - npm install - ``` - -1. Start the application in develop mode. - - ```bash - npm start - ``` - - Once the application starts, you'll see a confirmation message similar to this one in your terminal: - - ```bash - [webpack-dev-server] Project is running at: - [webpack-dev-server] Loopback: http://localhost:3000/ - ... - webpack 5.87.0 compiled successfully in 1306 ms - ``` - - > **Troubleshooting tip**: If the application fails to start due to syntax errors or errors for missing dependencies/modules, make sure you're using Node 18+ and install dependencies again. Run `nvm use 18` and then `npm install`. - -1. Open the sample application in your browser. - - The sample app should be running at [http://localhost:3000/](http://localhost:3000/) or the URL output in your terminal in the last step. - - ![Sample app UX showing an online hardware store](./img/FE-tutorial-demo-app.png) - -## Next - -At this point, you have a sample React app running with the Sentry SDK initialized. Next, [Capture Your First Error](/product/sentry-basics/integrate-frontend/generate-first-error/) to start using Sentry's error monitoring feature. diff --git a/docs/product/sentry-basics/integrate-frontend/upload-source-maps.mdx b/docs/product/sentry-basics/integrate-frontend/upload-source-maps.mdx deleted file mode 100644 index 0d586f15747f9b..00000000000000 --- a/docs/product/sentry-basics/integrate-frontend/upload-source-maps.mdx +++ /dev/null @@ -1,141 +0,0 @@ ---- -title: Enable Readable Stack Traces in Your Errors -sidebar_order: 4 -description: >- - Learn how to upload source maps to enable readable stack traces in your - errors. -og_image: /og-images/product-sentry-basics-integrate-frontend-upload-source-maps.png ---- - -When creating web applications, most development workflows involve transforming your JavaScript code via transpilation and minification to make it run more efficiently in the browser. Source map files serve as a guide for tools like Sentry to convert the transformed version of your JavaScript back to the code that you wrote. Source map files can be generated by your JavaScript build tool. - -The sample project uses webpack as its build tool. We'll configure it to generate source maps and check that they are output. - -If your project has a different configuration, use the [Sentry Wizard](/platforms/javascript/sourcemaps/#uploading-source-maps) to configure your source maps and skip to step 3. - -## 1. Generate Source Map Files Using Your Build Tool - -1. To configure webpack to generate source maps, open `webpack.config.js` add the following line inside of `module.exports`: - - ```javascript {filename:webpack.config.js} - ... - module.exports = { - entry: "./src/index.js", - output: { - filename: "main.js", - path: path.resolve(__dirname, "build"), - }, - devtool: "hidden-source-map", // Source map generation must be turned on ("hidden-source-map", "source-map", etc.) - ... - } - ... - ``` - - If you're using the sample project, you can uncomment line 11. - -1. Save the file. - -1. Webpack only generates source maps when you create a production build. To do so, stop your app running in develop mode with `Ctrl + C` and start a production build by running: - - ```bash - npm run build - ``` - - You should see a new `build` folder in your project. Inside, there should be a `main.js` file and a `main.js.map` file. `main.js` is your minified JavaScript. `main.js.map` is the source map file. - -## 2. Upload Your Source Maps to Sentry - -1. Install the Sentry webpack plugin - - ```bash - npm install @sentry/webpack-plugin --save-dev - ``` - -1. To generate a Sentry auth token & store it so it can be used, paste the following into your terminal: - - - - ```bash {filename:.env} - export SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___ - ``` - -1. Open `webpack.config.js` and add the following lines to add the plugin configuration to webpack. - - - ```javascript {filename:webpack.config.js} - const { sentryWebpackPlugin } = require("@sentry/webpack-plugin"); - - ... - - module.exports = { - ... - plugins: [ - sentryWebpackPlugin({ - org: "___ORG_SLUG___", - project: "___PROJECT_SLUG___", - authToken: process.env.SENTRY_AUTH_TOKEN, - - sourcemaps: { - // As you're enabling client source maps, you probably want to delete them after they're uploaded to Sentry. - // Set the appropriate glob pattern for your output folder - some glob examples below: - filesToDeleteAfterUpload: ["./**/*.map", ".*/**/public/**/*.map", "./dist/**/client/**/*.map"] - } - }), - ], - ... - } - ``` - -1. You can find your `org` as part of your Sentry URL (for example, https://**\**.sentry.io/), or in the **Organization Settings** page. - -## 3. Trigger Another Error - -1. Create a fresh production build with your changes from the previous step: - - ```bash - npm run build - ``` - -1. Confirm that your source maps were correctly uploaded to Sentry and associated with your project's latest release. Your terminal output should include a `Source Map Upload Report`, which might look like the following: - - ```bash - > Organization: - > Project: - > Release: 0d40018e21151113e224f208fb934a0d29f10508 - > Dist: None - > Upload type: artifact bundle - Source Map Upload Report - Minified Scripts - ~/f320b889-aa78-4850-8625-802a2ee9aca3-0.js (sourcemap at main.js.map, debug id f320b889-aa78-4850-8625-802a2ee9aca3) - Source Maps - ~/f320b889-aa78-4850-8625-802a2ee9aca3-0.js.map (debug id f320b889-aa78-4850-8625-802a2ee9aca3) - [sentry-webpack-plugin] Info: Successfully uploaded source maps to Sentry - ``` - -1. Run your production build: - - ```bash - npx serve build - ``` - -1. Open the production build of the sample application in your browser. - - The sample app should be running at [http://localhost:3000/](http://localhost:3000/) or the URL output in your terminal in the last step. - -1. In your browser, make sure that the dev console is open and perform an "Empty Cache and Hard Reload" to make sure the updated code is being served. - - ![Release Created](./img/upload-source-maps-08.png) - -1. Generate the error again by adding products to your cart and clicking "Checkout". - -1. Go to the **Issues** page in Sentry. Since you added a new release, a new issue should be created even though it's the same error as before. - -1. Click on the new issue to open its **Issue Details** page. - -1. Notice that there's now a release tag for the issue and that the error stack trace is now un-minified. The stack trace now includes the file name, method name, line and column number, and source code context in every stack frame. - - - -## Next - -Now you have all the information you need about the error and a clear stack trace. To get even more value out of Sentry, [Enable Suspect Commits & Stack Trace Linking](/product/sentry-basics/integrate-frontend/configure-scms/) so you can go directly to the code and assign the right developer to handle the issue. diff --git a/docs/product/sentry-basics/performance-monitoring.mdx b/docs/product/sentry-basics/performance-monitoring.mdx index 1e6e56fedaa213..133b276a3b8e36 100644 --- a/docs/product/sentry-basics/performance-monitoring.mdx +++ b/docs/product/sentry-basics/performance-monitoring.mdx @@ -56,7 +56,7 @@ Opting into the [Early Adopter](https://sentry.io/orgredirect/settings/:orgslug/ ## How to set up Performance Monitoring -For basic frontend or backend performance monitoring, just turn on Tracing in your relevant SDK. This will automatically trace every network request and give you a basic set of performance metrics. However, to make sure Sentry is capturing accurate and complete performance data, you need to set up [Distributed Tracing](/product/sentry-basics/distributed-tracing/). NextJS, Laravel, Ruby on Rails and a few others have strong out-of-the-box support for distributed tracing, but for more complex or multi-language applications, you'll need to configure this manually. Learn more about trace propagation [here](/platforms/javascript/tracing/distributed-tracing/). +For basic frontend or backend performance monitoring, just turn on Tracing in your relevant SDK. This will automatically trace every network request and give you a basic set of performance metrics. However, to make sure Sentry is capturing accurate and complete performance data, you need to set up [Distributed Tracing](/product/sentry-basics/getting-started-tutorial/). NextJS, Laravel, Ruby on Rails and a few others have strong out-of-the-box support for distributed tracing, but for more complex or multi-language applications, you'll need to configure this manually. Learn more about trace propagation [here](/platforms/javascript/tracing/distributed-tracing/). ## How Performance Monitoring works under the hood diff --git a/redirects.js b/redirects.js index dc45e24574aa83..6e69804689d2ee 100644 --- a/redirects.js +++ b/redirects.js @@ -1219,6 +1219,40 @@ const userDocsRedirects = [ source: '/product/sentry-basics/concepts/:path*', destination: '/concepts/key-terms/:path*', }, + // The distributed-tracing, integrate-frontend, and integrate-backend + // tutorials were consolidated into the single getting-started-tutorial. + { + source: '/product/sentry-basics/integrate-frontend/create-new-project/', + destination: '/product/sentry-basics/getting-started-tutorial/create-new-project/', + }, + { + source: '/product/sentry-basics/integrate-frontend/initialize-sentry-sdk/', + destination: '/product/sentry-basics/getting-started-tutorial/initialize-sentry-sdk-frontend/', + }, + { + source: '/product/sentry-basics/integrate-frontend/generate-first-error/', + destination: '/product/sentry-basics/getting-started-tutorial/generate-first-error/', + }, + { + source: '/product/sentry-basics/integrate-frontend/upload-source-maps/', + destination: '/product/sentry-basics/getting-started-tutorial/enable-readable-stack-traces/', + }, + { + source: '/product/sentry-basics/integrate-frontend/configure-scms/', + destination: '/integrations/source-code-mgmt/github/', + }, + { + source: '/product/sentry-basics/integrate-frontend/:path*', + destination: '/product/sentry-basics/getting-started-tutorial/', + }, + { + source: '/product/sentry-basics/integrate-backend/:path*', + destination: '/product/sentry-basics/getting-started-tutorial/', + }, + { + source: '/product/sentry-basics/distributed-tracing/:path*', + destination: '/product/sentry-basics/getting-started-tutorial/:path*', + }, { source: '/security-legal-pii/security/ai-ml-policy/', destination: '/security-legal-pii/security/service-data-usage/', diff --git a/src/components/featureInfo.tsx b/src/components/featureInfo.tsx index 1aee98e6af0d4b..b3125da16abfc4 100644 --- a/src/components/featureInfo.tsx +++ b/src/components/featureInfo.tsx @@ -33,11 +33,8 @@ const FEATURE_DATA: Record< Issues {' '} page and select an error from the issues list to view the full details and context - of this error. For more details, see this{' '} - - interactive walkthrough - - . + of this error. For more details, see the{' '} + Issue Details documentation. ), }, @@ -54,7 +51,7 @@ const FEATURE_DATA: Record< {' '} page and select a trace to reveal more information about each span, its duration, and any errors. For an interactive UI walkthrough, click{' '} - + here . diff --git a/src/components/tutorialProgress/index.tsx b/src/components/tutorialProgress/index.tsx new file mode 100644 index 00000000000000..141a20e3cb0448 --- /dev/null +++ b/src/components/tutorialProgress/index.tsx @@ -0,0 +1,67 @@ +import styles from './style.module.scss'; + +interface TutorialProgressProps { + /** The current step number (1-based). */ + step: number; + /** Total number of steps. @defaultValue 5 */ + total?: number; +} + +/** The bug that rides the tip of the fill. */ +function Bug() { + return ( + + + {/* antennae */} + + + {/* legs */} + + + + + + + + {/* head + body */} + + + + ); +} + +/** + * A slim progress bar for multi-page tutorials. Fills with Sentry purple in + * proportion to `step / total`, with a bug riding the tip of the fill. + */ +export function TutorialProgress({step, total = 5}: TutorialProgressProps) { + const clamped = Math.max(0, Math.min(step, total)); + const pct = total > 0 ? (clamped / total) * 100 : 0; + + return ( +
+
+
+ +
+
+
+ ); +} diff --git a/src/components/tutorialProgress/style.module.scss b/src/components/tutorialProgress/style.module.scss new file mode 100644 index 00000000000000..cf00f2ce3e7af0 --- /dev/null +++ b/src/components/tutorialProgress/style.module.scss @@ -0,0 +1,43 @@ +.wrap { + --sentry-purple: #6c5fc7; + margin: 0.25rem 0 2rem; +} + +.track { + position: relative; + height: 8px; + /* cap the bar at roughly a third of the content width */ + max-width: 33%; + border-radius: 9999px; + background: var(--gray-a4, #e7e7ee); + /* let the bug marker overflow above/below the track */ + overflow: visible; +} + +.fill { + position: relative; + height: 100%; + min-width: 8px; + border-radius: 9999px; + background: var(--sentry-purple); + transition: width 0.35s ease; +} + +.marker { + position: absolute; + right: 0; + top: 50%; + transform: translate(45%, -50%); + width: 24px; + height: 24px; + display: grid; + place-items: center; + color: var(--sentry-purple); + filter: drop-shadow(0 1px 2px rgb(0 0 0 / 0.18)); +} + +.marker svg { + width: 24px; + height: 24px; + display: block; +} diff --git a/src/mdxComponents.ts b/src/mdxComponents.ts index b0cc414fec2c1a..6b5a0659644c7c 100644 --- a/src/mdxComponents.ts +++ b/src/mdxComponents.ts @@ -66,6 +66,7 @@ import { import {StatusBadge} from './components/statusBadge'; import {StepComponent, StepConnector} from './components/stepConnector'; import {TableOfContents} from './components/tableOfContents'; +import {TutorialProgress} from './components/tutorialProgress'; import {VersionRequirement} from './components/version-requirement'; import {VimeoEmbed} from './components/video'; @@ -137,6 +138,7 @@ export function mdxComponents( StatusBadge, StepComponent, StepConnector, + TutorialProgress, VimeoEmbed, VersionRequirement, a: SmartLink,