Instrument Ruby applications with OpenTelemetry

This guide shows how to instrument your Ruby application with OpenTelemetry and export the traces to Dynatrace. To learn more about how Dynatrace works with OpenTelemetry, see Send data to Dynatrace with OpenTelemetry.

Prerequisites

The following prerequisites and limitations apply:

  • Dynatrace version 1.222+
  • W3C Trace Context is enabled
    1. From the Dynatrace menu, go to Settings and select Server-side service monitoring > Deep monitoring > Distributed tracing.
    2. Turn on Send W3C Trace Context HTTP headers.

Instrument your application

To instrument the application

  1. Install the required gems
  2. Get the endpoint and authentication token
  3. Modify and add the trace code

1. Install the required gems

  1. Install the OpenTelemetry SDK, API, and necessary exporter gems.

    gem install 'opentelemetry-api'
    gem install 'opentelemetry-sdk'
    gem install 'opentelemetry-exporter-otlp'
    
  2. Go to the RubyGems OpenTelemetry page, find the framework your app is using, and install the corresponding gem using the following command:

    gem install 'opentelemetry-instrumentation-<USED_FRAMEWORK>'
    

    where <USED_FRAMEWORK> is the framework your app uses (one of the frameworks listed on the RubyGems OpenTelemetry page).

    Alternatively, you can use opentelemetry-instrumentation-all, in which case your console will display some warnings about instrumentations that are not utilized. You can safely ignore them.

2. Get the endpoint and authentication token

The endpoint and authentication token you determine in this section will be needed in section 3.

To determine the endpoint to which your app will send traces

  1. Open Dynatrace.
  2. Check the address line of your browser. The URL will match one of the following patterns:
    • Dynatrace SaaS: https://{your-environment-id}.live.dynatrace.com/...
    • Dynatrace Managed: https://{your-domain}/e/{your-environment-id}/...
  3. Replace the ... part with api/v2/otlp/v1/traces to get the URL you will need in section 3 below.
    • Dynatrace SaaS: https://{your-environment-id}.live.dynatrace.com/api/v2/otlp/v1/traces
    • Dynatrace Managed: https://{your-domain}/e/{your-environment-id}/api/v2/otlp/v1/traces

To create an authentication token

  1. In the Dynatrace menu, go to Access tokens and select Generate new token.
  2. Provide a Token name.
  3. In the Search scopes box, search for Ingest OpenTelemetry traces and select the checkbox.
  4. Select Generate token.
  5. Select Copy to copy the token to your clipboard.
  6. Save the token in a safe place; you can't display it again, and you will need it in section 3 below.

3. Modify and add the trace code

Add the following snippet to your Ruby application code:

require 'opentelemetry/sdk'
require 'opentelemetry/exporter/otlp'

OpenTelemetry::SDK.configure do |c|
  c.service_name = 'ruby-otlp' #required resource attribute
  c.service_version = '1.0.1' #required resource attribute
  c.use_all #with this, the application will be using all instrumentation provided by OpenTelemetry
  c.add_span_processor(
    OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
      OpenTelemetry::Exporter::OTLP::Exporter.new(
        endpoint: '<URL>',  #Replace <URL> with the URL as determined in section 2 above
        headers: {
          "Authorization": "Api-Token <TOKEN>" #Replace <TOKEN> with the authentication token created in section 2 above
        }
      )
    )
  )
end

Verify that the traces are ingested into Dynatrace

A few minutes after restarting your app, look for your spans:

  • In the Dynatrace menu, go to Distributed traces and select the Ingested traces tab.
  • Your spans will be part of an existing PurePath, if the root of your call is already monitored by OneAgent.

If your application does not receive any traffic, there will be no traces.

(Optional) Configure data capture to meet privacy requirements

While Dynatrace automatically captures all OpenTelemetry resource and span attributes, only attribute values specified in the allowlist are stored and displayed in the Dynatrace web UI. This prevents accidental storage of personal data, so you can meet your privacy requirements and control the amount of monitoring data that's stored.

To view your custom span attributes, you need to allow them in the Dynatrace web UI first:

  • Span attributes In the Dynatrace menu, go to Settings and select Server-side service monitoring > Span attributes.
  • Resource attributes In the Dynatrace menu, go to Settings and select Server-side service monitoring > Resource attributes.