README.md in splunk-otel-0.1.0 vs README.md in splunk-otel-0.2.0

- old
+ new

@@ -34,20 +34,26 @@ - [W3C tracecontext](https://www.w3.org/TR/trace-context/) and [W3C baggage](https://www.w3.org/TR/baggage/) context propagation. - OTLP over HTTP exporter configured to send spans to a locally running [Splunk OpenTelemetry Connector](https://github.com/signalfx/splunk-otel-collector) - (http://localhost:4318). + 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`: ``` ruby gem "splunk-otel", "~> 0.1" ``` +or + +```shell +bundle add splunk-otel --version "~> 0.1" +``` + Configure OpenTelemetry using the `Splunk::Otel` module from `splunk/otel`: ``` ruby require "splunk/otel" ... @@ -67,14 +73,24 @@ 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: + +```ruby +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](docs/advanced-config.md) for information on how to configure the instrumentation. @@ -86,11 +102,11 @@ See [Correlating traces and logs](docs/correlating-traces-and-logs.md) for more information. ## Library instrumentation Supported libraries are listed -[here](https://github.com/open-telemetry/opentelemetry-ruby/tree/main/instrumentation). +[here](https://github.com/open-telemetry/opentelemetry-ruby-contrib/tree/main/instrumentation). The corresponding gems for the instrumentation libraries can be found under the [opentelemetry-ruby](https://rubygems.org/profiles/opentelemetry-ruby) profile on [rubygems.org](https://rubygems.org). ### Automatic instrumentation @@ -101,11 +117,11 @@ the [opentelemetry-instrumentation-all](https://rubygems.org/gems/opentelemetry-instrumentation-all) gem in your Gemfile: ``` ruby -gem "opentelemetry-instrumentation-all", "~> 0.23" +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: @@ -141,23 +157,36 @@ config = {'OpenTelemetry::Instrumentation::Redis' => { enabled: false }} c.use_all(config) end ``` -To enable instrumentation libraries manually, see [Manual instrumentation](#manually-instrument-code). +To enable instrumentation libraries manually, see [Manual library instrumentation](#manual-library-instrumentation). ### Manual instrumentation +Documentation on how to manually instrument a Ruby application is available in the +[OpenTelemetry official documentation](https://opentelemetry.io/docs/instrumentation/ruby/manual/). + +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](https://rubygems.org/gems/opentelemetry-instrumentation-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, @@ -169,10 +198,58 @@ Splunk::Otel.configure do |c| c.use "OpenTelemetry::Instrumentation::Sinatra", { opt: "value" } end ``` +### Real User Monitoring + +For [Real User Monitoring +(RUM)](https://www.splunk.com/en_us/products/real-user-monitoring.html) a +[Rack](https://github.com/rack/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: + +``` ruby +Splunk::Otel.configure do |c| + c.use "OpenTelemetry::Instrumentation::Rack" +end +``` + +And add the middleware in `Rack::Builder`: + +``` ruby +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](https://rubygems.org/gems/actionpack/), which Rails +does, the middleware will be added automatically if the Instrumentation Library +for ActionPack, "Splunk::Otel::Instrumentation::ActionPack", is used: + +``` ruby +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](https://github.com/signalfx/signalfx-agent). + +To use the `jaeger-thrift-splunk` exporter, set the`OTEL_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](docs/troubleshooting.md) documentation. # License @@ -186,5 +263,7 @@ > 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](https://www.splunk.com/en_us/investor-relations/acquisitions/signalfx.html) for more information.