README.md in opentelemetry-exporter-otlp-0.26.0 vs README.md in opentelemetry-exporter-otlp-0.26.1

- old
+ new

@@ -14,19 +14,21 @@ 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.4.0 release](https://github.com/open-telemetry/opentelemetry-proto/releases/tag/v0.4.0) of OTLP. +This gem supports the [v0.20.0 release][otel-proto-release] of OTLP. ## How do I get started? Install the gem using: -``` +```console + gem install opentelemetry-sdk gem install opentelemetry-exporter-otlp + ``` Or, if you use [bundler][bundler-home], 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. @@ -91,15 +93,62 @@ ## License The `opentelemetry-exporter-otlp` gem is distributed under the Apache 2.0 license. See [LICENSE][license-github] for more information. +## Working with Proto Definitions +The OTel community maintains a [repository with protobuf definitions][otel-proto-github] that language and collector implementors 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 + +- [`git` 2.41+][git-install] +- [`protoc` 22.5][protoc-install] +- [Ruby 3+][ruby-downloads] + +> :warning: `protoc 23.x` *changes the Ruby code generator to emit a serialized proto instead of a DSL.* <https://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.** + +```ruby + # Rakefile + + # https://github.com/open-telemetry/opentelemetry-proto/tree/v0.20.0 + PROTO_VERSION = `v0.20.0` +``` + +**Generate the Ruby source files using `rake`:** + +```console + +$> bundle exec rake protobuf:generate + +``` + +**Run tests and fix any errors:** + +```console + +$> bundle exec rake test + +``` + +**Commit the chnages and open a PR!** + [opentelemetry-collector-home]: https://opentelemetry.io/docs/collector/about/ [opentelemetry-home]: https://opentelemetry.io [bundler-home]: https://bundler.io [repo-github]: https://github.com/open-telemetry/opentelemetry-ruby [license-github]: https://github.com/open-telemetry/opentelemetry-ruby/blob/main/LICENSE [examples-github]: https://github.com/open-telemetry/opentelemetry-ruby/tree/main/examples [ruby-sig]: https://github.com/open-telemetry/community#ruby-sig [community-meetings]: https://github.com/open-telemetry/community#community-meetings [discussions-url]: https://github.com/open-telemetry/opentelemetry-ruby/discussions +[git-install]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git +[protoc-install]: https://github.com/protocolbuffers/protobuf/releases/tag/v22.5 +[ruby-downloads]: https://www.ruby-lang.org/en/downloads/ +[otel-proto-github]: https://github.com/open-telemetry/opentelemetry-proto +[otel-proto-release]: https://github.com/open-telemetry/opentelemetry-proto/releases/tag/v0.20.0