What to Log

You've set up Sentry Logs. Now what? This guide covers the high-value logging patterns that help you debug faster and catch problems before users report them.

Anatomy of a Log

Every structured log follows the same format:

Sentry.logger.<level>(message, { attributes });

Logs in Sentry are automatically trace-connected. Each log shows a trace ID that links to the full trace view.

Sentry.logger.<level>(message)

Levels: trace, debug, info, warn (or warning in Python), error, fatal

Attributes: Key-value pairs you can search and filter on. Consistency matters, so use whatever naming convention fits your codebase.

Sentry.logger.info("Order completed", {
  orderId: "order_123",
  userId: user.id,
  amount: 149.99,
  paymentMethod: "stripe",
});

Logs in Sentry are automatically trace-connected. Each log shows a trace ID that links to the full trace view.

Where to Add Logs

Start with these five areas and you'll catch most issues before users do.

1. Authentication Events

Login flows are invisible until something breaks. Log successes and failures to spot patterns like brute force attempts, OAuth misconfigurations, or MFA issues.

// After successful authentication
Sentry.logger.info("User logged in", {
  userId: user.id,
  authMethod: "oauth",
  provider: "google",
});

// After authentication fails
Sentry.logger.warn("Login failed", {
  email: maskedEmail,
  reason: "invalid_password",
  attemptCount: 3,
});

Query in Explore > Logs: userId:123 "logged in" or severity:warn authMethod:*

Alert idea: Alert when severity:warn "Login failed" spikes in a 5-minute window—this can indicate brute force attempts or auth provider issues.

2. Payment and Checkout

Money paths need visibility even when they succeed. When payments fail, you need context fast.

// After payment gateway returns an error
Sentry.logger.error("Payment failed", {
  orderId: "order_123",
  amount: 99.99,
  gateway: "stripe",
  errorCode: "card_declined",
  cartItems: 3,
});

Query in Explore > Logs: orderId:order_123 or severity:error gateway:stripe

Alert idea: Alert when severity:error gateway:* spikes—this can indicate payment provider outages.

3. External APIs and Async Operations

Traces capture what your code does. Logs capture context about external triggers and async boundaries. These are things like webhooks, scheduled tasks, and third-party API responses that traces can't automatically instrument.

// Third-party API call
const start = Date.now();
const response = await shippingApi.getRates(items);

Sentry.logger.info("Shipping rates fetched", {
  service: "shipping-provider",
  endpoint: "/rates",
  durationMs: Date.now() - start,
  rateCount: response.rates.length,
});

// Webhook received
Sentry.logger.info("Webhook received", {
  source: "stripe",
  eventType: "payment_intent.succeeded",
  paymentId: event.data.object.id,
});

Query in Explore > Logs: service:shipping-provider durationMs:>2000 or source:stripe

Alert idea: Alert when service:* durationMs:>3000 to catch third-party slowdowns before they cascade.

4. Background Jobs

Jobs run outside the request context. Without logs, failed jobs are invisible until someone notices missing data.

// Inside background job handler
Sentry.logger.info("Job started", {
  jobType: "email-digest",
  jobId: "job_456",
  queue: "notifications",
});

Sentry.logger.error("Job failed", {
  jobType: "email-digest",
  jobId: "job_456",
  retryCount: 3,
  lastError: "SMTP timeout",
});

Query in Explore > Logs: jobType:email-digest severity:error

Alert idea: Alert when severity:error jobType:* spikes—this can indicate queue processing issues or downstream failures.

5. Feature Flags and Config Changes

When something breaks after a deploy, the first question is "what changed?" Logging flag evaluations and config reloads gives you that answer instantly.

// When feature flag is checked or config changes
Sentry.logger.info("Feature flag evaluated", {
  flag: "new-checkout-flow",
  enabled: true,
  userId: user.id,
});

Sentry.logger.warn("Config reloaded", {
  reason: "env-change",
  changedKeys: ["API_TIMEOUT", "MAX_CONNECTIONS"],
});

Query in Explore > Logs: flag:new-checkout-flow or "Config reloaded"

Creating Alerts From Logs

1. Go to Explore > Logs
2. Enter your search query (e.g., severity:error gateway:*)
3. Click Save As - Alert
4. Choose a threshold type:
   • Static: Alert when count exceeds a value
   • Percent Change: Alert when count changes relative to a previous period
   • Anomaly: Let Sentry detect unusual patterns
5. Configure notification channels and save

Learn about creating alerts and best practices for reducing noise and routing notifications.

Logging Strategy

Development Logging

In development, set sample rates to 100% to catch everything. This helps you understand what logs are being generated and tune your instrumentation before it hits production.

Development configuration:

Sentry.init({
  dsn: "...",
  environment: "development",
  tracesSampleRate: 1.0, // 100% of traces
  // Capture all logs in development
  integrations: [
    Sentry.captureConsoleIntegration({
      levels: ["log", "info", "warn", "error", "debug"],
    }),
  ],
});

Use verbose logging levels like debug (development diagnostics) and trace (fine-grained execution details) freely in development. You can filter these out in production using beforeSendLog to only capture info and above.

Production Logging

Local debugging often means many small logs tracing execution flow. In production, this creates noise that's hard to query.

Instead, log fewer messages with higher cardinality. Store events during execution and emit them as a single structured log.

Don't do this:

Sentry.logger.info("Checkout started", { userId: "882" });
Sentry.logger.info("Discount applied", { code: "WINTER20" });
Sentry.logger.error("Payment failed", { reason: "Insufficient Funds" });

These logs are trace-connected, but searching for the error won't return the userId or discount code from the same transaction.

Do this instead:

Sentry.logger.error("Checkout failed", {
  userId: "882",
  orderId: "order_pc_991",
  cartTotal: 142.5,
  discountCode: "WINTER20",
  paymentMethod: "stripe",
  errorReason: "Insufficient Funds",
  itemCount: 4,
});

One log tells the whole story. Search for the error and get full context.

Log Drains for Platform Logs

If you can't install the Sentry SDK or need platform-level logs (CDN, database, load balancer), use Log Drains.

Platform drains: Vercel, Cloudflare Workers, Heroku, Supabase

Forwarders: OpenTelemetry Collector, Vector, Fluent Bit, AWS CloudWatch, Kafka

Quick Reference

Next Steps

Explore the Logs product walkthrough guides to learn more about the Sentry interface and discover additional tips.