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", "~> 0.1"
or
bundle add splunk-otel --version "~> 0.1"
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.23"
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.19"
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 released 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.