splunk-otel 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b26ca5033148be9cca92f15da5226356a391db3d3f2da45b144b64381a321b69
-  data.tar.gz: c6a6fbb2e6a784bb149654d77a1736f3aab4ba18827a25000561ea05271bf6a1
+  metadata.gz: fcafe2c8c9d5df1735256ab1d088eba1679b07c55f7790dc1b90f24cce3cfa34
+  data.tar.gz: a161059f434a56f484bb5b7e7c40da09c5333b067b18676bd6ac2c648ee5dbd4
 SHA512:
-  metadata.gz: 9a6156c5569d2dd5a85cbff060c0def7d8fe4c35408b9545b5d1704306bbb945ef0c11273844d9c7ad7fff7079b8b95b3ee3d9101451e4c388bad7c5c0f46bd2
-  data.tar.gz: 56b7fd62c64d001e9e60226e7a119f374734a59d984bf21e47056b19b7ee419a79c059059c5d7982175309654ccaed04694218858952eadb06f1249ba65a31ac
+  metadata.gz: 807de3ed7cd3135b07a65bfc296f6930dfb2904e9b01e5baae0b20aeb1e7a121b6a55064d1d38ab633644b6dcb68bb2f0f4e567ca95e9b27bc47d98dee6d59b0
+  data.tar.gz: b30aede6336990f2e73c4d525ec056fe37d63bf0191b865298cd01c89cfbe060f640c2a30645cf7c927702d32e8e4409475e4099a7b0c00b61a95921f241abd3

data/.github/dependabot.yml

@@ -0,0 +1,17 @@
+version: 2
+updates:
+- package-ecosystem: bundler
+  directory: "/"
+  schedule:
+    interval: daily
+  open-pull-requests-limit: 10
+- package-ecosystem: "github-actions"
+  directory: "/"
+  schedule:
+    interval: "weekly"
+    day: "friday"
+- package-ecosystem: "docker"
+  directory: "/examples/rails-7-barebones/"
+  schedule:
+    interval: "weekly"
+    day: "friday"

data/.github/workflows/main.yml

@@ -15,7 +15,7 @@ jobs:
         ruby-version: [3.1, 3.0, 2.7, 2.6]
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
 
       - name: Run Collector
         run: docker-compose up -d
@@ -33,6 +33,8 @@ jobs:
         run: bundle exec rubocop
       - name: Run tests
         run: bundle exec rake test
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v3
       - name: Run basic example e2e test
         run: ruby console.rb
         working-directory: ./examples/basic/
@@ -42,7 +44,16 @@ jobs:
   test-e2e-rails-7-barebones:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - name: Run e2e tests via Docker
         working-directory: ./examples/rails-7-barebones
         run: docker-compose up --build --exit-code-from tester
+
+  linkChecker:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Link Checker
+        uses: lycheeverse/lychee-action@v1.5.0
+        with:
+          fail: true

data/.gitlab-ci.yml

@@ -1,18 +1,31 @@
 image:
   name: "docker-hub.repo.splunkdev.net/ruby:3.1.2"
 
+include:
+  - project: 'ci-cd/templates'
+    ref: master
+    file: '/prodsec/.oss-scan.yml'
+
 stages:
   - build
+  - scan
   - release
 
 build:
   stage: build
+  artifacts:
+    paths:
+      - Gemfile.lock
   script: |
     gem update --system
     bundle install
     bundle exec rubocop
     bundle exec rake test
 
+oss-scan:
+  stage: scan
+  extends: .oss-scan
+
 release:
   stage: release
   rules:

data/.lycheeignore

@@ -0,0 +1,2 @@
+https://docs.splunk.com/Observability/gdi/get-data-in/application/ruby/get-started.html
+http://localhost:4318/

data/.rubocop.yml

@@ -25,3 +25,6 @@ Metrics/AbcSize:
 
 Metrics/MethodLength:
   Max: 15
+
+Metrics/ModuleLength:
+  Max: 105

data/CHANGELOG.md

@@ -7,4 +7,26 @@ and this repository adheres to [Semantic Versioning](https://semver.org/spec/v2.
 
 ## Unreleased
 
+## v0.2.0 - 2022-09-06
 
+### Added
+
+- OpenTelemetry Ruby SDK and API are updated to 1.0
+- [pre-configured support for Smart
+  Agent](https://github.com/signalfx/splunk-otel-ruby/pull/8)
+- [support for SPLUNK_TRACE_RESPONSE_HEADER_ENABLED environment
+  variable](https://github.com/signalfx/splunk-otel-ruby/pull/38)
+  
+## v0.1.0 - 2022-07-27
+
+### Added
+
+- [railtie based RUM Rack instrumentation](https://github.com/signalfx/splunk-otel-ruby/pull/26)
+- [basic example using splunk distro](https://github.com/signalfx/splunk-otel-ruby/pull/20)
+- [example of the most simplified rails setup](https://github.com/signalfx/splunk-otel-ruby/pull/24)
+- [Rack RUM middleware](https://github.com/signalfx/splunk-otel-ruby/pull/23)
+- [splunk.distro.version to resource attributes](https://github.com/signalfx/splunk-otel-ruby/pull/9)
+- [MIGRATING.md docs for migrating from SignalFX Tracing Library](https://github.com/signalfx/splunk-otel-ruby/pull/18)
+- [standard logging correlation formatter](https://github.com/signalfx/splunk-otel-ruby/pull/11)
+- support `SPLUNK_ACCESS_TOKEN` and `SPLUNK_REALM` environment variables for direct
+  to Splunk exporting

data/MIGRATING.md

@@ -1,20 +1,27 @@
 # Migrate from the SignalFx Tracing Library for Ruby
 
-The SignalFx Tracing Library for Ruby is deprecated. Replace it with the
-agent from the Splunk Distribution of OpenTelemetry Ruby.
+The SignalFx Tracing Library for Ruby is scheduled to be deprecated by the end of 2022.
+Replace it with the Splunk Distribution of OpenTelemetry Ruby.
 
-The agent of the Splunk Distribution of OpenTelemetry Ruby is based on
-the OpenTelemetry Instrumentation for Ruby, an open-source project that
-uses the OpenTelemetry API.
-
-Read the following instructions to learn how to migrate to the Splunk
-Ruby OTel agent.
+Splunk Distribution of OpenTelemetry Ruby is based on and compatible with
+the OpenTelemetry Instrumentation for Ruby,
+an open-source project that uses the OpenTelemetry API.
 
 ## Compatibility and requirements
 
 The Splunk Distribution of OpenTelemetry Ruby requires Ruby 2.6 and
 higher.
 
+## Known limitations compared to SignalFx Tracing for Ruby
+
+- Different subset of supported Ruby versions, see previous section
+- Currently no auto-instrumentation for:
+    - `elasticsearch` (<https://github.com/elastic/elasticsearch-ruby>)
+    - `grape` (<https://github.com/ruby-grape/grape>)
+    - `sequel` (<https://github.com/jeremyevans/sequel>)
+
+More details in [OTel instrumentation equivalents](#signalfx-instrumentations-equivalents).
+
 ## Migrate to the Splunk Distribution of OpenTelemetry Ruby
 
 To migrate from the SignalFx Tracing Library for Ruby to the Splunk
@@ -26,6 +33,7 @@ Distribution of OpenTelemetry Ruby, follow these steps:
 
 > Semantic conventions for span names and attributes change when you
 migrate.
+
 ### Remove the SignalFx Tracing Library for Ruby
 
 Follow these steps to remove the tracing library and its dependencies:
@@ -36,26 +44,105 @@ Follow these steps to remove the tracing library and its dependencies:
     gem uninstall signalfx
     ```
 
-2.  Remove `signalfx` from your Gemfile.
+1.  Remove `signalfx` from your Gemfile.
 
-3.  Remove any additional OpenTracing instrumentation packages you
-    installed.
+## Migrate to the Splunk Distribution of OpenTelemetry Ruby
 
-### Deploy the Splunk Ruby agent
+We're currently only testing installation using Bundler with RubyGems as a source.
+[Contact us](mailto:ssg-observability-instrumentals-ruby@splunk.com) if you require a different way of installation.
 
-To install the Splunk Distribution of OpenTelemetry Ruby, see the [README.md](README.md).
+If you installed
+[Smart Agent](https://github.com/signalfx/signalfx-agent)
+to serve as a gateway (traces/metrics data proxy)
+migrate to
+[OpenTelemetry Collector](https://docs.splunk.com/Observability/gdi/opentelemetry/resources.html)
+first, as soon as (if) possible.
 
-### Migrate settings for the Splunk Ruby OTel agent
+### Deploy the Splunk Distribution of OpenTelemetry Ruby
 
-To migrate settings from the SignalFx tracing library to the Splunk
-Distribution of OpenTelemetry Ruby, rename the following environment
-variables:
+To install the Splunk Distribution of OpenTelemetry Ruby, see the [README.md](README.md).
 
-| SignalFx environment variable        | OpenTelemetry environment variable                               |
-|--------------------------------------|------------------------------------------------------------------|
-| `SIGNALFX_ACCESS_TOKEN`              | `SPLUNK_ACCESS_TOKEN`                                            |
-| `SIGNALFX_SERVICE_NAME`              | `OTEL_SERVICE_NAME`                                              |
-| `SIGNALFX_ENDPOINT_URL`              | `OTEL_EXPORTER_JAEGER_ENDPOINT` or `OTEL_EXPORTER_OTLP_ENDPOINT` |
-| `SIGNALFX_RECORDED_VALUE_MAX_LENGTH` | `SPLUNK_MAX_ATTR_LENGTH`                                         |
+### Replace SignalFx / OpenTracing gems with OTel equivalents
+
+1.  Make a list of all `signalfx-*` instrumentation gems from your Gemfile, see
+    [this table](https://github.com/signalfx/signalfx-ruby-tracing#supported-libraries)
+    for a complete list.
+
+1.  Replace them with OpenTelemetry, as per the table below.
+
+1.  Replace any other OpenTracing instrumentation packages you might have installed yourself.
+
+<a name="signalfx-instrumentations-equivalents"></a>
+#### OTel equivalents of SignalFx instrumentation gems
+
+| SignalFx instrumentation name | OTel instrumentation name | notes |
+| ----------------------------- | ------------------------- | ----- |
+| signalfx-activerecord-opentracing | opentelemetry-instrumentation-active_record | |
+| signalfx-elasticsearch-instrumentation | no known equivalents | [open issue in OTel](https://github.com/open-telemetry/opentelemetry-ruby-contrib/issues/8) |
+| signalfx-faraday-instrumentation       | opentelemetry-instrumentation-faraday | |
+| signalfx-grape-instrumentation         | no known equivalents | [open issue in OTel](https://github.com/open-telemetry/opentelemetry-ruby-contrib/issues/9) |
+| signalfgx-mongodb-instrumentation      | opentelemetry-instrumentation-mongo | |
+| signalfx-mysql2-instrumentation        | opentelemetry-instrumentation-mysql2 | |
+| signalfx-nethttp-instrumentation       | opentelemetry-instrumentation-net_http | |
+| signalfx-pg-instrumentation            | opentelemetry-instrumentation-pg | |
+| signalfx-rack-tracer                   | opentelemetry-instrumentation-rack | |
+| signalfx-rails-instrumentation         | opentelemetry-instrumentation-rails | |
+| signalfx-redis-instrumentation         | opentelemetry-instrumentation-redis | |
+| signalfx-restclient-instrumentation    | opentelemetry-instrumentation-restclient | |
+| signalfx-sequel-instrumentation        | no known equivalents | [open issue in OTel](https://github.com/open-telemetry/opentelemetry-ruby-contrib/issues/11) |
+| signalfx-sidekiq-opentracing           | opentelemetry-instrumentation-sidekiq | |
+| signalfx-sinatra-instrumentation       | opentelemetry-instrumentation-sinatra | |
+
+#### OTel equivalents of other Open Tracing instrumentation gems
+
+See the
+[list of all known OTel Ruby instrumentations](https://opentelemetry.io/registry/?language=ruby&component=instrumentation)
+in OpenTelemetry registry.
+
+### Migrate settings for the Splunk Distribution of OpenTelemetry Ruby
+
+1. `SIGNALFX_ENDPOINT_URL` or `ingest_url` configuration parameter
+    - if you installed Smart Agent and can migrate to OpenTelemetry Collector, do that first, then see the point below
+    - if you have OpenTelemetry Collector available up as a sidecar (via `localhost`),
+      and it accepts OTLP on default ports, just remove this setting, we export OTLP to OTel Collector by default
+    - if you need to keep using Smart Agent, you have to set up a jaeger exporter yourself
+    - if you export directly to our backend (without OTel Collector as a proxy),
+      just set `SPLUNK_REALM` to your realm
+      (it's part of the URL, ie. `https://app.<realm>.signalfx.com/`, or `us0` if it's missing)
+
+1. `SIGNALFX_SERVICE_NAME` or `service_name` configuration parameter
+    - to set in environment, use `OTEL_SERVICE_NAME`
+    - to set in code, use `Splunk::Otel.configure(service_name: 'your service name', ...`
+
+1. `SIGNALFX_ACCESS_TOKEN` or `access_token` configuration parameter
+    - to set in environment, use `SPLUNK_ACCESS_TOKEN`
+
+1. `SIGNALFX_SPAN_TAGS` or `span_tags` configuration parameter
+    - to set in environment:
+        - first, you need to rewrite the existing value to the,
+          which has a syntax of comma-separated `<key>=<value>` pairs (e.g. `key1=value1,key2=value2`)
+        - set `OTEL_RESOURCE_ATTRIBUTES` to the new value
+    - to set in code:
+        - call `OpenTelemetry::SDK::Resources::Resource.create` with a `Hash`
+          consisting of your existing key-value pairs
+        - pass the newly created `Resource` to the `resource=` attribute in configuration
+        - for example:
+           ```ruby
+           Splunk::Otel.configure(other_args) do |c|
+             c.resource = OpenTelemetry::SDK::Resources::Resource.create(
+               "key" => "value"
+             )
+             # ...
+           end
+           ```
+
+1. `SIGNALFX_RECORDED_VALUE_MAX_LENGTH`
+    - can be set in environment using `OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT`
+    - see
+      [the list of span limits settings](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/sdk-environment-variables.md#span-limits)
+      to learn more
+
+1. `tracer` configuration parameter
+    - if you need to set its equivalent, open an issue, and tell us about your use case
 
 For more information about Splunk Ruby OTel settings, see [advanced-config.md](docs/advanced-config.md).

data/README.md

@@ -36,7 +36,7 @@ This Splunk distribution comes with the following defaults:
   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.
 
@@ -46,6 +46,12 @@ Install the gem by adding it to your project's `Gemfile`:
 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
@@ -69,10 +75,20 @@ Other resource attributes are not strictly required, but
 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
@@ -88,7 +104,7 @@ See [Correlating traces and logs](docs/correlating-traces-and-logs.md) for more
 ## 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).
@@ -103,7 +119,7 @@ the
 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
@@ -143,10 +159,23 @@ OpenTelemetry::SDK.configure do |c|
 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.
 
@@ -155,7 +184,7 @@ the project's `Gemfile`. For example, to install the
 [Sinatra](https://rubygems.org/gems/opentelemetry-instrumentation-sinatra)
 instrumentation:
 
-``` 
+```
 gem "opentelemetry-instrumentation-sinatra", "~> 0.19"
 ```
 
@@ -171,6 +200,54 @@ Splunk::Otel.configure do |c|
 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.
@@ -188,3 +265,5 @@ file](./LICENSE).
 > 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.

data/docs/advanced-config.md

@@ -2,12 +2,12 @@
 
 ## Trace exporters
 
-| Environment variable              | Default value                    | Support     | Description                                                                                                                              |
-| --------------------------------- | -------                          | ----------- | ---                                                                                                                                      |
-| `OTEL_TRACES_EXPORTER`            | `otlp`                           | Stable      | Select the traces exporter to use. We recommend using the OTLP exporter (`otlp`).
-| `OTEL_EXPORTER_OTLP_ENDPOINT`     | `http://localhost:4318`          | Stable      | The OTLP endpoint to connect to.
+| Environment variable          | Default value           | Support | Description                                                                       |
+|-------------------------------|-------------------------|---------|-----------------------------------------------------------------------------------|
+| `OTEL_TRACES_EXPORTER`        | `otlp`                  | Stable  | Select the traces exporter to use. We recommend using the OTLP exporter (`otlp`). |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://localhost:4318` | Stable  | The OTLP endpoint to connect to.                                                  |
 
-The Splunk Distribution of OpenTelemetry Ruby uses the OTLP traces exporter as
+The Splunk Distribution of OpenTelemetry Ruby uses the HTTP OTLP traces exporter as
 the default setting. For debugging purposes, use the `console` exporter, which writes
 spans directly to the console.
 
@@ -17,20 +17,35 @@ An example of setting an alternate trace exporter:
 export OTEL_TRACES_EXPORTER=console
 ```
 
+Supported values for `OTEL_TRACES_EXPORTER` are `otlp` and
+`jaeger-thrift-splunk`. Only the HTTP version of `otlp` is supported by the
+OpenTelemetry Ruby.
+
 ## Exporting directly to Splunk Observability Cloud
 
 To export traces directly to Splunk Observability Cloud, bypassing the Collector,
 set the `SPLUNK_ACCESS_TOKEN` and `SPLUNK_REALM` environment variables.
 
-| Environment variable                   | Default value | Support     | Description                                                                                                                                          |
-| -------------------------------------- | ------------  | ----------- | ---                                                                                                                                                  |
-| `SPLUNK_ACCESS_TOKEN`                  | unset         | Stable      | Splunk authentication token that lets exporters send data directly to Splunk Observability Cloud. Unset by default. Not required unless you need to send data to the Observability Cloud ingest endpoint. See [Create and manage authentication tokens using Splunk Observability Cloud](https://docs.splunk.com/Observability/admin/authentication-tokens/tokens.html#admin-tokens).                               |
-| `SPLUNK_REALM`                         | us0           | Stable      | The name of your organization’s realm, for example, us0. When you set the realm, traces are sent directly to the ingest endpoint of Splunk Observability Cloud, bypassing the Splunk OpenTelemetry Collector. |
+| Environment variable                   | Config Option                   | Default value | Support | Description                                                                                                                                                                                                                                                                                                                                                                           |
+|----------------------------------------|---------------------------------|---------------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `SPLUNK_ACCESS_TOKEN`                  |                                 | unset         | Stable  | Splunk authentication token that lets exporters send data directly to Splunk Observability Cloud. Unset by default. Not required unless you need to send data to the Observability Cloud ingest endpoint. See [Create and manage authentication tokens using Splunk Observability Cloud](https://docs.splunk.com/Observability/admin/authentication-tokens/tokens.html#admin-tokens). |
+| `SPLUNK_REALM`                         |                                 | unset         | Stable  | The name of your organization’s realm, for example, us0. When you set the realm, traces are sent directly to the ingest endpoint of Splunk Observability Cloud, bypassing the Splunk OpenTelemetry Collector.                                                                                                                                                                         |
+| `SPLUNK_TRACE_RESPONSE_HEADER_ENABLED` | `trace_response_header_enabled` | `True`        | Stable  | Enables adding server trace information to HTTP response headers in Rack middleware.                                                                                                                                                                                                                                                                                                  |
+
+## Exporting to the 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).
+
+| Environment variable            | Config Option | Default value | Support | Description                                                                                                                                                    |
+|---------------------------------|---------------|---------------|---------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `OTEL_EXPORTER_JAEGER_ENDPOINT` |               | unset         | Stable  | The endpoint to export traces using the `jaeger-thrift-splunk` exporter. If set this overrides the default jaeger endpint of `http://127.0.0.1:9080/v1/trace`. |
+
 
 ## Propagators configuration
 
-| Environment variable | Default value        | Support | Description                                                                                        |
-| `OTEL_PROPAGATORS`     | `tracecontext,baggage` | Stable  | Comma-separated list of propagator names to be used. |
+| Environment variable   | Config Option | Default value          | Support | Description                                          |
+| ---------------------- | ------------- | ---------------------- | ------- | ---------------------------------------------------- |
+| `OTEL_PROPAGATORS`     |               | `tracecontext,baggage` | Stable  | Comma-separated list of propagator names to be used.                 |
 
 To keep backward compatibility with manual instrumentation for the SignalFx Ruby Tracing library, set the trace propagator to B3:
 
@@ -38,15 +53,19 @@ To keep backward compatibility with manual instrumentation for the SignalFx Ruby
 export OTEL_PROPAGATORS=b3multi
 ```
 
+
+Supported values for `OTEL_PROPAGATORS` are `tracecontext`, `baggage`, `b3`,
+`b3multi`, `jaeger`, `xray`, `ottrace` and `none`.
+
 ## Trace configuration
 
 | Environment variable      | Config Option         | Default value             | Notes                                                                                                                                                                                                         |
 | ------------------------- | --------------------- | ------------------------- | ----------------------------------------------------------------------                                                                                                                                        |
-| OTEL_SERVICE_NAME                 | service_name          | `unnamed-ruby-service`  | The service name of this Ruby application. |
-| OTEL_RESOURCE_ATTRIBUTES          |                       | unset                     | Comma-separated list of resource attributes added to every reported span. <details><summary>Example</summary>`service.name=my-ruby-service,service.version=3.1,deployment.environment=production`</details> |
-| OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT   |                       | `""` (unlimited)          | Maximum number of attributes per span.  |
-| OTEL_EVENT_ATTRIBUTE_COUNT_LIMIT  |                       | `""` (unlimited)          | Maximum number of attributes per event.  |
-| OTEL_LINK_ATTRIBUTE_COUNT_LIMIT   |                       | `""` (unlimited)          | Maximum number of attributes per link.  |
-| OTEL_SPAN_EVENT_COUNT_LIMIT       |                       | `""` (unlimited)          | Maximum number of events per span. |
-| OTEL_SPAN_LINK_COUNT_LIMIT        |                       | `1000`                    | Maximum number of links per span. |
-| OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT |                       | `12000`                   | Maximum length of strings for span attribute values. Values larger than the limit are truncated. |
+| `OTEL_SERVICE_NAME`                 | `service_name`          | `unnamed-ruby-service`  | The service name of this Ruby application. |
+| `OTEL_RESOURCE_ATTRIBUTES`          |                       | unset                     | Comma-separated list of resource attributes added to every reported span. <details><summary>Example</summary>`service.name=my-ruby-service,service.version=3.1,deployment.environment=production`</details> |
+| `OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT`   |                       | unset (unlimited)          | Maximum number of attributes per span.  |
+| `OTEL_EVENT_ATTRIBUTE_COUNT_LIMIT`  |                       | unset (unlimited)          | Maximum number of attributes per event.  |
+| `OTEL_LINK_ATTRIBUTE_COUNT_LIMIT`   |                       | unset (unlimited)          | Maximum number of attributes per link.  |
+| `OTEL_SPAN_EVENT_COUNT_LIMIT`       |                       | unset (unlimited)          | Maximum number of events per span. |
+| `OTEL_SPAN_LINK_COUNT_LIMIT`        |                       | `1000`                    | Maximum number of links per span. |
+| `OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT` |                       | `12000`                   | Maximum length of strings for span attribute values. Values larger than the limit are truncated. |

data/examples/smart-agent/.gitignore

@@ -0,0 +1 @@
+Gemfile.lock

data/examples/smart-agent/Gemfile

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gem "opentelemetry-exporter-jaeger"
+gem "splunk-otel", path: "../../"

data/examples/smart-agent/docker-compose.yml

@@ -0,0 +1,8 @@
+version: "3"
+services:
+  otel:
+    image: quay.io/signalfx/signalfx-agent:5
+    ports:
+      - 9080:9080
+    volumes:
+      - ./smart-agent-config.yaml:/etc/signalfx/agent.yaml

data/examples/smart-agent/runner.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "rubygems"
+require "bundler/setup"
+Bundler.require(:default)
+
+Splunk::Otel.configure do |configurator|
+  $configurator = configurator # rubocop:disable Style/GlobalVars
+
+  class << configurator
+    def test_shutdown
+      @span_processors.each(&:shutdown)
+    end
+  end
+end
+
+tracer = OpenTelemetry.tracer_provider.tracer("test", "1.0")
+tracer.in_span("test-span") do
+  puts "test-span execution"
+end
+
+$configurator.test_shutdown # rubocop:disable Style/GlobalVars

data/examples/smart-agent/smart-agent-config.yaml

@@ -0,0 +1,5 @@
+signalFxAccessToken: ""
+ingestUrl: "https://ingest.lab0.signalfx.com"
+signalFxRealm: "lab0"
+monitors:
+  - type: trace-forwarder

data/lib/splunk/otel/instrumentation/rack/middleware.rb

@@ -15,7 +15,11 @@ module Splunk
         def call(env)
           status, headers, body = @app.call(env)
 
-          headers = Splunk::Otel::Common.rum_headers(headers)
+          headers = if Splunk::Otel.trace_response_header_enabled
+                      Splunk::Otel::Common.rum_headers(headers)
+                    else
+                      headers
+                    end
 
           [status, headers, body]
         end

data/lib/splunk/otel/proprietary_exporters.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Splunk
+  module Otel
+    OUR_EXPORTERS_KEYS = ["jaeger-thrift-splunk"].freeze
+    private_constant :OUR_EXPORTERS_KEYS
+
+    # internal module for allowing our exporters to be set via ENV
+    module ExporterExtensions
+      def effective_splunk_jaeger_endpoint
+        return "https://ingest.#{ENV["SPLUNK_REALM"]}.signalfx.com/v1/trace" if ENV["SPLUNK_REALM"]
+        return ENV["OTEL_EXPORTER_JAEGER_ENDPOINT"] if ENV["OTEL_EXPORTER_JAEGER_ENDPOINT"]
+
+        "http://127.0.0.1:9080/v1/trace"
+      end
+
+      def wrapped_exporters_from_env
+        original_env_value = ENV.fetch("OTEL_TRACES_EXPORTER", "otlp")
+        exporters_keys = original_env_value.split(",").map(&:strip)
+        non_proprietary_exporters_keys = exporters_keys - OUR_EXPORTERS_KEYS
+
+        ENV["OTEL_TRACES_EXPORTER"] = non_proprietary_exporters_keys.join(",")
+        original_exporters = super
+        ENV["OTEL_TRACES_EXPORTER"] = original_env_value
+
+        original_exporters + proprietary_exporters(exporters_keys)
+      end
+
+      def proprietary_exporters(exporters_keys)
+        (exporters_keys & OUR_EXPORTERS_KEYS).map do |exporter_key|
+          case exporter_key
+          when "jaeger-thrift-splunk"
+            args = {
+              endpoint: effective_splunk_jaeger_endpoint
+            }
+            fetch_exporter_with_args("jaeger-thrift-splunk", "OpenTelemetry::Exporter::Jaeger::CollectorExporter",
+                                     **args)
+          end
+        end.compact
+      end
+
+      def fetch_exporter_with_args(name, class_name, **args)
+        # TODO: warn if jaeger exporter gem is not present
+        exporter = Kernel.const_get(class_name).new(**args)
+        OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new exporter
+      rescue NameError
+        OpenTelemetry.logger.warn "The #{name} exporter cannot be configured" \
+                                  "- please add opentelemetry-exporter-#{name} to your Gemfile" \
+                                  ", spans will not be exported.."
+        nil
+      end
+    end
+  end
+end

data/lib/splunk/otel/version.rb

@@ -2,6 +2,6 @@
 
 module Splunk
   module Otel
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

data/lib/splunk/otel.rb

@@ -1,18 +1,22 @@
 # frozen_string_literal: true
 
-require_relative "otel/version"
 require "opentelemetry/sdk"
-
-# FIXME: without this, otlp doesn't work out-of-the-box
 require "opentelemetry-exporter-otlp"
 
+require_relative "otel/version"
+require_relative "otel/proprietary_exporters"
+
 module Splunk
   # main module for application startup configuration
-  module Otel
+  module Otel # rubocop:disable Metrics/ModuleLength
     # custom exception types in this gem must inherit from Splunk::Otel::Error
     # this allows the user to rescue a generic exception type to catch all exceptions
     class Error < StandardError; end
 
+    attr_reader(:trace_response_header_enabled)
+
+    @trace_response_header_enabled = true
+
     # Configures the OpenTelemetry SDK and instrumentation with Splunk defaults.
     #
     # @yieldparam [Configurator] configurator Yields a configurator to the
@@ -49,21 +53,25 @@ module Splunk
     #       c.use_all
     #     end
     def configure(service_name: ENV.fetch("OTEL_SERVICE_NAME", "unnamed-ruby-service"),
-                  auto_instrument: false)
-      set_default_propagators
-      set_access_token_header
-      set_default_exporter
-      set_default_span_limits
+                  auto_instrument: false,
+                  trace_response_header_enabled: ENV.fetch("SPLUNK_TRACE_RESPONSE_HEADER_ENABLED", "true"))
+      @trace_response_header_enabled = to_boolean(trace_response_header_enabled)
+
+      set_defaults
 
       # run SDK's setup function
-      OpenTelemetry::SDK.configure do |c|
-        c.service_name = service_name
-        c.resource = OpenTelemetry::SDK::Resources::Resource.create(
+      OpenTelemetry::SDK.configure do |configurator|
+        class << configurator
+          include Splunk::Otel::ExporterExtensions
+        end
+
+        configurator.service_name = service_name
+        configurator.resource = OpenTelemetry::SDK::Resources::Resource.create(
           "splunk.distro.version" => Splunk::Otel::VERSION
         )
 
-        c.use_all if auto_instrument
-        yield c if block_given?
+        configurator.use_all if auto_instrument
+        yield configurator if block_given?
       end
 
       # set span limits to GDI defaults if not set by the user
@@ -72,6 +80,13 @@ module Splunk
       verify_service_name
     end
 
+    def set_defaults
+      set_default_propagators
+      set_access_token_header
+      set_default_exporter
+      set_default_span_limits
+    end
+
     # verify `service.name` is set and print a warning if it is still the default
     def verify_service_name
       provider_resource = OpenTelemetry.tracer_provider.instance_variable_get(:@resource)
@@ -151,6 +166,20 @@ module Splunk
       end
     end
 
+    def to_boolean(val)
+      # val could already be a boolean so just return the value if it is already
+      # true or false
+      case val
+      when true then true
+      when false then false
+      else
+        !%w[false
+            no
+            f
+            0].include?(val.strip.downcase)
+      end
+    end
+
     def service_name_warning
       <<~WARNING
         service.name attribute is not set, your service is unnamed and will be difficult to identify.
@@ -161,7 +190,8 @@ module Splunk
 
     module_function :configure, :gdi_span_limits, :set_default_propagators, :set_default_exporter,
                     :verify_service_name, :service_name_warning, :default_env_vars,
-                    :set_default_span_limits, :set_access_token_header, :set_endpoint
+                    :set_default_span_limits, :set_access_token_header, :set_endpoint,
+                    :to_boolean, :trace_response_header_enabled, :set_defaults
   end
 end
 

data/splunk-otel.gemspec

@@ -43,7 +43,8 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "opentelemetry-instrumentation-action_pack", "~> 0.2.0"
   spec.add_development_dependency "opentelemetry-instrumentation-rack", "~> 0.21"
   spec.add_development_dependency "rack", "~> 2.2"
-  spec.add_development_dependency "rack-test", "~> 1.1"
+  spec.add_development_dependency "rack-test", "~> 2.0"
+  spec.add_development_dependency "simplecov-cobertura", "~> 2.1.0"
 
   spec.metadata = {
     "rubygems_mfa_required" => "true"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: splunk-otel
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Splunk
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-07-27 00:00:00.000000000 Z
+date: 2022-09-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: opentelemetry-api
@@ -226,14 +226,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.1'
+        version: '2.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.1'
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov-cobertura
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.1.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.1.0
 description: 
 email:
 - splunk-oss@splunk.com
@@ -242,9 +256,11 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".github/CODEOWNERS"
+- ".github/dependabot.yml"
 - ".github/workflows/main.yml"
 - ".gitignore"
 - ".gitlab-ci.yml"
+- ".lycheeignore"
 - ".rubocop.yml"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
@@ -277,6 +293,11 @@ files:
 - examples/rails-7-barebones/docker-compose.yml
 - examples/rails-7-barebones/tests-e2e/rails_7_barebones_test.rb
 - examples/rails-7-barebones/wait-for.sh
+- examples/smart-agent/.gitignore
+- examples/smart-agent/Gemfile
+- examples/smart-agent/docker-compose.yml
+- examples/smart-agent/runner.rb
+- examples/smart-agent/smart-agent-config.yaml
 - lib/splunk/otel.rb
 - lib/splunk/otel/common.rb
 - lib/splunk/otel/instrumentation/action_pack.rb
@@ -286,6 +307,7 @@ files:
 - lib/splunk/otel/instrumentation/rack.rb
 - lib/splunk/otel/instrumentation/rack/middleware.rb
 - lib/splunk/otel/logging.rb
+- lib/splunk/otel/proprietary_exporters.rb
 - lib/splunk/otel/version.rb
 - scripts/install-release-deps.sh
 - scripts/release.sh