Send OpenTelemetry data from a Ruby on Rails app to Axiom

This guide explains how to send OpenTelemetry data from a Ruby on Rails App to Axiom using the Ruby OpenTelemetry SDK.

This guide provides detailed steps on how to configure OpenTelemetry in a Ruby application to send telemetry data to Axiom using the OpenTelemetry Ruby SDK.

Prerequisites

• Create an Axiom account.
• Create a dataset in Axiom where you send your data.
• Create an API token in Axiom with permissions to update the dataset you have created.

• Install a Ruby version manager like rbenv and use it to install the latest Ruby version.
• Install Rails using the gem install rails command.

Set up the Ruby on Rails application

1. Create a new Rails app using the rails new myapp command.
2. Go to the app directory with the cd myapp command.
3. Open the Gemfile and add the following OpenTelemetry packages:

gem 'opentelemetry-api'
gem 'opentelemetry-sdk'
gem 'opentelemetry-exporter-otlp'
gem 'opentelemetry-instrumentation-rails'
gem 'opentelemetry-instrumentation-http'
gem 'opentelemetry-instrumentation-active_record', require: false
gem 'opentelemetry-instrumentation-all'

Install the dependencies by running bundle install.

Configure the OpenTelemetry exporter

In the initializers folder of your Rails app, create a new file called opentelemetry.rb, and then add the following OpenTelemetry exporter configuration:

require 'opentelemetry/sdk'
require 'opentelemetry/exporter/otlp'
require 'opentelemetry/instrumentation/all'

OpenTelemetry::SDK.configure do |c|
  c.service_name = 'ruby-traces' # Set your service name

  c.use_all # Or specify individual instrumentation you need

  c.add_span_processor(
    OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
      OpenTelemetry::Exporter::OTLP::Exporter.new(
        endpoint: 'https://AXIOM_DOMAIN/v1/traces',
        headers: {
          'Authorization' => 'Bearer API_TOKEN',
          'X-AXIOM-DATASET' => 'DATASET_NAME'
        }
      )
    )
  )
end

Replace API_TOKEN with the Axiom API token you have generated. For added security, store the API token in an environment variable.

Replace DATASET_NAME with the name of the Axiom dataset where you want to send data.

Replace AXIOM_DOMAIN with api.axiom.co if your organization uses the US region, and with api.eu.axiom.co if your organization uses the EU region. For more information, see Regions.

Run the instrumented application

Run your Ruby on Rails application with OpenTelemetry instrumentation.

In development mode

Start the Rails server using the rails server command. The server will start on the default port (usually 3000), and you can access your application by visiting http://localhost:3000 in your web browser.

As you interact with your application, OpenTelemetry automatically collects telemetry data and sends it to Axiom using the configured OTLP exporter.

In production mode

For production, ensure to precompile assets and run migrations if necessary. Start the server with RAILS_ENV=production bin/rails server. This setup ensures your Ruby application is instrumented to send traces to Axiom, using OpenTelemetry for observability.

Observe the telemetry data in Axiom

As you interact with your application, traces are collected and exported to Axiom, allowing you to monitor, analyze, and gain insights into your application’s performance and behavior.

1. In your Axiom account and click on the Datasets or Stream tab.

2. Select your dataset from the list.

3. From the list of fields, click on the trace_id to view your spans.

Dynamic OpenTelemetry Traces dashboard

This data can then be further viewed and analyzed in Axiom’s dashboard, offering a deeper understanding of your application’s performance and behavior.

1. In your Axiom account, select Dashboards, and click on the traces dashboard named after your dataset.

2. View the dashboard which displays your total traces, incoming spans, average span duration, errors, slowest operations, and top 10 span errors across services.

Send data from an existing Ruby app

Manual instrumentation

Manual instrumentation allows users to define and manage telemetry data collection points within their Ruby applications, providing granular control over what is traced.

1. Initialize Tracer. Use the OpenTelemetry API to obtain a tracer from the global tracer provider. This tracer will be used to start and manage spans.

tracer = OpenTelemetry.tracer_provider.tracer('my-tracer')

2. Manually start a span at the beginning of the block of code you want to trace and ensure to end it when your operations complete. This is useful for gathering detailed data about specific operations.

span = tracer.start_span('operation_name')
begin
  # Perform operation
rescue => e
  span.record_exception(e)
  span.status = OpenTelemetry::Trace::Status.error("Operation failed")
ensure
  span.finish
end

3. Enhance spans with custom attributes to provide additional context about the traced operations, helping in debugging and monitoring performance.

span.set_attribute("user_id", user.id)
span.add_event("query_executed", attributes: { "query" => sql_query })

Automatic instrumentation

Automatic instrumentation in Ruby uses OpenTelemetry’s libraries to automatically generate telemetry data for common operations, such as HTTP requests and database queries.

1. Set up the OpenTelemetry SDK with the necessary instrumentation libraries in your Ruby application. This typically involves modifying the Gemfile and an initializer to set up the SDK and auto-instrumentation.

# In config/initializers/opentelemetry.rb
OpenTelemetry::SDK.configure do |c|
  c.service_name = 'ruby-traces'
  c.use_all  # Automatically use all available instrumentation
end

2. Ensure your Gemfile includes gems for the automatic instrumentation of the frameworks and libraries your application uses.

gem 'opentelemetry-instrumentation-rails'
gem 'opentelemetry-instrumentation-http'
gem 'opentelemetry-instrumentation-active_record'

After setting up, no additional manual changes are required for basic telemetry data collection. The instrumentation libraries handle the creation and management of telemetry data automatically.

Reference

List of OpenTelemetry trace fields

Field Category	Field Name	Description
General Trace Information
	_rowId	Unique identifier for each row in the trace data.
	_sysTime	System timestamp when the trace data was recorded.
	_time	Timestamp when the actual event being traced occurred.
	trace_id	Unique identifier for the entire trace.
	span_id	Unique identifier for the span within the trace.
	parent_span_id	Unique identifier for the parent span within the trace.
HTTP Attributes
	attributes.http.method	HTTP method used for the request.
	attributes.http.status_code	HTTP status code returned in response.
	attributes.http.target	Specific target of the HTTP request.
	attributes.http.scheme	Protocol scheme (HTTP/HTTPS).
User Agent
	attributes.http.user_agent	User agent string, providing client software and OS.
Custom Attributes
	attributes.custom[“http.host”]	Host information where the HTTP request was sent.
	attributes.custom.identifier	Path to a file or identifier in the trace context.
	attributes.custom.layout	Layout used in the rendering process of a view or template.
Resource Process Attributes
	resource.process.command	Command line string used to start the process.
	resource.process.pid	Process ID.
	resource.process.runtime.description	Description of the runtime environment.
	resource.process.runtime.name	Name of the runtime environment.
	resource.process.runtime.version	Version of the runtime environment.
Operational Details
	duration	Time taken for the operation.
	kind	Type of span (e.g., server, client, internal).
	name	Name of the span, often a high-level title for the operation.
Code Attributes
	attributes.code.function	Function or method being executed.
	attributes.code.namespace	Namespace or module that includes the function.
Scope Attributes
	scope.name	Name of the scope for the operation.
	scope.version	Version of the scope.
Service Attributes
	service.name	Name of the service generating the trace.
	service.version	Version of the service generating the trace.
	service.instance.id	Unique identifier for the instance of the service.
Telemetry SDK Attributes
	telemetry.sdk.language	Language of the telemetry SDK, e.g., ruby.
	telemetry.sdk.name	Name of the telemetry SDK, e.g., opentelemetry.
	telemetry.sdk.version	Version of the telemetry SDK, e.g., 1.4.1.

List of imported libraries

gem 'opentelemetry-api'

The opentelemetry-api gem provides the core OpenTelemetry API for Ruby. It defines the basic concepts and interfaces for distributed tracing, such as spans, tracers, and context propagation. This gem is essential for instrumenting your Ruby application with OpenTelemetry.

gem 'opentelemetry-sdk'

The opentelemetry-sdk gem is the OpenTelemetry SDK for Ruby. It provides the implementation of the OpenTelemetry API, including the tracer provider, span processors, and exporters. This gem is responsible for managing the lifecycle of spans and sending them to the specified backend.

gem 'opentelemetry-exporter-otlp'

The opentelemetry-exporter-otlp gem is an exporter that sends trace data to a backend that supports the OpenTelemetry Protocol (OTLP), such as Axiom. It formats the trace data according to the OTLP standards and transmits it over HTTP or gRPC, ensuring compatibility and standardization in how telemetry data is sent across different systems and services.

gem 'opentelemetry-instrumentation-rails'

The opentelemetry-instrumentation-rails gem provides automatic instrumentation for Ruby on Rails applications. It integrates with various aspects of a Rails application, such as controllers, views, and database queries, to capture relevant trace data without requiring manual instrumentation. This gem simplifies the process of adding tracing to your Rails application.

gem 'opentelemetry-instrumentation-http'

The opentelemetry-instrumentation-http gem provides automatic instrumentation for HTTP requests made using the Net::HTTP library. It captures trace data for outgoing HTTP requests, including request headers, response status, and timing information. This gem helps in tracing the external dependencies of your application.

gem 'opentelemetry-instrumentation-active_record', require: false

The opentelemetry-instrumentation-active_record gem provides automatic instrumentation for ActiveRecord, the Object-Relational Mapping (ORM) library used in Ruby on Rails. It captures trace data for database queries, including the SQL statements executed and their duration. This gem helps in identifying performance bottlenecks related to database interactions.

gem 'opentelemetry-instrumentation-all'

The opentelemetry-instrumentation-all gem is a meta-gem that includes all the available instrumentation libraries for OpenTelemetry in Ruby. It provides a convenient way to install and configure multiple instrumentation libraries at once, covering various aspects of your application, such as HTTP requests, database queries, and external libraries. This gem simplifies the setup process and ensures comprehensive tracing coverage for your Ruby application.