Splunk Distribution of OpenTelemetry Ruby

The Splunk Distribution of OpenTelemetry Instrumentation for Ruby provides a gem for setup of OpenTelemetry SDK for reporting distributed traces to Splunk APM.

This distribution comes with the following defaults:

W3C tracecontext and baggage propagation.
OTLP exporter configured to send spans to a locally running OpenTelemetry Collector over HTTP (default endpoint: localhost:4318).
Unlimited default limits for configuration options to support full-fidelity traces.

Requirements

Ruby 2.6+

Get started

This Splunk distribution comes with the following defaults:

W3C tracecontext and W3C baggage context propagation.
OTLP over HTTP exporter configured to send spans to a locally running Splunk OpenTelemetry Connector at http://localhost:4318.
Unlimited default limits for configuration options to support full-fidelity traces.

Install the gem by adding it to your project's Gemfile:

gem "splunk-otel", "~> 1.0"

bundle add splunk-otel --version "~> 1.0"

Configure OpenTelemetry using the Splunk::Otel module from splunk/otel:

require "splunk/otel"
...
Splunk::Otel.configure

Basic configuration

The service.name resource attribute is the only configuration option that needs to be specified, using either the environment variable OTEL_SERVICE_NAME or passing as an argument to configure:

Splunk::Otel.configure(service_name: "my-service")

Other resource attributes are not strictly required, but deployment.environment and service.version are recommended to be set if they are available. These can be set through the environment variable OTEL_RESOURCE_ATTRIBUTES:

OTEL_RESOURCE_ATTRIBUTES="service.version=1.2.3,deployment.environment=production"

alternatively, if needed, more attributes can be added in code using:

Splunk::Otel.configure(service_name: "my-service") do |c|
  c.resource = OpenTelemetry::SDK::Resources::Resource.create(
    "key" => "value"
  )
end

Advanced configuration

See advanced-config.md for information on how to configure the instrumentation.

Correlate traces and logs

You can add trace metadata to logs using the OpenTelemetry trace API. Trace metadata lets you explore logs in Splunk Observability Cloud.

See Correlating traces and logs for more information.

Library instrumentation

Supported libraries are listed here. The corresponding gems for the instrumentation libraries can be found under the opentelemetry-ruby profile on rubygems.org.

Automatic instrumentation

You can enable automatic instrumentation of all libraries used in your project that have corresponding OpenTelemetry Ruby gems libraries by installing the opentelemetry-instrumentation-all gem in your Gemfile:

gem "opentelemetry-instrumentation-all", "~> 0.27"

Enable the instrumentations from the gem by passing auto_instrument:true to the configure method of Splunk::Otel. For example:

require "splunk/otel"

Splunk::Otel.configure(auto_instrument: true)

The gem fetches all instrumentation libraries but only enables those that instrument a dependency in your project. For example, it will fetch opentelemetry-instrumentation-rack but only if the rack gem is included and used in your project will the instrumentation be enabled.

auto_instrument: true also works if individual instrumentation libraries are installed, like the opentelemetry-instrumentation-sinatra gem.

To set configuration of one or more instrumentation libraries a config hash can be passed to use_all:

OpenTelemetry::SDK.configure do |c|
  config = {'OpenTelemetry::Instrumentation::Redis' => { opt: "value" }}
  c.use_all(config)
end

The option enabled can be used to disable individual instrumentation libraries when using opentelemetry-instrumentation-all:

OpenTelemetry::SDK.configure do |c|
  config = {'OpenTelemetry::Instrumentation::Redis' => { enabled: false }}
  c.use_all(config)
end

To enable instrumentation libraries manually, see Manual library instrumentation.

Manual instrumentation

Documentation on how to manually instrument a Ruby application is available in the OpenTelemetry official documentation.

To extend the instrumentation with the OpenTelemetry Instrumentation for Ruby, you have to use a compatible API version.

The Splunk Distribution of OpenTelemetry Ruby is compatible with:

OpenTelemetry API version 1.0.0
OpenTelemetry SDK version 1.0.0

Manual library instrumentation

Instrumentation gems can also be installed and enabled individually. This may be preferred in order to control exactly which gems are fetched when building your project.

Install the instrumentation library by including it in the project's Gemfile. For example, to install the Sinatra instrumentation:

gem "opentelemetry-instrumentation-sinatra", "~> 0.21"

In a block passed to Splunk::Otel.configure configure the SDK to use each of the instrumentation libraries. In the case of the Sinatra instrumentation, the block would look like the following example:

require "splunk/otel"

Splunk::Otel.configure do |c|
  c.use "OpenTelemetry::Instrumentation::Sinatra", { opt: "value" }
end

Real User Monitoring

For Real User Monitoring (RUM) a Rack middleware is provided which will add trace context to the Server-Timing header in the response if there is an active Span. To use the middleware configure Splunk::Otel to use the Rack instrumentation:

Splunk::Otel.configure do |c|
    c.use "OpenTelemetry::Instrumentation::Rack"
end

And add the middleware in Rack::Builder:

Rack::Builder.app do
    use OpenTelemetry::Instrumentation::Rack::Middlewares::TracerMiddleware
    use Splunk::Otel::Rack::RumMiddleware
    run ->(_env) { [200, { "content-type" => "text/plain" }, ["OK"]] }
end

When using ActionPack, which Rails does, the middleware will be added automatically if the Instrumentation Library for ActionPack, "Splunk::Otel::Instrumentation::ActionPack", is used:

Splunk::Otel.configure do |c|
    c.use "OpenTelemetry::Instrumentation::ActionPack"
    c.use "Splunk::Otel::Instrumentation::ActionPack"
end

To disable the response headers being added the environment variable SPLUNK_TRACE_RESPONSE_HEADER_ENABLED can be set to false, or pass trace_response_header_enabled: false to Splunk::Otel.configure.

Configure for use with Smart Agent

This distribution includes the jaeger-thrift-splunk exporter, which is preconfigured to send data to local instance of the SignalFx Smart Agent.

To use the jaeger-thrift-splunk exporter, set theOTEL_TRACES_EXPORTER environment variable to jaeger-thrift-splunk, or append the exporter to the existing values. For example, OTEL_TRACES_EXPORTER=otlp,jaeger-thrift-splunk.

If the SPLUNK_REALM or the OTEL_EXPORTER_JAEGER_ENDPOINT environmental variables are set, the default endpoint is overwritten.

Troubleshooting

For troubleshooting information, see the Troubleshooting documentation.

License

The Splunk OpenTelemetry Ruby distribution is licensed under the terms of the Apache Software License version 2.0. For more details, see the license file.

Copyright 2021 Splunk Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

ℹ️ SignalFx was acquired by Splunk in October 2019. See Splunk SignalFx for more information.