Sentry Getting Started: Set up Error & Performance Monitoring

Getting started overview

Integrating Sentry for error and performance monitoring involves a series of steps designed to quickly connect your application to the Sentry platform. The core process includes account creation, project setup, and SDK configuration. Sentry provides official SDKs for numerous languages and frameworks, streamlining the integration process by abstracting the direct interaction with the Sentry API.

Upon successful setup, Sentry captures unhandled exceptions, performance bottlenecks, and user session data, transmitting this information to your Sentry dashboard. This enables developers to monitor application health in real-time, triage issues, and access detailed context for debugging. The initial setup focuses on obtaining a Data Source Name (DSN), which is a public key used by the SDK to send events to Sentry.

The following table provides a quick reference for the initial setup:

Create an account and get keys

To begin using Sentry, you must first create an account. Sentry offers a Developer free tier suitable for individuals, which includes 5,000 errors, 10,000 transactions, and 100 sessions per month. Paid plans are available for teams, scaling with event volume.

1. Sign Up for a Sentry Account: Navigate to the Sentry sign-up page and follow the prompts to create your account. You can use an email address, or sign up with GitHub, Google, or Microsoft accounts.
2. Create Your First Project: After signing up, Sentry will guide you through creating your first project. A project represents a distinct application or service you wish to monitor. During this step, you will select the platform (e.g., Python, JavaScript, Node.js) that best matches your application's technology stack. This selection helps Sentry provide tailored SDK installation instructions. Detailed steps for creating a new project are available in the official documentation.
3. Obtain Your Data Source Name (DSN): Upon project creation, Sentry automatically generates a unique Data Source Name (DSN) for your project. The DSN is a URI that tells the Sentry SDK where to send event data. It includes the protocol, public key, and project ID. You can find your DSN within your Sentry dashboard by navigating to Settings > Projects > [Your Project Name] > Client Keys (DSN). Keep this DSN secure, as it's essential for configuring your Sentry SDK. The DSN structure is typically {PROTOCOL}://{PUBLIC_KEY}@{HOST}/{PATH}{PROJECT_ID}, as described in the Sentry DSN documentation.

Your first request

Once you have your DSN, the next step involves integrating the Sentry SDK into your application and sending a test event. The process varies slightly depending on your chosen programming language or framework.

Example: JavaScript (Node.js)

For a Node.js application, the general steps involve installing the Sentry SDK and initializing it with your DSN.

1. Install the SDK: Open your project's terminal and install the Sentry Node.js SDK using npm or yarn:

   npm install @sentry/node @sentry/integrations
   # or
   yarn add @sentry/node @sentry/integrations

2. Initialize the SDK: In your application's entry file (e.g., app.js or index.js), import and initialize Sentry with your DSN. Replace YOUR_DSN_HERE with the DSN you obtained from your Sentry project settings.

const Sentry = require('@sentry/node');
const Tracing = require('@sentry/tracing');

Sentry.init({
  dsn: "YOUR_DSN_HERE",
  integrations: [
    // enable HTTP calls tracing
    new Sentry.Integrations.Http({
      tracing: true
    }),
    // enable Express.js middleware tracing
    new Tracing.Integrations.Express({
      app: require('express')()
    }),
  ],

  // Set tracesSampleRate to 1.0 to capture 100% of transactions for performance monitoring.
  // We recommend adjusting this value in production.
  tracesSampleRate: 1.0,
});

// Optional: Add a request handler to automatically capture errors for incoming requests
// Sentry.Handlers.requestHandler() must be the first middleware on the app
// Sentry.Handlers.errorHandler() must be before any other error middleware
const app = require('express')();
app.use(Sentry.Handlers.requestHandler());
app.use(Sentry.Handlers.errorHandler());

3. Send a Test Error: To verify your integration, intentionally throw an error in your application. This error should be captured by the Sentry SDK and sent to your Sentry dashboard.

app.get('/debug-sentry', function mainHandler(req, res) {
  throw new Error('My first Sentry error!');
});

app.listen(3000, () => {
  console.log('Server started on port 3000');
});

After running this code and accessing /debug-sentry in your browser (e.g., http://localhost:3000/debug-sentry), navigate to your Sentry dashboard. You should see an event corresponding to "My first Sentry error!" listed under your project. This confirms that the SDK is correctly configured and communicating with the Sentry service. More specific setup instructions for Node.js are available in the Sentry Node.js documentation.

Example: Python (Django)

For a Django application, the integration involves installing the Sentry Python SDK and configuring it within your Django settings.

1. Install the SDK: In your Django project's virtual environment, install the Sentry Python SDK:

   pip install sentry-sdk django-sentry-lib

2. Configure Django Settings: Add sentry_sdk to your INSTALLED_APPS and configure Sentry in your settings.py file. Replace YOUR_DSN_HERE with your project's DSN.

import sentry_sdk
from sentry_sdk.integrations.django import DjangoIntegration

sentry_sdk.init(
    dsn="YOUR_DSN_HERE",
    integrations=[
        DjangoIntegration(),
    ],

    # Set traces_sample_rate to 1.0 to capture 100% of transactions for performance monitoring.
    # We recommend adjusting this value in production.
    traces_sample_rate=1.0,

    # If you're using a load balancer or proxy that strips headers,
    # you may need to set environment variables or use a different IP address configuration.
    # For details, refer to the Sentry documentation on proxy settings.
)

INSTALLED_APPS = [
    # ... other apps ...
    'sentry_sdk',
]

3. Send a Test Error: To confirm the integration, you can raise an exception within a Django view.

# In your apps/views.py
from django.http import HttpResponse

def error_test(request):
    1 / 0  # This will raise a ZeroDivisionError
    return HttpResponse("This should not be reached.")

Map this view to a URL in your urls.py, then access that URL in your browser. A ZeroDivisionError will occur, and Sentry will capture it. Check your Sentry dashboard for the new error event. More detailed instructions for Django are available in the Sentry Django documentation.

Common next steps

After successfully sending your first test event, consider the following steps to maximize Sentry's value:

• Configure Performance Monitoring: Beyond error tracking, Sentry offers robust performance monitoring. SDKs typically include integrations for common web frameworks and databases to automatically capture transaction data, identifying slow endpoints, database queries, and other performance bottlenecks. Adjust tracesSampleRate to control the percentage of transactions sampled. Refer to the Sentry Performance Monitoring guide for platform-specific details.
• Set Up Session Replay: For web applications (JavaScript), integrate Session Replay to visualize user interactions leading up to an error or performance issue. This provides valuable context by showing exactly what a user experienced, including clicks, scrolls, and network requests. The Sentry Session Replay documentation provides setup instructions.
• Integrate with Version Control and Issue Trackers: Connect Sentry with your version control system (e.g., GitHub, GitLab) and issue trackers (e.g., Jira, Notion). This allows Sentry to automatically suggest code owners, link errors to relevant commits, and create new issues directly from the Sentry dashboard. Consult the Sentry Integrations page for a list of supported services and configuration guides.
• Configure Alerts: Define custom alert rules based on error frequency, new errors, or performance thresholds. Sentry can send notifications via email, Slack, PagerDuty, or other services, ensuring your team is promptly informed of critical issues. Learn more about Sentry Alerts and Notifications.
• Understand Data Scrubber and Filtering: To protect sensitive information, Sentry provides mechanisms for data scrubbing and filtering. Configure your SDK or project settings to prevent sensitive data (e.g., personally identifiable information, API keys) from being sent to Sentry. This is a crucial step for compliance with regulations like GDPR, which is a key consideration for many developers, as outlined by sources such as the Google Developers Privacy Guide.

Troubleshooting the first call

If your first test event doesn't appear in the Sentry dashboard, consider these common troubleshooting steps:

• Verify DSN Correctness: Double-check that the DSN configured in your application code precisely matches the DSN in your Sentry project settings. A common mistake is a typo or an incorrect protocol (http vs. https).
• Check Network Connectivity: Ensure your application server has outbound network access to sentry.io (or your self-hosted Sentry instance). Firewalls or proxy servers can block connections. If you're behind a proxy, consult your SDK's documentation for proxy configuration (e.g., setting HTTP_PROXY environment variables).
• Inspect SDK Logs: Most Sentry SDKs offer verbose logging options that can provide insights into why an event might not be sent. Enable debug logging in your SDK configuration (e.g., debug: true for JavaScript, init(debug=True) for Python) and check your application's logs for any Sentry-related errors or warnings.
• Review Project Quotas: While on a free tier, you might hit event quotas. Check your Sentry dashboard's usage statistics (Settings > Usage & Billing) to ensure you haven't exceeded your allocated error, transaction, or session limits for the current billing period.
• Confirm Event Context: Ensure the error you're trying to capture is unhandled. If you're catching and gracefully handling an exception without re-raising it or explicitly calling Sentry.captureException(), Sentry's automatic error capturing might not trigger.
• Check Ad Blockers or Browser Extensions: For front-end JavaScript applications, browser extensions like ad blockers can sometimes interfere with Sentry's network requests. Test in an incognito window or with extensions disabled.
• Consult Sentry Status Page: Occasionally, Sentry services might experience disruptions. Check the Sentry Status Page to see if there are any ongoing incidents affecting their platform.