OpenTelemetry Ruby

The Ruby OpenTelemetry client.

Contributing

We'd love your help! Use tags good first issue and help wanted to get started with the project.

The Ruby special interest group (SIG) meets regularly. See the OpenTelemetry community page repo for information on this and other language SIGs.

Approvers (@open-telemetry/ruby-approvers):

• Vlad Gorodetsky, Shopify
• Yoshinori Kawasaki, Wantedly
• Don Morrison, Mutations

Find more about the approver role in community repository.

Maintainers (@open-telemetry/ruby-maintainers):

• Francis Bogsanyi, Shopify
• Matthew Wear, LightStep
• Daniel Azuma, Google

Find more about the maintainer role in community repository.

Installation

This repository includes multiple installable packages. The opentelemetry-api package includes abstract classes and no-op implementations that comprise the OpenTelemetry API following the specification. The opentelemetry-sdk package is the reference implementation of the API.

Libraries that produce telemetry data should only depend on opentelemetry-api, and defer the choice of the SDK to the application developer. Applications may depend on opentelemetry-sdk or another package that implements the API.

Please note that this library is currently in alpha, and shouldn't be used in production environments.

The API and SDK packages are available on RubyGems.org, and can be installed via bundle:

bundle install opentelemetry-api
bundle install opentelemetry-sdk

To install development versions of these packages, follow the "Developer Setup" section (below).

Developer Setup

1. Install Docker and Docker Compose for your operating system
2. Get the latest code for the project
3. Build the opentelemetry/opentelemetry-ruby image
   • docker-compose build
   • This makes the image available locally
4. API:
   1. Install dependencies
      • docker-compose run api bundle install
   2. Run the tests
      • docker-compose run api bundle exec rake test
5. SDK:
   1. Install dependencies
      • docker-compose run sdk bundle install
   2. Run the tests for the sdk
      • docker-compose run sdk bundle exec rake test

Docker Services

We use Docker Compose to configure and build services used in development and testing. See docker-compose.yml for specific configuration details.

The services provided are:

• app - main container environment scoped to the /app directory. Used primarily to build and tag the opentelemetry/opentelemetry-ruby:latest image.
• api - convenience environment scoped to the api gem in the /app/api directory.
• sdk - convenience environment scoped to the sdk gem in the /app/sdk directory.

Quick Start

require 'opentelemetry/sdk'

# Configure the sdk with default export and context propagation formats
# see SDK#configure for customizing the setup
OpenTelemetry::SDK.configure

# To start a trace you need to get a Tracer from the TracerProvider
tracer = OpenTelemetry.tracer_provider.tracer('my_app_or_gem', '0.1.0')

# create a span
tracer.in_span('foo') do |span|
  # set an attribute
  span.set_attribute('platform', 'osx')
  # add an event
  span.add_event(name: 'event in bar')
  # create bar as child of foo
  tracer.in_span('bar') do |child_span|
    # inspect the span
    pp child_span
  end
end

See the API Documentation for more detail, and the opentelemetry examples for a complete example including context propagation.

Release Schedule

OpenTelemetry Ruby is under active development. Below is the release schedule for the Ruby library. The first version of the release isn't guaranteed to conform to a specific version of the specification, and future releases will not attempt to maintain backward compatibility with the alpha release.

Component	Version	Target Date	Release Date
Tracing API	Alpha v0.2.0	September 30 2019	November 13 2019
Tracing SDK	Alpha v0.2.0	September 30 2019	November 13 2019
Trace Context Propagation	Alpha v0.2.0	September 30 2019	November 13 2019
Jaeger Trace Exporter	Alpha v0.2.0	September 30 2019	November 13 2019
Metrics API	Alpha v0.3.0	February 24 2020	Unknown
Metrics SDK	Alpha v0.3.0	February 24 2020	Unknown
Prometheus Metrics Exporter	Alpha v0.3.0	February 24 2020	Unknown
Correlation Context Propagation	Alpha v0.3.0	February 24 2020	Unknown
OpenTracing Bridge	Alpha v0.3.0	February 24 2020	Unknown
Zipkin Trace Exporter	Unknown	Unknown	Unknown
OpenCensus Bridge	Unknown	Unknown	Unknown

Release Process

To perform a release of one of the OpenTelemetry Rubygems, follow these steps. Only a maintainer may perform a release.

1. Make sure the library's VERSION constant matches the version to be released. This constant is defined in the library's version.rb file.
2. Add an entry to the library's CHANGELOG.md.
3. Tag the commit to be released. The tag must be of the form: {library-name}/v{version}. For example, to release opentelemetry-api version 1.2.3, create the tag opentelemetry-api/v1.2.3.
4. Push the tag directly to Github.
5. See here for special instructions for publishing the opentelemetry-adapters-all gem.

After the tag is pushed, CircleCI will run the release workflow. This workflow includes one final run of the unit tests, followed by the release script itself.

The CircleCI project includes two environment variables that control the release process.

• OPENTELEMETRY_RUBYGEMS_API_KEY contains the API key used to authenticate with Rubygems for release.
• OPENTELEMETRY_RELEASES_ENABLED controls whether releases are enabled. If set to true, releases are performed normally. If set to false or unset, the release pipeline will execute, but the final gem push is disabled.

Useful links

• For more information on OpenTelemetry, visit: https://opentelemetry.io/
• For help or feedback on this project, join us on gitter.

License

Apache 2.0 - See LICENSE for more information.