Send Ruby application data to Observe¶

Get the Observe Agent¶

Install the Observe agent in your environment.

Add the OpenTelemetry auto-instrumentation for Ruby¶

First, acquire the dependencies:

bundle add opentelemetry-sdk opentelemetry-instrumentation-all

Now initialize the instrumentation. For a Rails application, create a file named config/initializers/opentelemetry.rb with the following code:

# config/initializers/opentelemetry.rb
require 'opentelemetry/sdk'
require 'opentelemetry/instrumentation/all'
OpenTelemetry::SDK.configure do |c|
  c.use_all()

For other types of Ruby services (i.e., not Rails), perform this initialization as early as possible in the start-up process.

Configure the Ruby instrumentation¶

Set the following environment variables:

Environment variable	Value
`OTEL_SERVICE_NAME`	your service name

Optional configuration: name GraphQL endpoints by operation¶

By default, the instrumentation discovers a single GraphQL endpoint, named GraphqlController#execute.

If you’re using GraphQL and Rack with Ruby, want more detailed GraphQL endpoint names, use this during initialization of the OpenTelemetry SDK:

c.use_all('OpenTelemetry::Instrumentation::GraphQL' => {
    enable_platform_field: true,
    enable_platform_authorized: true,
    enable_platform_resolve_type: true,
    legacy_platform_span_names:true,
    legacy_tracing: true
    })

Then add this code in your Rack controller:

rack_span = OpenTelemetry::Trace.current_span
rack_span.name = <your preferred span name>

Example code to name the span according to the GraphQL operation:

def transaction_name(query)
selected_op = query.selected_operation
txn_name = if selected_op
    op_type = selected_op.operation_type
    op_name = selected_op.name || fallback_transaction_name(query.context) || "anonymous"
    "#{op_type}.#{op_name}"
else
    "query.anonymous"
end
"GraphQL/#{txn_name}"
end

Optional configuration: Name Sidekiq endpoints by class¶

By default, the instrumentation names Sidekiq endpoints by operation name and destination.

To instead identify Sidekiq endpoints by job class, use this during initialization of the OpenTelemetry SDK:

c.use_all('OpenTelemetry::Instrumentation::Sidekiq' => {
    span_naming: "job_class"
    })

Run your instrumented app¶

rails server -p 8080

Next steps¶

Navigate to Traces in your Observe tenant to view traces from your application.

Troubleshooting¶

My application data is not reaching Observe¶

If your data is not showing up in Observe, first verify that Observe Agent is receiving data from your application. See Troubleshooting the Observe Agent.

Common reasons why the Observe agent is not receiving traces from your application:

Default exporter settings override¶

By default, OpenTelemetry instrumentation exports data using standard OTLP settings, which are automatically compatible with the Observe Agent’s default receiver configuration.

This means that data from your application might not be reaching the Observe Agent if you have overridden the following environment variables with non-default settings:

OTEL_EXPORTER_OTLP_ENDPOINT
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT

Ensure these variables are unset or set to the correct endpoint (e.g., http://localhost:4317 for gRPC or http://localhost:4318 for HTTP).

Ports blocked by firewall¶

Ensure that any firewalls within the same network as your app and collector are configured to allow traffic on ports 4317 and 4318. The application instrumentation uses these ports to communicate with the Observe agent.

I am getting duplicate spans in Observe¶

If you’re seeing multiple spans with the same span_id in the Trace Explorer, the cause may be the following:

Multiple layers of OTel instrumentation for the same spans
Multiple exporters configured (either in your Agent, OTel collector, or application code) that point to Observe
Some other pathway in your environment is duplicating data (e.g., proxy or load balancer)