OpenTelemetry Ruby

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 gem:

gem install opentelemetry-api
gem install opentelemetry-sdk

or via Bundler by adding the following to your Gemfile:

gem 'opentelemetry-api'
gem 'opentelemetry-sdk'

followed by:

bundle install

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

Developer Setup

Install Docker and Docker Compose for your operating system
Get the latest code for the project
Build the opentelemetry/opentelemetry-ruby image
- docker-compose build
- This makes the image available locally
API:
1. Install dependencies
  - docker-compose run api bundle install
2. Run the tests
  - docker-compose run api bundle exec rake test
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.4.0		April 16 2020
Tracing SDK	Alpha v0.4.0		April 16 2020
Trace Context Propagation	Alpha v0.4.0		April 16 2020
Jaeger Trace Exporter	Alpha v0.4.0		April 16 2020
Correlation Context Propagation	Alpha v0.4.0		April 16 2020
Metrics API	Unknown	Unknown	Unknown
Metrics SDK	Unknown	Unknown	Unknown
Prometheus Metrics Exporter	Unknown	Unknown	Unknown
OpenTracing Bridge	Unknown	Unknown	Unknown
Zipkin Trace Exporter	Unknown	Unknown	Unknown
OpenCensus Bridge	Unknown	Unknown	Unknown
Resource Auto-detection (GCP)	Alpha v0.5.0	July 3 2020
Concurrent Ruby Instrumentation	Alpha v0.4.0		April 16 2020
Ethon Instrumentation	Alpha v0.4.0		April 16 2020
Excon Instrumentation	Alpha v0.4.0		April 16 2020
Faraday Instrumentation	Alpha v0.4.0		April 16 2020
MySQL2 Instrumentation	Alpha v0.5.0	July 3 2020
Net::HTTP Instrumentation	Alpha v0.4.0		April 16 2020
Rack Instrumentation	Alpha v0.4.0		April 16 2020
Redis Instrumentation	Alpha v0.4.0		April 16 2020
Restclient Instrumentation	Alpha v0.4.0		April 16 2020
Sinatra Instrumentation	Alpha v0.4.1		June 24 2020
Sidekiq Instrumentation	Alpha v0.4.0		April 16 2020
All Instrumentation Convenience	Alpha v0.4.1		June 24 2020

Release Process

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

Make sure the library's VERSION constant matches the version to be released. This constant is defined in the library's version.rb file.
Add an entry to the library's CHANGELOG.md.
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.
Push the tag directly to Github.
See here for special instructions for publishing the opentelemetry-instrumentation-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.

kbogtob / opentelemetry-ruby Goto Github PK