diff --git a/exporter/otlp/README.md b/exporter/otlp/README.md index 8d5b70e618..55d09b8470 100644 --- a/exporter/otlp/README.md +++ b/exporter/otlp/README.md @@ -16,15 +16,17 @@ Generally, *libraries* that produce telemetry data should avoid depending direct ### 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`. @@ -93,6 +95,48 @@ The OpenTelemetry Ruby gems are maintained by the OpenTelemetry-Ruby special int 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.* . 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 @@ -103,3 +147,8 @@ The `opentelemetry-exporter-otlp` gem is distributed under the Apache 2.0 licens [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 diff --git a/exporter/otlp/Rakefile b/exporter/otlp/Rakefile index 5aaabc603d..ce1edbd6e9 100644 --- a/exporter/otlp/Rakefile +++ b/exporter/otlp/Rakefile @@ -29,23 +29,21 @@ else task default: %i[test rubocop yard] end +# https://github.com/open-telemetry/opentelemetry-proto/tree/v0.20.0 PROTO_VERSION = 'v0.20.0' -PROTOBUF_FILES = [ - 'collector/logs/v1/logs_service.proto', - 'collector/metrics/v1/metrics_service.proto', - 'collector/trace/v1/trace_service.proto', - 'common/v1/common.proto', - 'logs/v1/logs.proto', - 'metrics/v1/metrics.proto', - 'resource/v1/resource.proto', - 'trace/v1/trace.proto', - 'trace/v1/trace_config.proto' -].freeze - -task :update_protobuf do - system("git clone -b #{PROTO_VERSION} https://github.com/open-telemetry/opentelemetry-proto") - PROTOBUF_FILES.each do |file| - system("protoc --ruby_out=lib/ --proto_path=opentelemetry-proto opentelemetry/proto/#{file}") + +namespace :protobuf do + task :clean do + FileUtils.rm_rf('lib/opentelemetry/proto') + FileUtils.rm_rf('opentelemetry-proto') + end + + desc "Generate Ruby Source files from OTel Proto Version #{PROTO_VERSION}" + task generate: [:clean] do + system("git clone -b #{PROTO_VERSION} https://github.com/open-telemetry/opentelemetry-proto", exception: true) + Dir['opentelemetry-proto/opentelemetry/proto/**/*.proto'].each do |file| + system("protoc --ruby_out=lib/ --proto_path=opentelemetry-proto #{file.gsub('opentelemetry-proto/', '')}", exception: true) + end + FileUtils.rm_rf('opentelemetry-proto') end - system('rm -rf opentelemetry-proto') end diff --git a/exporter/otlp/lib/opentelemetry/proto/collector/logs/v1/logs_service_services_pb.rb b/exporter/otlp/lib/opentelemetry/proto/collector/logs/v1/logs_service_services_pb.rb deleted file mode 100644 index 98712758d0..0000000000 --- a/exporter/otlp/lib/opentelemetry/proto/collector/logs/v1/logs_service_services_pb.rb +++ /dev/null @@ -1,50 +0,0 @@ -# Generated by the protocol buffer compiler. DO NOT EDIT! -# Source: opentelemetry/proto/collector/logs/v1/logs_service.proto for package 'opentelemetry.proto.collector.logs.v1' -# Original file comments: -# Copyright 2020, OpenTelemetry Authors -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# 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. -# - -require 'grpc' -require 'opentelemetry/proto/collector/logs/v1/logs_service_pb' - -module Opentelemetry - module Proto - module Collector - module Logs - module V1 - module LogsService - # Service that can be used to push logs between one Application instrumented with - # OpenTelemetry and an collector, or between an collector and a central collector (in this - # case logs are sent/received to/from multiple Applications). - class Service - - include ::GRPC::GenericService - - self.marshal_class_method = :encode - self.unmarshal_class_method = :decode - self.service_name = 'opentelemetry.proto.collector.logs.v1.LogsService' - - # For performance reasons, it is recommended to keep this RPC - # alive for the entire life of the application. - rpc :Export, ::Opentelemetry::Proto::Collector::Logs::V1::ExportLogsServiceRequest, ::Opentelemetry::Proto::Collector::Logs::V1::ExportLogsServiceResponse - end - - Stub = Service.rpc_stub_class - end - end - end - end - end -end diff --git a/exporter/otlp/lib/opentelemetry/proto/collector/metrics/v1/metrics_service_services_pb.rb b/exporter/otlp/lib/opentelemetry/proto/collector/metrics/v1/metrics_service_services_pb.rb deleted file mode 100644 index 13be8cb414..0000000000 --- a/exporter/otlp/lib/opentelemetry/proto/collector/metrics/v1/metrics_service_services_pb.rb +++ /dev/null @@ -1,50 +0,0 @@ -# Generated by the protocol buffer compiler. DO NOT EDIT! -# Source: opentelemetry/proto/collector/metrics/v1/metrics_service.proto for package 'opentelemetry.proto.collector.metrics.v1' -# Original file comments: -# Copyright 2019, OpenTelemetry Authors -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# 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. -# - -require 'grpc' -require 'opentelemetry/proto/collector/metrics/v1/metrics_service_pb' - -module Opentelemetry - module Proto - module Collector - module Metrics - module V1 - module MetricsService - # Service that can be used to push metrics between one Application - # instrumented with OpenTelemetry and a collector, or between a collector and a - # central collector. - class Service - - include ::GRPC::GenericService - - self.marshal_class_method = :encode - self.unmarshal_class_method = :decode - self.service_name = 'opentelemetry.proto.collector.metrics.v1.MetricsService' - - # For performance reasons, it is recommended to keep this RPC - # alive for the entire life of the application. - rpc :Export, ::Opentelemetry::Proto::Collector::Metrics::V1::ExportMetricsServiceRequest, ::Opentelemetry::Proto::Collector::Metrics::V1::ExportMetricsServiceResponse - end - - Stub = Service.rpc_stub_class - end - end - end - end - end -end diff --git a/exporter/otlp/lib/opentelemetry/proto/collector/trace/v1/trace_service_services_pb.rb b/exporter/otlp/lib/opentelemetry/proto/collector/trace/v1/trace_service_services_pb.rb deleted file mode 100644 index aa9a167155..0000000000 --- a/exporter/otlp/lib/opentelemetry/proto/collector/trace/v1/trace_service_services_pb.rb +++ /dev/null @@ -1,50 +0,0 @@ -# Generated by the protocol buffer compiler. DO NOT EDIT! -# Source: opentelemetry/proto/collector/trace/v1/trace_service.proto for package 'opentelemetry.proto.collector.trace.v1' -# Original file comments: -# Copyright 2019, OpenTelemetry Authors -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# 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. -# - -require 'grpc' -require 'opentelemetry/proto/collector/trace/v1/trace_service_pb' - -module Opentelemetry - module Proto - module Collector - module Trace - module V1 - module TraceService - # Service that can be used to push spans between one Application instrumented with - # OpenTelemetry and a collector, or between a collector and a central collector (in this - # case spans are sent/received to/from multiple Applications). - class Service - - include ::GRPC::GenericService - - self.marshal_class_method = :encode - self.unmarshal_class_method = :decode - self.service_name = 'opentelemetry.proto.collector.trace.v1.TraceService' - - # For performance reasons, it is recommended to keep this RPC - # alive for the entire life of the application. - rpc :Export, ::Opentelemetry::Proto::Collector::Trace::V1::ExportTraceServiceRequest, ::Opentelemetry::Proto::Collector::Trace::V1::ExportTraceServiceResponse - end - - Stub = Service.rpc_stub_class - end - end - end - end - end -end diff --git a/exporter/otlp/lib/opentelemetry/proto/trace/v1/trace_config_pb.rb b/exporter/otlp/lib/opentelemetry/proto/trace/v1/trace_config_pb.rb deleted file mode 100644 index 540dc2d65d..0000000000 --- a/exporter/otlp/lib/opentelemetry/proto/trace/v1/trace_config_pb.rb +++ /dev/null @@ -1,49 +0,0 @@ -# Generated by the protocol buffer compiler. DO NOT EDIT! -# source: opentelemetry/proto/trace/v1/trace_config.proto - -require 'google/protobuf' - -Google::Protobuf::DescriptorPool.generated_pool.build do - add_file("opentelemetry/proto/trace/v1/trace_config.proto", :syntax => :proto3) do - add_message "opentelemetry.proto.trace.v1.TraceConfig" do - optional :max_number_of_attributes, :int64, 4 - optional :max_number_of_timed_events, :int64, 5 - optional :max_number_of_attributes_per_timed_event, :int64, 6 - optional :max_number_of_links, :int64, 7 - optional :max_number_of_attributes_per_link, :int64, 8 - oneof :sampler do - optional :constant_sampler, :message, 1, "opentelemetry.proto.trace.v1.ConstantSampler" - optional :trace_id_ratio_based, :message, 2, "opentelemetry.proto.trace.v1.TraceIdRatioBased" - optional :rate_limiting_sampler, :message, 3, "opentelemetry.proto.trace.v1.RateLimitingSampler" - end - end - add_message "opentelemetry.proto.trace.v1.ConstantSampler" do - optional :decision, :enum, 1, "opentelemetry.proto.trace.v1.ConstantSampler.ConstantDecision" - end - add_enum "opentelemetry.proto.trace.v1.ConstantSampler.ConstantDecision" do - value :ALWAYS_OFF, 0 - value :ALWAYS_ON, 1 - value :ALWAYS_PARENT, 2 - end - add_message "opentelemetry.proto.trace.v1.TraceIdRatioBased" do - optional :samplingRatio, :double, 1 - end - add_message "opentelemetry.proto.trace.v1.RateLimitingSampler" do - optional :qps, :int64, 1 - end - end -end - -module Opentelemetry - module Proto - module Trace - module V1 - TraceConfig = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("opentelemetry.proto.trace.v1.TraceConfig").msgclass - ConstantSampler = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("opentelemetry.proto.trace.v1.ConstantSampler").msgclass - ConstantSampler::ConstantDecision = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("opentelemetry.proto.trace.v1.ConstantSampler.ConstantDecision").enummodule - TraceIdRatioBased = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("opentelemetry.proto.trace.v1.TraceIdRatioBased").msgclass - RateLimitingSampler = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("opentelemetry.proto.trace.v1.RateLimitingSampler").msgclass - end - end - end -end