Logs

Log processing MUST follow this order:

1. Capture log via Public APIs (e.g. Sentry.logger.info) or via SDK integrations.
2. Check if logging is enabled via enableLogs/enable_logs — if not, skip remaining steps.
3. Pass the log to Hub/Scope via a generic method (e.g., captureLog).
4. Pass the log to the Client via a generic method (e.g., captureLog).
5. Process captured log (attach attributes per Default Attributes).
6. Run beforeSendLog/before_send_log to filter or modify the log.
7. Add log to buffer/batch processor per Buffering.
8. At flush time, send array of logs to Sentry via log envelope, applying rate limiting per Data Category and Rate Limiting.

SDKs MUST attach the following attributes to every log:

For parameterized logs, SDKs MUST also attach:

If there are no sentry.message.parameter.X attributes, SDKs MUST NOT attach sentry.message.template (since 1.7.0). This reduces duplicate content and simplifies PII processing.

If a log is generated by an SDK integration, the SDK SHOULD set the sentry.origin attribute per the Trace Origin documentation.

Since 1.9.0, logs follow these rules:

1. User calls Sentry's Logging API directly: SDKs MUST NOT send sentry.origin. This intentionally deviates from the Trace Origin spec to minimize log size.
2. Captured from a logging library: Use auto.log.<name> format (e.g., "auto.log.serilog").
3. Auto-emitted from other instrumented systems: Use auto.<category>.<integration-name> format (e.g., "auto.db.prisma").

SDKs MAY attach user information as attributes, guarded by sendDefaultPii (since 1.14.0):

By default, Relay parses the user agent attached to an incoming log envelope to extract browser and os information. SDKs MAY attach these attributes if they do not forward a user agent:

Backend SDKs (Node.js, Python, PHP, etc.) SHOULD attach:

Mobile, desktop, and native SDKs (Android, Apple, Electron, etc.) SHOULD attach:

SDKs MUST buffer logs before sending. A simple initial strategy is flushing when the buffer exceeds 100 items or 5 seconds have passed. The buffer SHOULD forward logs to the transport in the scenarios outlined in the telemetry buffer data forwarding scenarios.

SDKs MUST NOT send more than 100 logs per envelope (since 1.15.0). Relay is optimized for this limit.

SDKs MUST enforce a hard limit of 1000 queued log events to prevent out-of-memory issues (since 1.12.0). Logs added beyond this limit are dropped. SDKs MAY use a lower limit but MUST NOT exceed 1000.

SDKs MUST NOT release logging capabilities to users without a buffering implementation.

Logs use the log_item data category for rate limiting in Relay. Both log and otel_log envelopes are covered by this data category. SDKs MUST implement this data category. Rate limiting applies as usual with no special behavior for logs.

SDKs MUST track client outcomes for this data category to report how often logs are dropped.

SDKs SHOULD provide integrations that capture logs from platform logging libraries (e.g., JavaScript's console, Python's logging, Java's Log4j) when enableLogs/enable_logs is set to true.

SDKs MAY introduce additional options beyond enableLogs/enable_logs to gate integration-specific functionality (e.g., controlling log appenders added via external config).

Logs emitted via the public API are opt-out. The enableLogs/enable_logs option MUST act as a general kill switch for all logs sent to Sentry. When set to false, no logs MUST be sent, regardless of whether they originate from the public API, auto-emitting integrations, or third-party bindings.

However, logs that are automatically emitted by integrations or libraries without an explicit user call follow different rules because they can generate unexpected volume and cost.

Integrations that auto-emit logs - An SDK integration that automatically captures logs (e.g., forwarding console.log calls, capturing framework-level diagnostic output) MUST be opt-in. The integration MUST NOT emit any logs unless the user explicitly enables it. The opt-in mechanism MAY be a dedicated integration-level option or requiring the user to explicitly add the integration.

Third-party log bindings - An SDK feature that binds to an external library's logging API and mirrors those logs as Sentry logs in the background (e.g., syncing from Python's logging module or a framework's built-in logger) MUST also be opt-in. Users MUST explicitly enable the binding before any logs are forwarded to Sentry.

These rules exist because auto-emitted logs can cause a high volume of telemetry that directly impacts a user's quota. Unlike errors, where users have prior intuition about volume, silently emitting logs on their behalf could lead to unexpected costs. Requiring opt-in ensures users remain in control of their log volume.

Logs SHOULD be associated with traces. If a log is recorded during an active span, SDKs SHOULD set the span_id property to the active span's ID.

Logs SHOULD be associated with replays. If a log is recorded during an active replay, SDKs SHOULD set the sentry.replay_id attribute to the active replay's ID.

When sent, the sequence integer MUST:

• Start at 0 when the SDK initializes.
• Increment by 1 for each log that is captured.
• Reset to 0 when:
  • The SDK is re-initialized.
  • The current log's integer millisecond differs from the previous log's integer millisecond (i.e., floor(timestamp_seconds * 1000) changes).

The sequence provides deterministic ordering within a single SDK instance. It does not guarantee ordering across independent processes or workers, which have separate counters. The reset behavior ensures the sequence only increments for consecutive logs that share the same timestamp.

If debug is set to true in SDK init, calls to the Sentry logger API SHOULD also print to the console with the appropriate log level. This aids debugging of logging setups.

SDKs MUST report count (log_item) and size in bytes (log_byte) of discarded log messages. An approximation of log size is sufficient (e.g., by counting as if serialized).

The log envelope item payload is a JSON object that MUST include an items array of log entries, allowing multiple logs per envelope item. The payload MAY also include top-level version and ingest_settings fields as specified in the next section.

An envelope MUST contain at most one log envelope item — all log entries for a flush are batched into a single item's items array. Logs from different traces MAY be mixed into the same log item, but if they are, the envelope MUST NOT include a DSC (dynamic sampling context) header.

Item Headers:

{
  "type": "log",
  "item_count": 5,
  "content_type": "application/vnd.sentry.items.log+json"
}
{
  "version": 2,
  "ingest_settings": {
    "infer_ip": "auto",
    "infer_useragent": "auto"
  },
  "items": [{..log..}, {..log..}, {..log..}, {..log..}, {..log..}]
}

The log envelope item ingest_settings property is an optional JSON object that contains ingestion settings for Relay, for example, to infer certain data from the incoming request.

SDKs like Browser or React Native MAY set these to "auto" to instruct Relay to infer the IP address or user agent from the incoming request and put it onto the log as an attribute.

For ingestion settings to take effect, the SDK MUST also set the version property to 2 (number) or higher. If version is omitted, Relay treats the payload as version 1 and doesn't apply ingest_settings.

Each log in the items array is a JSON object:

{
  "timestamp": 1544719860.0,
  "trace_id": "5b8efff798038103d269b633813fc60c",
  "span_id": "b0e6f15b45c36b12",
  "level": "info",
  "body": "User John has logged in!",
  "severity_number": 9,
  "attributes": {
    "sentry.message.template": {
      "value": "User %s has logged in!",
      "type": "string"
    },
    "sentry.message.parameter.0": {
      "value": "John",
      "type": "string"
    }
  }
}

SDKs MUST expose the following configuration options:

The default for enableLogs/enable_logs was changed from false to true in version 2.0.0. The previous default required users to explicitly opt in before they could use the logging primitives. By defaulting to true, adding a Sentry.logger.* statement is itself the opt-in. Users can start logging without additional configuration. This aligns the behavior with enableMetrics/enable_metrics, which also defaults to true.

While logs functionality is in an experimental state, SDKs SHOULD put these options in an experimental namespace to avoid breaking changes:

Sentry.init({
  // stable
  enableLogs: true,

  // experimental
  _experiments: { enableLogs: true },
});

SDKs MUST expose logging methods in a logger module or namespace, with one method per severity level:

• Sentry.logger.trace
• Sentry.logger.debug
• Sentry.logger.info
• Sentry.logger.warn
• Sentry.logger.error
• Sentry.logger.fatal

These methods accept a string template and parameters for structured logging. They MAY also accept arbitrary attributes.

The Hub/Scope and Client MUST exclusively provide a generic logging method (e.g., captureLog). They MUST NOT replicate the static Sentry.logger.X API methods to avoid increasing our API surface. Users utilizing multiple Hub/Scope or Clients will need to rely on the generic method for logging.

The Sentry.logger.X methods are fire-and-forget (no return value). SDKs MAY run these methods on a separate thread or queue them for later processing, including evaluating the string template and running internal hooks like beforeSendLog.

SDKs MUST ensure logs are sent in the order they are received.