Set Up Logs

npx @sentry/dotagents add getsentry/sentry-agent-skills --name sentry-setup-logging

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 Ruby are supported in Sentry Ruby SDK version 5.24.0 and above.

gem install sentry-ruby

Or add it to your Gemfile:

gem "sentry-ruby"

Setup

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

Sentry.init do |config|
  config.dsn = "___PUBLIC_DSN___"
  config.enable_logs = true
end

Usage

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

The logger namespace exposes six methods that you can use to log messages at different log levels: trace, debug, info, warning, error, and fatal.

You can pass additional attributes directly to the logging functions. These properties will be sent to Sentry, and can be searched from within the Logs UI, and even added to the Logs views as a dedicated column.

Sentry.logger.info("Updated global cache")

Sentry.logger.debug("Cache miss for user %{user_id}", user_id: 123)

Sentry.logger.trace(
  "Starting database connection %{database}",
  database: "users"
)

Sentry.logger.warn(
  "Rate limit reached for endpoint %{endpoint}",
  endpoint: "/api/results/"
)

Sentry.logger.error(
  "Failed to process payment. Order: %{order_id}. Amount: %{amount}",
  order_id: "or_2342", amount: 99.99
)

Sentry.logger.fatal(
  "Database %{database} connection pool exhausted",
  database: "users"
)

You can also use message templates with positional or hash parameters:

# Using named parameters
Sentry.logger.info("User %{name} logged in", name: "Jane Doe")

# Using positional parameters
Sentry.logger.info("User %s logged in", ["Jane Doe"])

Any other arbitrary attributes will be sent as part of the log event payload:

# Here `user_id` and `action` will be sent as extra attributes that
# Sentry Logs UI displays
Sentry.logger.info(
  "User %{user} logged in",
  user: "Jane", user_id: 123, action: "create"
)

Options

before_send_log

To filter logs before they are sent to Sentry, use the before_send_log callback. Return nil to skip a log, or return the log object to send it.

Sentry.init do |config|
  config.dsn = "___PUBLIC_DSN___"
  config.enable_logs = true

  config.before_send_log = lambda do |log|
    # Skip info logs
    return if log.level == :info

    log
  end
end

std_lib_logger_filter

When using the :logger patch for Ruby's standard library logger, you can filter log messages using std_lib_logger_filter. The callback receives the logger instance, message, and severity level. Return true to send the log, or false to skip it.

Sentry.init do |config|
  config.dsn = "___PUBLIC_DSN___"
  config.enable_logs = true
  config.enabled_patches << :logger

  # Only send ERROR and FATAL logs to Sentry
  config.std_lib_logger_filter = proc do |logger, message, severity|
    [:error, :fatal].include?(severity)
  end
end

Default Attributes

The Ruby SDK 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.
• sdk.name: The name of the SDK that sent the log. 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.

Message Template Attributes

If the log was parameterized, 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.

Server Attributes

• server.address: The address of the server that sent the log. Equivalent to server_name that gets attached to Sentry errors.

User Attributes

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

• user.id: The user ID.
• user.name: The username.
• user.email: The email address.

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.

Other Logging Integrations

Available integrations:

• Standard library logging