# Koa | Sentry for Koa

This guide explains how to set up Sentry in your Koa application.

## [Prerequisites](https://docs.sentry.io/.md#prerequisites)

You need:

* A Sentry [account](https://sentry.io/signup.md) and [project](https://docs.sentry.io/product/projects.md)
* Your application up and running

## [Step 1: Install](https://docs.sentry.io/.md#step-1-install)

Choose the features you want to configure, and this guide will show you how:

Error Monitoring\[ ]Tracing\[ ]Profiling\[ ]Logs (Beta)

Want to learn more about these features?

* [**Issues**](https://docs.sentry.io/product/issues.md) (always enabled): Sentry's core error monitoring product that automatically reports errors, uncaught exceptions, and unhandled rejections. If you have something that looks like an exception, Sentry can capture it.
* [**Tracing**](https://docs.sentry.io/product/tracing.md): Track software performance while seeing the impact of errors across multiple systems. For example, distributed tracing allows you to follow a request from the frontend to the backend and back.
* [**Profiling**](https://docs.sentry.io/product/explore/profiling.md): Gain deeper insight than traditional tracing without custom instrumentation, letting you discover slow-to-execute or resource-intensive functions in your app.

### [Install the Sentry SDK](https://docs.sentry.io/.md#install-the-sentry-sdk)

Run the command for your preferred package manager to add the Sentry SDK to your application:

```bash
npm install @sentry/node
```

```bash
npm install @sentry/node @sentry/profiling-node --save
```

## [Step 2: Configure](https://docs.sentry.io/.md#step-2-configure)

### [Initialize the Sentry SDK](https://docs.sentry.io/.md#initialize-the-sentry-sdk)

To import and initialize Sentry, create a file named `instrument.(js|mjs)` in the root directory of your project and add the following code:

`instrument.js`

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

// Ensure to call this before requiring any other modules!
Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",

  // Adds request headers and IP for users, for more info visit:
  // https://docs.sentry.io/platforms/javascript/guides/node/configuration/options/#sendDefaultPii
  sendDefaultPii: true,
  //  profiling

  integrations: [
    // Add our Profiling integration
    nodeProfilingIntegration(),
  ],
  //  profiling
  //  performance

  // Set tracesSampleRate to 1.0 to capture 100%
  // of transactions for tracing.
  // We recommend adjusting this value in production
  // Learn more at
  // https://docs.sentry.io/platforms/javascript/guides/node/configuration/options/#tracesSampleRate
  tracesSampleRate: 1.0,
  //  performance
  //  profiling

  // Set profilesSampleRate to 1.0 to profile 100%
  // of sampled transactions.
  // This is relative to tracesSampleRate
  // Learn more at
  // https://docs.sentry.io/platforms/javascript/guides/node/configuration/options/#profilesSampleRate
  profilesSampleRate: 1.0,
  //  profiling
  //  logs

  // Enable logs to be sent to Sentry
  _experiments: { enableLogs: true },
  //  logs
});
```

### [Apply Instrumentation to Your App](https://docs.sentry.io/.md#apply-instrumentation-to-your-app)

Make sure to initialize Sentry before you require or import any other modules in your app. Otherwise, auto-instrumentation won't work for these modules.

##### Which module system are you using?

The method for applying instrumentation depends on whether your application uses CommonJS (CJS) or ECMAScript Modules (ESM). If you're unsure which system you're using or if you're looking for alternative installation methods, see [here](https://docs.sentry.io/platforms/javascript/guides/koa/install.md).

#### [CommonJS](https://docs.sentry.io/.md#commonjs)

Require the `instrument.js` file before any other modules:

```javascript
// Require this first!
require("./instrument");

// Now require other modules
const Koa = require("koa");
const Sentry = require("@sentry/node");

const app = new Koa();

Sentry.setupKoaErrorHandler(app);

// Add your routes, etc.

app.listen(3030);
```

#### [ESM](https://docs.sentry.io/.md#esm)

When running your application in ESM mode, use the [--import](https://nodejs.org/api/cli.html#--importmodule) command line option and point it to `instrument.mjs` to load the module before the application starts:

```bash
# Note: This is only available for Node v18.19.0 onwards.
node --import ./instrument.mjs app.mjs
```

## [Step 3: Add Readable Stack Traces With Source Maps (Optional)](https://docs.sentry.io/.md#step-3-add-readable-stack-traces-with-source-maps-optional)

The stack traces in your Sentry errors probably won't look like your actual code. To fix this, upload your source maps to Sentry. The easiest way to do this is by using the Sentry Wizard:

```bash
npx @sentry/wizard@latest -i sourcemaps
```

## [Step 4: Verify Your Setup](https://docs.sentry.io/.md#step-4-verify-your-setup)

Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project.

```javascript
router.get("/debug-sentry", function () {
  throw new Error("My first Sentry error!");
});
```

### [View Captured Data in Sentry](https://docs.sentry.io/.md#view-captured-data-in-sentry)

Now, head over to your project on [Sentry.io](https://sentry.io/.md) to view the collected data (it takes a couple of moments for the data to appear).

Need help locating the captured errors in your Sentry project?

1. Open the [**Issues**](https://sentry.io/orgredirect/organizations/:orgslug/issues.md) page and select an error from the issues list to view the full details and context of this error. For an interactive UI walkthrough, click [here](https://docs.sentry.io/product/sentry-basics/integrate-frontend/generate-first-error.md#ui-walkthrough).
2. Open the [**Traces**](https://sentry.io/orgredirect/organizations/:orgslug/traces.md) page and select a trace to reveal more information about each span, its duration, and any errors. For an interactive UI walkthrough, click [here](https://docs.sentry.io/product/sentry-basics/distributed-tracing/generate-first-error.md#ui-walkthrough).
3. Open the [**Profiles**](https://sentry.io/orgredirect/organizations/:orgslug/profiling.md) page, select a transaction, and then a profile ID to view its flame graph. For more information, click [here](https://docs.sentry.io/product/explore/profiling/profile-details.md).

## [Next Steps](https://docs.sentry.io/.md#next-steps)

At this point, you should have integrated Sentry into your Node.js application and should already be sending data to your Sentry project.

Now's a good time to customize your setup and look into more advanced topics. Our next recommended steps for you are:

* Extend Sentry to your frontend using one of our [frontend SDKs](https://docs.sentry.io/.md)
* Learn how to [manually capture errors](https://docs.sentry.io/platforms/javascript/guides/node/usage.md)
* Continue to [customize your configuration](https://docs.sentry.io/platforms/javascript/guides/node/configuration.md)
* Get familiar with [Sentry's product features](https://docs.sentry.io/product.md) like tracing, insights, and alerts

Are you having problems setting up the SDK?

* Check out alternative [installation methods](https://docs.sentry.io/platforms/javascript/guides/koa/install.md)
* Find various topics in [Troubleshooting](https://docs.sentry.io/platforms/javascript/guides/koa/troubleshooting.md)
* [Get support](https://sentry.zendesk.com/hc/en-us.md)
