Skip to content

Commit 2f54648

Browse files
Alex KrawiecAlex Krawiec
Alex Krawiec
authored and
Alex Krawiec
committed
First stab at creating an outline and some structure for tracing walkthrough
1 parent c850177 commit 2f54648

File tree

5 files changed

+410
-0
lines changed

5 files changed

+410
-0
lines changed

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

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
---
2+
title: Create a Sentry Project
3+
sidebar_order: 1
4+
description: "Learn how to create a Sentry project, which scopes events to a distinct piece of your application landscape."
5+
---
6+
7+
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. In this walkthrough we will be creating a frontend project in React as well as a separate backend project in Express/Node.
8+
9+
_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).
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 to display the list of all your projects.
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 every new issue**.
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+
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.
32+
33+
> You can also find a project's DSN anytime in **[Project] > Settings > Client Keys (DSN)**.
34+
35+
1. Click **Take me to Issues** to go to your new project's **Issues** page.
36+
37+
### UI Walkthrough
38+
{/* UPDATE THIS WITH YOUR OWN ARCADE */}
39+
40+
The interactive demo below walks through how to create a new project in the UI.
41+
42+
<div style={{"height":"0px","paddingBottom":"calc(56.88524590163935% + 41px)","position":"relative","width":"100%"}}>
43+
<iframe
44+
src="https://demo.arcade.software/IUuJGLUBdRIa2yBFE35v?embed"
45+
frameborder="0"
46+
loading="lazy"
47+
webkitallowfullscreen
48+
mozallowfullscreen
49+
allowfullscreen
50+
allow="fullscreen;"
51+
style={{"colorScheme":"light","height":"100%","left":"0px","position":"absolute","top":"0px","width":"100%"}}
52+
title="FE Tutorial -> Create Project"
53+
></iframe>
54+
</div>
55+
56+
## Create a Backend Project
57+
58+
Follow the steps below to create a new Sentry project for a sample Backend application:
59+
60+
1. Log in to your [Sentry organization](https://sentry.io).
61+
62+
1. Select **Projects** from the left side navigation menu to display the list of all your projects.
63+
64+
1. Click "Create Project" and configure it as appropriate for your application:
65+
66+
- **Choose your platform**: Select the language or framework for your project based on the code you wish to monitor. In this case, choose **Express**.
67+
68+
- **Set your alert frequency**: For the purpose of this tutorial, select **Alert me on high priority issues**.
69+
70+
> If you're wary of alert fatigue, learn more about how to set up your alerts in [Alerts Best Practices](/product/alerts/best-practices/).
71+
72+
- **Name your project and assign it a team**: Make sure to give it a different project name than your frontend application.
73+
74+
- Click **Create Project**. This takes you to the quick Configure Express SDK guide, which provides an overview of how to configure the SDK. This tutorial covers the SDK setup in more detail.
75+
76+
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.
77+
78+
> You can also find a project's DSN anytime in **[Project] > Settings > Client Keys (DSN)**.
79+
80+
1. Click **Take me to Issues** to go to your new project's **Issues** page.
81+
82+
83+
84+
## Next
85+
86+
Now that you have a Sentry project set up, you can [Add the Sentry SDK to Your Projects](/product/sentry-basics/integrate-frontend/initialize-sentry-sdk/).

‎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
3+
sidebar_order: 30
4+
description: "Follow this tutorial to set up Sentry for a sample fullstack JavaScript application. By the end, you'll be able to use distributed tracing."
5+
---
6+
7+
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 trace the source and impact of your issues across projects and platforms.
8+
9+
- x
10+
- x
11+
- x
12+
13+
This tutorial uses a [sample React application](https://github.com/getsentry/frontend-tutorial) on the frontend as well as a sample Node/Express API as the backend. Some familiarity with JavaScript will help you follow along, you can also follow along with the provided sample code or apply the same steps to your own project.
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 a Sentry Project](/product/sentry-basics/integrate-frontend/create-new-project/)

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

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
---
2+
title: Add the Sentry SDK to Your Backend Project
3+
sidebar_order: 2
4+
description: "Learn how to add the Sentry SDK to your backend codebase."
5+
---
6+
7+
This section walks you through how to import the sample application into your local development environment, add the Sentry SDK, and initialize it.
8+
9+
If you're using your own source code, you can skip this section. Instead:
10+
11+
- Select your [platform](/platforms/) and follow its **Getting Started** guide to add the Sentry SDK to your code.
12+
- Then, skip to the [next step](/guides/integrate-frontend/generate-first-error/).
13+
14+
## 1. Clone the Sample Application
15+
16+
The sample application is a basic backend application using Express and Node.
17+
18+
1. Fork the [sample application's repository](https://github.com/getsentry/frontend-tutorial) on GitHub.
19+
{/* TODO: ADD CUSTOM REPO HERE */}
20+
21+
1. Clone the forked repository to your local environment:
22+
23+
```bash
24+
git clone [email protected]:<your_username>/frontend-tutorial.git
25+
```
26+
27+
1. Open the `backend-tutorial` project in your preferred code editor.
28+
29+
## 2. Add the Sentry React SDK
30+
31+
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).
32+
33+
1. Install the Sentry React SDK using NPM.
34+
35+
Make sure you're in the `backend-tutorial` project folder.
36+
37+
```bash {tabTitle:npm}
38+
npm install --save @sentry/node @sentry/profiling-node
39+
```
40+
41+
```bash {tabTitle:yarn}
42+
yarn add @sentry/node @sentry/profiling-node
43+
```
44+
45+
```bash {tabTitle:pnpm}
46+
pnpm add @sentry/node @sentry/profiling-node
47+
```
48+
49+
1. Import and initialize the SDK.
50+
51+
Create a file at the root level of your project and call it `instrument.js`
52+
53+
```javascript {filename:instrument.js}
54+
const Sentry = require("@sentry/node");
55+
const { nodeProfilingIntegration } = require("@sentry/profiling-node");
56+
57+
Sentry.init({
58+
dsn: "sample_DSN_key",
59+
integrations: [
60+
nodeProfilingIntegration(),
61+
],
62+
// Tracing
63+
tracesSampleRate: 1.0,
64+
// Capture 100% of the transactions
65+
66+
// Set sampling rate for profiling - this is relative to tracesSampleRate
67+
profilesSampleRate: 1.0,
68+
});
69+
```
70+
71+
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.
72+
73+
1. Add your DSN key to the Sentry SDK configuration.
74+
75+
Paste in the DSN key value you copied from the project created in the [previous section](/product/sentry-basics/integrate-frontend/create-new-project/).
76+
{/* TODO: Update link here */}
77+
78+
```javascript {filename:instrument.js}
79+
Sentry.init({
80+
dsn: "<your_DSN_key>",
81+
// ...
82+
});
83+
```
84+
85+
1. Save the file.
86+
87+
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.
88+
89+
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.
90+
91+
Make sure to import `instrument.js` at the top of your `server.js` file, and set up the error handler after all controllers and before any other middleware:
92+
93+
``` javascript {filename:instrument.js}
94+
// IMPORTANT: Make sure to import `instrument.js` at the top of your file.
95+
// If you're using ECMAScript Modules (ESM) syntax, use `import "./instrument.js";`
96+
require("./instrument.js");
97+
98+
// All other imports below
99+
// Import with `import * as Sentry from "@sentry/node"` if you are using ESM
100+
const Sentry = require("@sentry/node");
101+
const express = require("express");
102+
const productsRoute = require('./routes/products');
103+
const cors = require('cors')
104+
105+
const app = express();
106+
107+
app.use(express.static('public'));
108+
app.use(cors());
109+
110+
app.get('/', (req, res) => {
111+
res.send('<h1>Hello, Express.js Server here!</h1>');
112+
});
113+
114+
// The error handler must be registered before any other error middleware and after all controllers
115+
Sentry.setupExpressErrorHandler(app);
116+
117+
// Optional fallthrough error handler
118+
app.use(function onError(err, req, res, next) {
119+
// The error id is attached to `res.sentry` to be returned
120+
// and optionally displayed to the user for support.
121+
console.log('500?');
122+
res.statusCode = 500;
123+
res.end(res.sentry + "\n");
124+
});
125+
126+
app.use('/products', productsRoute);
127+
128+
const port = 3001;
129+
130+
app.listen(port, () => {
131+
console.log(`Server is running on port`);
132+
});
133+
134+
```
135+
136+
## 3. Build and Run the Sample Application
137+
138+
In the `frontend-tutorial` project folder:
139+
140+
1. Install project dependencies.
141+
142+
```bash
143+
npm install
144+
```
145+
146+
1. Start the application in develop mode.
147+
148+
```bash
149+
npm start
150+
```
151+
152+
Once the application starts, you'll see a confirmation message similar to this one in your terminal:
153+
154+
```bash
155+
<i> [webpack-dev-server] Project is running at:
156+
<i> [webpack-dev-server] Loopback: http://localhost:3000/
157+
...
158+
webpack 5.87.0 compiled successfully in 1306 ms
159+
```
160+
161+
> **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`.
162+
163+
1. Open the sample application in your browser.
164+
165+
The sample app should be running at [http://localhost:3000/](http://localhost:3000/) or the URL output in your terminal in the last step.
166+
167+
![Sample app UX showing an online hardware store](./img/FE-tutorial-demo-app.png)
168+
169+
## Next
170+
171+
At this point, you have a sample React app running with the Sentry SDK initialized. Next, [Add the Sentry SDK to Your Backend Project](/product/sentry-basics/integrate-frontend/generate-first-error/) to start using Sentry's error monitoring feature.

0 commit comments

Comments
 (0)