OpenTelemetry ActionMailer Instrumentation

The ActionMailer instrumentation is a community-maintained instrumentation for the ActionMailer portion of the Ruby on Rails web-application framework.

How do I get started?

Install the gem using:

# Install just the ActionMailer instrumentation
gem install opentelemetry-instrumentation-action_mailer
# Install the ActionMailer instrumentation along with the rest of the Rails-related instrumentation
gem install opentelemetry-instrumentation-rails

Or, if you use bundler, include opentelemetry-instrumentation-action_mailer in your Gemfile.

Usage

To use the instrumentation, call use with the name of the instrumentation:

OpenTelemetry::SDK.configure do |c|
  # Use only the ActionMailer instrumentation 
  c.use 'OpenTelemetry::Instrumentation::ActionMailer'
  # Use the ActionMailer instrumentation along with the rest of the Rails-related instrumentation
  c.use 'OpenTelemetry::Instrumentation::Rails'
end

Alternatively, you can also call use_all to install all the available instrumentation.

OpenTelemetry::SDK.configure do |c|
  c.use_all
end

Active Support Instrumentation

This instrumentation relies entirely on ActiveSupport::Notifications and registers a custom Subscriber that listens to relevant events to report as spans.

See the table below for details of what Rails Framework Hook Events are recorded by this instrumentation:

Event Name	Creates Span?	Notes
deliver.action_mailer	:white_check_mark:	Creates an span with kind internal and email content and status
process.action_mailer	:x:	Lack of useful info so ignored

Options

ActionMailer instrumentation doesn't expose email addresses by default, but if email addresses are needed, simply use :email_address option:

OpenTelemetry::SDK.configure do |c|
  c.use 'OpenTelemetry::Instrumentation::ActionMailer', { email_address: :include }
end

If only want to hide certain attributes from the notifications payload for email address:

OpenTelemetry::SDK.configure do |c|
  c.use 'OpenTelemetry::Instrumentation::ActionMailer', { email_address: :include, disallowed_notification_payload_keys: ['email.to.address'] }
end

Semantic Conventions

Internal spans are named using the name of the ActiveSupport event that was provided (e.g. action_mailer deliver).

The following attributes from the notification payload for the deliver.action_mailer event are attached to action_mailer deliver spans:

Attribute Name	Type	Notes
email.x_mailer	String	Mailer class that is used to send mail
email.message_id	String	Set from Mail gem
email.subject	String	Mail subject
email.to.address	Array	Receiver for mail (omit by default, include when email_address set to :include)
email.from.address	Array	Sender for mail (omit by default, include when email_address set to :include)
email.cc.address	Array	mail CC (omit by default, include when email_address set to :include)
email.bcc.address	Array	mail BCC (omit by default, include when email_address set to :include)

Examples

Example usage can be seen in the ./example/trace_request_demonstration.ru file here

How can I get involved?

The opentelemetry-instrumentation-action_mailer gem source is on GitHub, along with related gems including opentelemetry-api and opentelemetry-sdk.

The OpenTelemetry Ruby gems are maintained by the OpenTelemetry-Ruby special interest group (SIG). You can get involved by joining us in GitHub Discussions or attending our weekly meeting. See the meeting calendar for dates and times. For more information on this and other language SIGs, see the OpenTelemetry community page.

License

The opentelemetry-instrumentation-action_mailer gem is distributed under the Apache 2.0 license. See LICENSE for more information.