Skip to content

Commit b6290f7

Browse files
coolguyzoneAlex KrawiecAlex KrawiecAlex Krawieclizokm
authored
Distrubited Tracing Tutorial (#11518)
* First stab at creating an outline and some structure for tracing walkthrough * Content updates to tracing walkthrough * Start scaffolding first tracing error * Flesh out generating first error doc * Add arcade and more progress on generating first error * Clean up language and objectives on index page of tracing tutorial * Update links and make minor copy edits * Update urls for github sample projects * Fix Sentry code for frontend * Update frontend terminal success message sample * Fix some formatting errors * Make error log in initialize-sentry-sdk-backend more descriptive * Update docs/product/sentry-basics/distributed-tracing/create-new-project.mdx Co-authored-by: Liza Mock <[email protected]> * Update docs/product/sentry-basics/distributed-tracing/create-new-project.mdx Co-authored-by: Liza Mock <[email protected]> * Update docs/product/sentry-basics/distributed-tracing/index.mdx Co-authored-by: Liza Mock <[email protected]> * Update docs/product/sentry-basics/distributed-tracing/index.mdx Co-authored-by: Liza Mock <[email protected]> * Update docs/product/sentry-basics/distributed-tracing/index.mdx Co-authored-by: Liza Mock <[email protected]> * Update docs/product/sentry-basics/distributed-tracing/index.mdx Co-authored-by: Liza Mock <[email protected]> * Update docs/product/sentry-basics/distributed-tracing/initialize-sentry-sdk-backend.mdx Co-authored-by: Liza Mock <[email protected]> * Update docs/product/sentry-basics/distributed-tracing/initialize-sentry-sdk-backend.mdx Co-authored-by: Liza Mock <[email protected]> * Update docs/product/sentry-basics/distributed-tracing/initialize-sentry-sdk-frontend.mdx Co-authored-by: Liza Mock <[email protected]> * Add minor copy edits * Add code highlighting where needed * Add frontend screenshot to initialize-sentry-frontend * Update arcade in tracing create-new-project * Update docs/product/sentry-basics/distributed-tracing/initialize-sentry-sdk-frontend.mdx Co-authored-by: Liza Mock <[email protected]> * Update docs/product/sentry-basics/distributed-tracing/initialize-sentry-sdk-backend.mdx Co-authored-by: Liza Mock <[email protected]> * Update docs/product/sentry-basics/distributed-tracing/initialize-sentry-sdk-backend.mdx Co-authored-by: Liza Mock <[email protected]> * Update docs/product/sentry-basics/distributed-tracing/initialize-sentry-sdk-frontend.mdx Co-authored-by: Liza Mock <[email protected]> * Update docs/product/sentry-basics/distributed-tracing/generate-first-error.mdx Co-authored-by: Liza Mock <[email protected]> * Update docs/product/sentry-basics/distributed-tracing/generate-first-error.mdx Co-authored-by: Liza Mock <[email protected]> * Update docs/product/sentry-basics/distributed-tracing/generate-first-error.mdx Co-authored-by: Liza Mock <[email protected]> * Update docs/product/sentry-basics/distributed-tracing/generate-first-error.mdx Co-authored-by: Liza Mock <[email protected]> * Update docs/product/sentry-basics/distributed-tracing/generate-first-error.mdx Co-authored-by: Liza Mock <[email protected]> * Suggested edits for tracing tutorial (#11660) * Make tech stack clearer earlier in text * Split long paragraph * Remove text that probably makes no sense if you are a first time user * Explain DSN in context of the screen a user is currently on * It is clearer in one sentence * Put instructions in corre t order * Move comment * Add new bullet point for importing instrument into server.js * Looks clearer as a diff * Depending on user preferences in their IDE, this might not be line 88, e.g. line length settings * Fix typo * Update todos and various small copy changes, format w/ prettier --------- Co-authored-by: Alex Krawiec <[email protected]> Co-authored-by: Alex Krawiec <[email protected]> Co-authored-by: Alex Krawiec <[email protected]> Co-authored-by: Liza Mock <[email protected]> Co-authored-by: Salma Alam-Naylor <[email protected]>
1 parent 3f8c511 commit b6290f7

File tree

6 files changed

+538
-0
lines changed

6 files changed

+538
-0
lines changed

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

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
---
2+
title: Create Frontend and Backend Sentry Projects
3+
sidebar_order: 2
4+
description: "Learn how to create your Sentry projects, which will scope events to distinct pieces of your application landscape."
5+
---
6+
7+
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.
8+
9+
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).
10+
11+
## Create a Frontend Project
12+
13+
Follow the steps below to create a new Sentry project for a sample React application:
14+
15+
1. Log in to your [Sentry organization](https://sentry.io).
16+
17+
1. Select **Projects** from the left side navigation menu.
18+
19+
1. Click "Create Project" and configure it as appropriate for your application:
20+
21+
- **Choose your platform**: Select the language or framework for your project based on the code you wish to monitor. In this case, choose **React**.
22+
23+
- **Set your alert frequency**: For the purpose of this tutorial, select **Alert me on high priority issues**.
24+
25+
> If you're wary of alert fatigue, learn more about how to set up your alerts in [Alerts Best Practices](/product/alerts/best-practices/).
26+
27+
- **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).
28+
29+
- 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.
30+
31+
- 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 > Client Keys (DSN)**
32+
33+
1. Click **Take me to Issues** to go to your new project's **Issues** page.
34+
35+
### UI Walkthrough
36+
37+
The interactive demo below walks through how to create a new project in the UI.
38+
39+
<div
40+
style={{
41+
height: "0px",
42+
paddingBottom: "calc(56.88524590163935% + 41px)",
43+
position: "relative",
44+
width: "100%",
45+
}}
46+
>
47+
<iframe
48+
src="https://demo.arcade.software/4z9l5xNZfpXFGAFc03az?embed"
49+
frameborder="0"
50+
loading="lazy"
51+
webkitallowfullscreen
52+
mozallowfullscreen
53+
allowfullscreen
54+
allow="fullscreen;"
55+
style={{
56+
colorScheme: "light",
57+
height: "100%",
58+
left: "0px",
59+
position: "absolute",
60+
top: "0px",
61+
width: "100%",
62+
}}
63+
title="FE Tutorial -> Create Project"
64+
></iframe>
65+
</div>
66+
67+
## Create a Backend Project
68+
69+
Next, follow the steps below to create a new Sentry project for a sample Backend application:
70+
71+
1. Log in to your [Sentry organization](https://sentry.io).
72+
73+
1. Select **Projects** from the left side navigation menu to display the list of all your projects.
74+
75+
1. Click "Create Project" and configure it as appropriate for your application:
76+
77+
- **Choose your platform**: In this case, choose **Express**.
78+
79+
- **Set your alert frequency**: Once again, select **Alert me on high priority issues**.
80+
81+
- **Name your project and assign it a team**: Make sure to give it a different project name than your frontend application.
82+
83+
- Click **Create Project**. This takes you to the quick Configure Express SDK guide, which provides an overview of how to configure the SDK.
84+
85+
1. Copy the DSN key and keep it handy.
86+
87+
> You can also find a project's DSN anytime in **[Project] > Settings > Client Keys (DSN)**.
88+
89+
1. Click **Take me to Issues** to go to your new project's **Issues** page.
90+
91+
### UI Walkthrough
92+
93+
<div
94+
style={{
95+
height: "0px",
96+
paddingBottom: "calc(56.88524590163935% + 41px)",
97+
position: "relative",
98+
width: "100%",
99+
}}
100+
>
101+
<iframe
102+
src="https://demo.arcade.software/YXX8LAOHGSP4mWWBMMtM?embed"
103+
frameborder="0"
104+
loading="lazy"
105+
webkitallowfullscreen
106+
mozallowfullscreen
107+
allowfullscreen
108+
allow="fullscreen;"
109+
style={{
110+
colorScheme: "light",
111+
height: "100%",
112+
left: "0px",
113+
position: "absolute",
114+
top: "0px",
115+
width: "100%",
116+
}}
117+
title="Tracing Tutorial -> Create Express Project"
118+
></iframe>
119+
</div>
120+
121+
## Next
122+
123+
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‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
---
2+
title: Capture Your First Distributed Tracing Error
3+
sidebar_order: 5
4+
description: "Learn how to capture your first error and view it in Sentry."
5+
---
6+
7+
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).
8+
9+
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.
10+
11+
## 1. Trigger an Error
12+
13+
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.
14+
15+
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.
16+
17+
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`.
18+
19+
```jsx diff {filename:App.js}
20+
<div className="btn-parent">
21+
<button className="btn" onClick={() => getProduct("clown-shoes")}>
22+
Clown Shoes
23+
</button>
24+
</div>
25+
<div className="btn-parent">
26+
- <button className="btn" onClick={() => getProduct("nonfat-water")}>
27+
+ <button className="btn" onClick={() => getProduct("debug-sentry")}>
28+
Nonfat Water
29+
</button>
30+
</div>
31+
```
32+
33+
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:
34+
35+
```javascript {filename:server.js}
36+
app.get("/products/debug-sentry", (req, res) => {
37+
console.log("Sentry Error thrown!");
38+
throw new Error("My first Sentry error!");
39+
});
40+
```
41+
42+
1. Save the file.
43+
44+
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.
45+
46+
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:
47+
48+
```bash
49+
Sentry Error thrown!
50+
```
51+
52+
This confirms that the error we just produced on the frontend has triggered a corresponding error on the backend.
53+
54+
## 2. View the Error in Sentry
55+
56+
Now that you've triggered an error, let's see what it looks like in Sentry.
57+
58+
1. Open the [**Traces**](https://sentry.io/orgredirect/organizations/:orgslug/traces/) page in Sentry.io. Make sure one (or both) of the projects you're using for this tutorial is selected in the projects dropdown.
59+
60+
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.
61+
62+
3. On the [Trace View](/concepts/key-terms/tracing/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.
63+
64+
### UI Walkthrough
65+
66+
The interactive demo below walks through how to view a distributed trace in Sentry.
67+
68+
<div
69+
style={{
70+
height: "0px",
71+
paddingBottom: "calc(52.1021021021021% + 41px)",
72+
position: "relative",
73+
width: "100%",
74+
}}
75+
>
76+
<iframe
77+
src="https://demo.arcade.software/xPc1a1WUYTnQqPvBQGnQ?embed"
78+
frameborder="0"
79+
loading="lazy"
80+
webkitallowfullscreen
81+
mozallowfullscreen
82+
allowfullscreen
83+
allow="fullscreen;"
84+
style={{
85+
colorScheme: "light",
86+
height: "100%",
87+
left: "0px",
88+
position: "absolute",
89+
top: "0px",
90+
width: "100%",
91+
}}
92+
title="FE Tutorial - View First Error"
93+
></iframe>
94+
</div>
95+
96+
## Next
97+
98+
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.

‎docs/product/sentry-basics/distributed-tracing/img/frontend-screenshot.png‎

217 KB
Loading

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

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
title: Distributed Tracing Tutorial
3+
sidebar_order: 1
4+
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."
5+
---
6+
7+
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:
8+
9+
- Configure the Sentry SDK on a sample React and Node/Express app.
10+
- Trigger a sample front-end error that in turn triggers a sample back-end error.
11+
- Go to the [Traces](https://sentry.io/orgredirect/organizations/:orgslug/traces/) page in Sentry and see a detailed view of your entire trace.
12+
13+
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.
14+
15+
## Prerequisites
16+
17+
- A [Sentry](https://sentry.io) account, or [sign up](https://sentry.io/signup/) for one
18+
- A [GitHub](https://github.com/) account, or [sign up](https://github.com/join) for one
19+
- [Node 18+](https://nodejs.org/en/download/)
20+
21+
## Next
22+
23+
[Create your Sentry Projects](/product/sentry-basics/distributed-tracing/create-new-project/)

0 commit comments

Comments
 (0)