Distributed Tracing with Uptime

Sentry's Uptime Monitoring uses distributed tracing to track the flow and timing of requests and operations during uptime checks. This helps you quickly find the root cause of downtime by connecting related errors and performance data.

When uptime checks are performed, Sentry creates a trace that shows the complete request lifecycle. This trace contains:

• Uptime request spans: A default set of root spans that identifies this as an uptime check
• Application spans: Individual operations like database queries, API calls, and cache operations, configured through distributed tracing
• Error events: Any exceptions or failures that occur during the request

Error tracing captures when things go wrong, while span tracing shows the performance and flow of operations. Together, they provide complete visibility into why an uptime check failed. Span tracing is disabled by default for uptime checks, but can be enabled by allowing sampling in your Uptime Alert settings. Errors plus spans focus on problems, while uptime monitoring plus spans focus on performance.

How Uptime Tracing Works

Sentry Uptime Tracing automatically appends a sentry-trace header to every outgoing request made to the configured URL in your Uptime Alert settings. This header propagates a trace identifier.

If one of Sentry's supported backend SDKs is configured for the application handling the incoming uptime check request, the trace will continue through your application. Learn more about how distributed tracing works.

Example Uptime check request:

GET /example-uptime-endpoint HTTP/1.1
Host: sentry.io
User-Agent: SentryUptimeBot/1.0 (+http://docs.sentry.io/product/uptime-monitoring/)
Sentry-Trace: 32d4011600324838afcd666edadc1d09-8d5ca7419a02ca36

Tracing Errors

Error tracing is enabled by default for uptime checks. When downtime is detected, an Uptime Issue is created. You can then go to Sentry's Trace Explorer page to view any related errors.

Because uptime requests won't override your SDK’s error sampling rate, some errors may not appear in traces if that rate is set to below 1.

import * as Sentry from "@sentry/node";

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0
example-org / example-project",
  // Filtering example for a Node.js Express app
  beforeSend(event) {
    const userAgent = event.request?.headers?.["user-agent"];

    // Ignore events captured in a request from SentryUptimeBot
    if (userAgent && userAgent.includes("SentryUptimeBot")) {
      return null;
    }

    // Process other events
    return event;
  },
});

Tracing Spans

There are two sets of spans avaialble for uptime checks:

1. Uptime request spans. These are automatically created by Sentry for every uptime check request. You can find them as the root of any uptime issue's trace.
2. Application spans. These are spans that are configured through distributed tracing. You can find them as the children of uptime request spans.

Unlike error tracing, span tracing that you configure is disabled by default for uptime checks, but can be enabled by allowing sampling in your Uptime Alert settings. Enabling span tracing can be helpful because it provides a detailed view of the timing and flow of requests and operations during uptime checks, which is especially useful for diagnosing timeouts or performance issues.

Enabling Uptime Tracing for Spans

To enable span tracing, modify your Uptime Alert settings with the "Allow Sampling" option. This will ensure that Sentry defers the sampling decision to your SDK, which will follow the trace sample rate you've configured.

Because uptime requests won't override your SDK’s error sampling rate, some errors may not appear in traces if that rate is set to below 1.

Custom Sampling

To ensure that all spans from uptime checks are sampled, even if your SDK's trace sampling rate is below 1, you can configure a sampling function. Here's an example:

import * as Sentry from "@sentry/node";

Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0
example-org / example-project",
  // Custom tracer function for a Node.js Express app
  tracesSampler: ({ name, attributes, parentSampled }) => {
    const userAgent = attributes?.["http.user_agent"];

    if (
      typeof userAgent === "string" &&
      userAgent.includes("SentryUptimeBot")
    ) {
      // Sample 100% of spans from SentryUptimeBot
      return 1;
    }

    // Sample 50% of other spans
    return 0.5;
  },
});

Billing Considerations

Errors and spans captured during uptime checks are billed as regular events in Sentry. Configure sampling thoughtfully to manage costs.