+
opentelemetry-exporter-otlp
+
+
The opentelemetry-exporter-otlp
gem provides an OTLP exporter for OpenTelemetry for Ruby. Using opentelemetry-exporter-otlp
, an application can configure OpenTelemetry to export collected tracing data to the OpenTelemetry Collector.
+
+
What is OpenTelemetry?
+
+
OpenTelemetry is an open source observability framework, providing a general-purpose API, SDK, and related tools required for the instrumentation of cloud-native software, frameworks, and libraries.
+
+
OpenTelemetry provides a single set of APIs, libraries, agents, and collector services to capture distributed traces and metrics from your application. You can analyze them using Prometheus, Jaeger, and other observability tools.
+
+
How does this gem fit in?
+
+
The opentelemetry-exporter-otlp
gem is a plugin that provides OTLP export. To export to the OpenTelemetry Collector, an application can include this gem along with opentelemetry-sdk
, and configure the SDK
to use the provided OTLP exporter as a span processor.
+
+
Generally, libraries that produce telemetry data should avoid depending directly on specific exporter, deferring that choice to the application developer.
+
+
Supported protocol version
+
+
This gem supports the v0.20.0 release of OTLP.
+
+
How do I get started?
+
+
Install the gem using:
+
+
+gem install opentelemetry-sdk
+gem install opentelemetry-exporter-otlp
+
+
+
Or, if you use bundler, include opentelemetry-sdk
in your Gemfile
.
+
+
Then, configure the SDK to use the OTLP exporter as a span processor, and use the OpenTelemetry interfaces to produces traces and other information. Following is a basic example.
+
+
require 'opentelemetry/sdk'
+require 'opentelemetry/exporter/otlp'
+
+
+OpenTelemetry::SDK.configure
+
+tracer_provider = OpenTelemetry.tracer_provider
+tracer = tracer_provider.tracer('my_app_or_gem', '0.1.0')
+
+tracer.in_span('foo') do |span|
+ span.set_attribute('platform', 'osx')
+ span.add_event('event in bar')
+ tracer.in_span('bar') do |child_span|
+ pp child_span
+ end
+end
+
+tracer_provider.shutdown
+
+
+
For additional examples, see the examples on github.
+
+
+
+
The collector exporter can be configured explicitly in code, or via environment variables as shown above. The configuration parameters, environment variables, and defaults are shown below.
+
+
| Parameter | Environment variable | Default | |—————————| ——————————————– | ———————————– | | endpoint:
| OTEL_EXPORTER_OTLP_ENDPOINT
| "http://localhost:4318/v1/traces"
| | certificate_file:
| OTEL_EXPORTER_OTLP_CERTIFICATE
| | | client_certificate_file
| OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE
| | | client_key_file
| OTEL_EXPORTER_OTLP_CLIENT_KEY
| | | headers:
| OTEL_EXPORTER_OTLP_HEADERS
| | | compression:
| OTEL_EXPORTER_OTLP_COMPRESSION
| "gzip"
| | timeout:
| OTEL_EXPORTER_OTLP_TIMEOUT
| 10
| | ssl_verify_mode:
| OTEL_RUBY_EXPORTER_OTLP_SSL_VERIFY_PEER
or | OpenSSL::SSL:VERIFY_PEER
| | | OTEL_RUBY_EXPORTER_OTLP_SSL_VERIFY_NONE
| |
+
+
ssl_verify_mode:
parameter values should be flags for server certificate verification: OpenSSL::SSL:VERIFY_PEER
and OpenSSL::SSL:VERIFY_NONE
are acceptable. These values can also be set using the appropriately named environment variables as shown where VERIFY_PEER
will take precedence over VERIFY_NONE
. Please see the Net::HTTP docs for more information about these flags.
+
+
How can I get involved?
+
+
The opentelemetry-exporter-otlp
gem source is on github, along with related gems including opentelemetry-sdk
.
+
+
The OpenTelemetry Ruby gems are maintained by the OpenTelemetry-Ruby special interest group (SIG). You can get involved by joining us in GitHub Discussions or attending our weekly meeting. See the meeting calendar for dates and times. For more information on this and other language SIGs, see the OpenTelemetry community page.
+
+
License
+
+
The opentelemetry-exporter-otlp
gem is distributed under the Apache 2.0 license. See LICENSE for more information.
+
+
Working with Proto Definitions
+
+
The OTel community maintains a repository with protobuf definitions that language and collector implementers use to generate code.
+
+
Maintainers are expected to keep up to date with the latest version of protos. This guide will provide you with step-by-step instructions on updating the OTLP Exporter gem with the latest definitions.
+
+
System Requirements
+
+
+
+:warning: protoc 23.x
changes the Ruby code generator to emit a serialized proto instead of a DSL. protobuf.dev/news/2023-04-20/. Please ensure you use protoc
version 22.x
in order to ensure we remain compatible with versions of protobuf prior to google-protobuf
gem 3.18
.
+
+
+
Upgrade Proto Definitions
+
+
Update the target otel-proto version in the Rakefile
that matches a release tag
in the proto repo, e.g.
+
+
+ PROTO_VERSION = `v0.20.0`
+
+
+
Generate the Ruby source files using rake
:
+
+
+$> bundle exec rake protobuf:generate
+
+
+
Run tests and fix any errors:
+
+
+$> bundle exec rake test
+
+
+
Commit the changes and open a PR!
+