Set Up Logs

With Sentry Structured Logs, you can send text-based log information from your applications to Sentry. Once in Sentry, these logs can be viewed alongside relevant errors, searched by text-string, or searched using their individual attributes.

Requirements

Logs for Apple platforms are supported in Sentry Cocoa SDK version 8.55.0 and above. Logs are still experimental and the API may change in the future.

Setup

To enable logging, you need to initialize the SDK with the experimental enableLogs option set to true.

import Sentry

SentrySDK.start { options in
    options.dsn = "https://examplePublicKey@o0.ingest.sentry.io/0"
    // Enable logs to be sent to Sentry
    options.experimental.enableLogs = true
}

Usage

Once the feature is enabled on the SDK and the SDK is initialized, you can send logs using the Sentry.logger APIs.

The Sentry.logger namespace exposes six methods that you can use to log messages at different log levels: trace, debug, info, warn, error, and fatal. Supported types for attributes are Strings, Int, Double, and Bool.

import Sentry

let logger = SentrySDK.logger

// Log messages without attributes
logger.trace("Starting database connection")
logger.debug("Cache miss for user")
logger.info("Updated profile")

// Log messages with attributes
logger.trace("Starting database connection", attributes: ["database": "users"])
logger.debug("Cache miss for user", attributes: ["userId": 123])
logger.info("Updated profile", attributes: ["profileId": 345])
logger.warn("Rate limit reached for endpoint", attributes: [
    "endpoint": "/api/results/",
    "isEnterprise": false
])
logger.error("Failed to process payment", attributes: [
    "orderId": "order_123",
    "amount": 99.99
])
logger.fatal("Database connection pool exhausted", attributes: [
    "database": "users",
    "activeConnections": 100
])

String Interpolation (Swift Only)

Swift supports automatic extraction of interpolated values as attributes. When you use string interpolation in your log messages, supported types (Strings, Int, Double, and Bool) are automatically extracted and added as attributes with the key format sentry.message.parameter.{index}.

let userId = "user_123"
let orderCount = 5
let isPremium = true
let totalAmount = 99.99

// String interpolation automatically extracts values as attributes
logger.info("User \(userId) placed \(orderCount) orders, premium: \(isPremium), total: $\(totalAmount)")

// This is equivalent to manually specifying attributes:
let message = "User \(userId) placed \(orderCount) orders, premium: \(isPremium), total: $\(totalAmount)"
logger.info(
  message,
  attributes: [
      "sentry.message.template": "User {0} placed {1} orders, premium: {2}, total: {3}",
      "sentry.message.parameter.0": userId,
      "sentry.message.parameter.1": orderCount,
      "sentry.message.parameter.2": isPremium,
      "sentry.message.parameter.3": totalAmount
  ]
)

Options

beforeSendLog

To filter logs, or update them before they are sent to Sentry, you can use the beforeSendLog option.

import Sentry

SentrySDK.start { options in
    options.dsn = "https://examplePublicKey@o0.ingest.sentry.io/0"
    options.experimental.enableLogs = true
    
    options.beforeSendLog = { log in
        if log.level == .info {
            // Filter out all info logs
            return nil
        }
        return log
    }
}

The beforeSendLog function receives a log object, and should return the log object if you want it to be sent to Sentry, or nil if you want to discard it.

The log object has the following properties:

• level: The log level (trace, debug, info, warn, error, fatal)
• message: The message to be logged
• timestamp: The timestamp of the log
• attributes: The attributes of the log

Default Attributes

The Apple SDKs automatically sets several default attributes on all log entries to provide context and improve debugging:

Core Attributes

• environment: The environment set in the SDK if defined. This is sent from the SDK as sentry.environment.
• release: The release set in the SDK if defined. This is sent from the SDK as sentry.release.
• trace.parent_span_id: The span ID of the span that was active when the log was collected (only set if there was an active span). This is sent from the SDK as sentry.trace.parent_span_id.
• sdk.name: The name of the SDK that sent the log. This is sent from the SDK as sentry.sdk.name. This is sent from the SDK as sentry.sdk.name.
• sdk.version: The version of the SDK that sent the log. This is sent from the SDK as sentry.sdk.version. This is sent from the SDK as sentry.sdk.version.

Message Template Attributes

If the log was paramaterized, Sentry adds the message template and parameters as log attributes.

• message.template: The parameterized template string. This is sent from the SDK as sentry.message.template.
• message.parameter.X: The parameters to fill the template string. X can either be the number that represent the parameter's position in the template string (sentry.message.parameter.0, sentry.message.parameter.1, etc) or the parameter's name (sentry.message.parameter.item_id, sentry.message.parameter.user_id, etc). This is sent from the SDK as sentry.message.parameter.X.

User Attributes

• user.id: The user ID. Maps to id in the User payload, which is set by default by the SDKs.

If user information is available in the current scope, the following attributes are added to the log:

• user.name: The username. Maps to username in the User payload.
• user.email: The email address. Maps to email in the User payload.

Message Template Attributes

If the log was paramaterized (like with Sentry.logger().error("A %s log message", "formatted");), Sentry adds the message template and parameters as log attributes.

Integration Attributes

If a log is generated by an SDK integration, the SDK will set additional attributes to help you identify the source of the log.

• origin: The origin of the log. This is sent from the SDK as sentry.origin.