Distrubited Tracing Tutorial

docs/product/sentry-basics/distributed-tracing/create-new-project.mdx

@@ -0,0 +1,98 @@
+---
+title: Create Frontend and Backend Sentry Projects
+sidebar_order: 2
+description: "Learn how to create your Sentry projects, which will scope events to distinct pieces of your application landscape."
+---
+
+This section walks you through how to create new projects in your Sentry account. You need to have a project set up in Sentry in order to capture errors and other events. In this walkthrough we'll be creating a frontend project in React as well as a separate backend project in Express/Node.
+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).
+
+## Create a Frontend 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 Best Practices](/product/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.
+
+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 **[Project] > Settings > Client Keys (DSN)**.
+
+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.
+
+<div style={{"height":"0px","paddingBottom":"calc(56.88524590163935% + 41px)","position":"relative","width":"100%"}}>
+  <iframe
+    src="https://demo.arcade.software/4z9l5xNZfpXFGAFc03az?embed"
+    frameborder="0"
+    loading="lazy"
+    webkitallowfullscreen
+    mozallowfullscreen
+    allowfullscreen
+    allow="fullscreen;"
+    style={{"colorScheme":"light","height":"100%","left":"0px","position":"absolute","top":"0px","width":"100%"}}
+    title="FE Tutorial -> Create Project"
+  ></iframe>
+</div>
+
+## 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.
+
+1. Click "Create Project" and configure it as appropriate for your application:
+
+    - **Choose your platform**: In this case, choose **Express**.
+
+    - **Set your alert frequency**: Once again, select **Alert me on high priority issues**.
+
+    - **Name your project and assign it a team**: Make sure to give it a different project name than your frontend application.
+
+    - Click **Create Project**. This takes you to the quick Configure Express SDK guide, which provides an overview of how to configure the SDK.
+
+1. Copy the DSN key and keep it handy.
+
+   > You can also find a project's DSN anytime in **[Project] > Settings > Client Keys (DSN)**.
+
+1. Click **Take me to Issues** to go to your new project's **Issues** page.
+
+### UI Walkthrough
+
+<div style={{"height":"0px","paddingBottom":"calc(56.88524590163935% + 41px)","position":"relative","width":"100%"}}>
+  <iframe
+    src="https://demo.arcade.software/YXX8LAOHGSP4mWWBMMtM?embed"
+    frameborder="0"
+    loading="lazy"
+    webkitallowfullscreen
+    mozallowfullscreen
+    allowfullscreen
+    allow="fullscreen;"
+    style={{"colorScheme":"light","height":"100%","left":"0px","position":"absolute","top":"0px","width":"100%"}}
+    title="Tracing Tutorial -> Create Express Project"
+  ></iframe>
+</div>
+
+
+
+## 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/).

docs/product/sentry-basics/distributed-tracing/generate-first-error.mdx

@@ -0,0 +1,84 @@
+---
+title: Capture Your First Distributed Tracing Error
+sidebar_order: 5
+description: "Learn how to capture your first error and view it in Sentry."
+---
+
+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. When you click on any of the product buttons, this 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.
+
+## 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. 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 {filename:App.js} {7}
+    <div className="btn-parent">
+        <button className="btn" onClick={() => getProduct("clown-shoes")}>
+            Clown Shoes
+        </button>
+    </div>
+    <div className="btn-parent">
+        <button className="btn" onClick={() => getProduct("debug-sentry")}>
+        Nonfat Water
+       </button>
+    </div>
+```
+Take note that in the `server.js` file of the `tracing-tutorial-backend` repo, there is a middleware function handling the `/products/debug-sentry` route, which throws a sample error:
+
+```javascript {filename:server.js}
+app.get("/products/debug-sentry", (req, res) => {
+    console.log('Sentry Error thrown!');
+    throw new Error("My first Sentry error!");
+  });
+```
+
+
+
+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 text saying something went wrong.  If you look at line 88 of the `App.js` file in the `tracing-tutorial-frontend` repo, you'll see this is what the frontend displays when it's call to the backend doesn't return any data.
+
+1. Open the terminal window that's running the `tracing-tutorial-backend` server. Here, you'll see that a log letting you know that an error has occurred.
+
+```bash
+Sentry Error thrown!
+```
+
+
+
+## 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 **Traces** page in [Sentry.io](https://sentry.io/). Make sure one (or both) of the projects you are using here is selected in the projects dropdown.
+
+2. You should see a trace that shows both the React and Express icons, indicating that this trace traverses both projects. Click on the blue trace ID on the left to see the Trace View.
+
+3. On the Trace View page, you can see every span that happened within this trace. You can see the error on the React app that directly triggered the error on the Express app.
+
+### UI Walkthrough
+
+The interactive demo below walks through how to view a distributed trace in Sentry.
+
+<div style={{"height":"0px","paddingBottom":"calc(52.1021021021021% + 41px)","position":"relative","width":"100%"}}>
+  <iframe
+    src="https://demo.arcade.software/xPc1a1WUYTnQqPvBQGnQ?embed"
+    frameborder="0"
+    loading="lazy"
+    webkitallowfullscreen
+    mozallowfullscreen
+    allowfullscreen
+    allow="fullscreen;"
+    style={{"colorScheme":"light","height":"100%","left":"0px","position":"absolute","top":"0px","width":"100%"}}
+    title="FE Tutorial - View First Error"
+  ></iframe>
+</div>
+
+## Next
+
+At this point, you've verified that Sentry is providing distributed tracing across your projects. You can now dig in to issues to easily find the original source of the issue, so you can diagnose and fix it in less time.

docs/product/sentry-basics/distributed-tracing/index.mdx

@@ -0,0 +1,23 @@
+---
+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 and backend 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 [Node/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 Node/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/)

docs/product/sentry-basics/distributed-tracing/initialize-sentry-sdk-backend.mdx

@@ -0,0 +1,176 @@
+---
+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/integrate-frontend/generate-first-error/).
+{/* TODO: UPDATE THIS LINK */}
+
+## 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 [email protected]:<your_username>/frontend-tutorial.git
+   ```
+   {/* TODO: UPDATE NAME OF THIS REPO */}
+
+1. Open the `tracing-tutorial-backend` project in your preferred code editor.
+   {/* TODO: UPDATE NAME OF THIS REPO */}
+
+## 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. Install the Sentry Express SDK using NPM.
+
+   Make sure you're in the `tracing-tutorial-backend` project folder.
+      {/* TODO: UPDATE NAME OF THIS REPO */}
+
+
+   ```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. Import and initialize the SDK.
+
+   Create a file at the root level of your project and call it `instrument.js`
+
+    ```javascript {filename:instrument.js}
+   const Sentry = require("@sentry/node");
+   const { nodeProfilingIntegration } = require("@sentry/profiling-node");
+
+   Sentry.init({
+    dsn: "sample_DSN_key",
+    integrations: [
+        nodeProfilingIntegration(),
+    ],
+   // Tracing
+   tracesSampleRate: 1.0,
+   //  Capture 100% of the transactions
+
+   // 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 configuring Sentry on your frontend project. Your frontend and backend projects should each have a unique DSN.
+
+   ```javascript {filename:instrument.js}
+   Sentry.init({
+     dsn: "<your_DSN_key>",
+     // ...
+   });
+   ```
+
+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](will add link later) and [Session Replay](/platforms/javascript/guides/react/session-replay) features.
+
+Be sure to 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 {filename:server.js} {1-7, 26-36}
+    // 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('<h1>Hello, Express.js Server here!</h1>');
+    });
+
+    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. 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:3001/](http://localhost:3001/) or the URL output in your terminal in the last step.
+
+
+
+## Next
+
+At this point, you 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.