Epsagon Tracing for Ruby

This package provides tracing to Ruby applications for the collection of distributed tracing and performance metrics in Epsagon.

Installation

To install Epsagon, run:

$ gem install epsagon

Usage

Important: Epsagon is activated and instruments the supported libraries once the module is imported.

Auto Tracing

To enable automatic tracing on the supported libraries, add this snippet to your code:
(for a Rails app, the snippet can be added in config/boot.rb)

require 'epsagon'

Epsagon.init

Set the token and app name, and run your Ruby command:

$ export EPSAGON_TOKEN=<epsagon-token>
$ export EPSAGON_APP_NAME=<app-name>
$ <ruby command>

When using inside a Dockerfile, you can use ENV instead of export.

Integrations

Epsagon provides out-of-the-box instrumentation (tracing) for some popular frameworks and libraries.

LibrarySupported Version
net/httpFully supported
faradayFully supported
sinatraFully supported
rails>=4.0.0
aws-sdk>=2.0.0

Custom traces

Epsagon for Ruby is based on OpenTelemetry.
You can use the trace API to create custom spans:

require 'epsagon'

Epsagon.init

tracer = OpenTelemetry.tracer_provider.tracer('send-test-spans', '0.1.0')

tracer.in_span('my-task') do |span|
  span.set_attribute('task_attribute', true)
  span.set_attribute('another_task_attribute', 42)
  span.set_attribute('yet_another_task_attribute', 'Attirbute value.')
  start_my_task()
  tracer.in_span('inner-task') do |child_span|
    do_traced_subtask()
    child_span.set_attribute('inner_span_attr', 'inner_span_attr value')
  end
  finish_my_task()
end

Configuration

The same settings from the environment variables and additional parameters can be set on initialization, e.g.:

require 'epsagon'

Epsagon.init({
  metadata_only: false,
  debug: true,
  token: '<epsagon-token>',
  app_name: 'example-app-name',
})

The supported parameters are:

ParameterEnvironment VariableTypeDefaultDescription
tokenEPSAGON_TOKENString-Epsagon account token
app_nameEPSAGON_APP_NAMEString-Application name that will be set for traces
metadata_onlyEPSAGON_METADATABooleanFalseWhether to send only the metadata (True) or also the payloads (False)
debugEPSAGON_DEBUGBooleanFalseEnable debug prints for troubleshooting

Getting Help

If you have any issue around using the library or the product, please don't hesitate to:

  • Use the documentation.
  • Use the help widget inside the product.
  • Open an issue in GitHub.

Did this page help you?