diff --git a/.github/workflows/ci-instrumentation-with-services.yml b/.github/workflows/ci-instrumentation-with-services.yml index f919817f5..7e72729d0 100644 --- a/.github/workflows/ci-instrumentation-with-services.yml +++ b/.github/workflows/ci-instrumentation-with-services.yml @@ -24,6 +24,7 @@ jobs: - mysql2 - pg - que + - racecar - rdkafka - redis - resque @@ -61,6 +62,7 @@ jobs: [[ "${{ matrix.gem }}" == "mysql2" ]] && echo "skip=true" >> $GITHUB_OUTPUT [[ "${{ matrix.gem }}" == "pg" ]] && echo "skip=true" >> $GITHUB_OUTPUT [[ "${{ matrix.gem }}" == "que" ]] && echo "skip=true" >> $GITHUB_OUTPUT + [[ "${{ matrix.gem }}" == "racecar" ]] && echo "skip=true" >> $GITHUB_OUTPUT [[ "${{ matrix.gem }}" == "rdkafka" ]] && echo "skip=true" >> $GITHUB_OUTPUT [[ "${{ matrix.gem }}" == "redis" ]] && echo "skip=true" >> $GITHUB_OUTPUT [[ "${{ matrix.gem }}" == "resque" ]] && echo "skip=true" >> $GITHUB_OUTPUT diff --git a/.toys/.data/releases.yml b/.toys/.data/releases.yml index 1d165f006..a8dbbb36d 100644 --- a/.toys/.data/releases.yml +++ b/.toys/.data/releases.yml @@ -31,6 +31,10 @@ commit_lint: # * changelog_path: Path to CHANGLEOG.md relative to the gem directory. # (Required only if it is not in the expected location.) gems: + - name: opentelemetry-instrumentation-racecar + directory: instrumentation/racecar + version_constant: [OpenTelemetry, Instrumentation, Racecar, VERSION] + - name: opentelemetry-instrumentation-rake directory: instrumentation/rake version_constant: [OpenTelemetry, Instrumentation, Rake, VERSION] diff --git a/instrumentation/all/Gemfile b/instrumentation/all/Gemfile index af6379075..da7318213 100644 --- a/instrumentation/all/Gemfile +++ b/instrumentation/all/Gemfile @@ -8,4 +8,5 @@ source 'https://rubygems.org' gemspec +gem 'opentelemetry-instrumentation-racecar', path: '../racecar' gem 'opentelemetry-instrumentation-rake', path: '../rake' diff --git a/instrumentation/all/lib/opentelemetry/instrumentation/all.rb b/instrumentation/all/lib/opentelemetry/instrumentation/all.rb index 56d377e25..71abefca9 100644 --- a/instrumentation/all/lib/opentelemetry/instrumentation/all.rb +++ b/instrumentation/all/lib/opentelemetry/instrumentation/all.rb @@ -29,6 +29,7 @@ require 'opentelemetry-instrumentation-net_http' require 'opentelemetry-instrumentation-pg' require 'opentelemetry-instrumentation-que' +require 'opentelemetry-instrumentation-racecar' require 'opentelemetry-instrumentation-rack' require 'opentelemetry-instrumentation-rails' require 'opentelemetry-instrumentation-rake' diff --git a/instrumentation/all/opentelemetry-instrumentation-all.gemspec b/instrumentation/all/opentelemetry-instrumentation-all.gemspec index 92b2b1c05..1e5ef4587 100644 --- a/instrumentation/all/opentelemetry-instrumentation-all.gemspec +++ b/instrumentation/all/opentelemetry-instrumentation-all.gemspec @@ -46,6 +46,7 @@ Gem::Specification.new do |spec| spec.add_dependency 'opentelemetry-instrumentation-net_http', '~> 0.21.0' spec.add_dependency 'opentelemetry-instrumentation-pg', '~> 0.22.1' spec.add_dependency 'opentelemetry-instrumentation-que', '~> 0.5.0' + spec.add_dependency 'opentelemetry-instrumentation-racecar', '~> 0.1.0' spec.add_dependency 'opentelemetry-instrumentation-rack', '~> 0.21.1' spec.add_dependency 'opentelemetry-instrumentation-rails', '~> 0.23.0' spec.add_dependency 'opentelemetry-instrumentation-rake', '~> 0.1.0' diff --git a/instrumentation/racecar/.rubocop.yml b/instrumentation/racecar/.rubocop.yml new file mode 100644 index 000000000..2d18e24ae --- /dev/null +++ b/instrumentation/racecar/.rubocop.yml @@ -0,0 +1,5 @@ +inherit_from: ../.rubocop-examples.yml + +Naming/FileName: + Exclude: + - "lib/opentelemetry-instrumentation-racecar.rb" diff --git a/instrumentation/racecar/.yardopts b/instrumentation/racecar/.yardopts new file mode 100644 index 000000000..dd4d77560 --- /dev/null +++ b/instrumentation/racecar/.yardopts @@ -0,0 +1,9 @@ +--no-private +--title=OpenTelemetry Racecar Instrumentation +--markup=markdown +--main=README.md +./lib/opentelemetry/instrumentation/**/*.rb +./lib/opentelemetry/instrumentation.rb +- +README.md +CHANGELOG.md diff --git a/instrumentation/racecar/Appraisals b/instrumentation/racecar/Appraisals new file mode 100644 index 000000000..fdef7f748 --- /dev/null +++ b/instrumentation/racecar/Appraisals @@ -0,0 +1,13 @@ +# frozen_string_literal: true + +# Copyright The OpenTelemetry Authors +# +# SPDX-License-Identifier: Apache-2.0 + +appraise 'racecar-2.7' do + gem 'racecar', '~> 2.7.0' +end + +appraise 'racecar-2.8' do + gem 'racecar', '~> 2.8.2' +end diff --git a/instrumentation/racecar/CHANGELOG.md b/instrumentation/racecar/CHANGELOG.md new file mode 100644 index 000000000..97a90eeb4 --- /dev/null +++ b/instrumentation/racecar/CHANGELOG.md @@ -0,0 +1 @@ +# Release History: opentelemetry-instrumentation-racecar diff --git a/instrumentation/racecar/Gemfile b/instrumentation/racecar/Gemfile new file mode 100644 index 000000000..b4aa971cf --- /dev/null +++ b/instrumentation/racecar/Gemfile @@ -0,0 +1,18 @@ +# frozen_string_literal: true + +# Copyright The OpenTelemetry Authors +# +# SPDX-License-Identifier: Apache-2.0 + +source 'https://rubygems.org' + +# DO NOT ADD DEPENDENCIES HERE! +# Please declare a minimum development dependency in the gemspec, +# then target specific versions in the Appraisals file. + +gemspec + +group :development, :test do + gem 'activesupport', '~> 6' # used to test against JRuby which is only MRI 2.6 compatibile + gem 'opentelemetry-instrumentation-base', path: '../base' +end diff --git a/instrumentation/racecar/LICENSE b/instrumentation/racecar/LICENSE new file mode 100644 index 000000000..1ef7dad2c --- /dev/null +++ b/instrumentation/racecar/LICENSE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright The 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. diff --git a/instrumentation/racecar/README.md b/instrumentation/racecar/README.md new file mode 100644 index 000000000..cd41cdaf1 --- /dev/null +++ b/instrumentation/racecar/README.md @@ -0,0 +1,57 @@ +# OpenTelemetry Racecar Instrumentation + +The Racecar instrumentation is a community-maintained instrumentation for [Racecar](https://github.com/zendesk/racecar), a client library for Apache Kafka. + + +## How do I get started? + +Install the gem using: + +``` +gem install opentelemetry-instrumentation-racecar +``` + +Or, if you use [bundler][bundler-home], include `opentelemetry-instrumentation-racecar` in your `Gemfile`. + +## Runtime requirements + +This instrumentation is built on top of Racecar's integration with `ActiveSupport::Notifications`. `ActiveSupport::Notification` will need to be loaded before the instrumentation is installed (as below) or the installation will cancel. + +## Usage + +To use the instrumentation, call `use` with the name of the instrumentation: + +```ruby +OpenTelemetry::SDK.configure do |c| + c.use 'OpenTelemetry::Instrumentation::Racecar' +end +``` + +Alternatively, you can also call `use_all` to install all the available instrumentation. + +```ruby +OpenTelemetry::SDK.configure do |c| + c.use_all +end +``` + +## Examples + +Example usage can be seen in the `./example` directory [here](https://github.com/open-telemetry/opentelemetry-ruby-contrib/blob/main/instrumentation/racecar/example). Run `./trace_demonstration.sh` to see its behaviour. + +## How can I get involved? + +The `opentelemetry-instrumentation-racecar` gem source is [on github][repo-github], along with related gems including `opentelemetry-api` and `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][discussions-url] or attending our weekly meeting. See the [meeting calendar][community-meetings] for dates and times. For more information on this and other language SIGs, see the OpenTelemetry [community page][ruby-sig]. + +## License + +The `opentelemetry-instrumentation-racecar` gem is distributed under the Apache 2.0 license. See [LICENSE][license-github] for more information. + +[bundler-home]: https://bundler.io +[repo-github]: https://github.com/open-telemetry/opentelemetry-ruby +[license-github]: https://github.com/open-telemetry/opentelemetry-ruby-contrib/blob/main/LICENSE +[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 diff --git a/instrumentation/racecar/Rakefile b/instrumentation/racecar/Rakefile new file mode 100644 index 000000000..1a64ba842 --- /dev/null +++ b/instrumentation/racecar/Rakefile @@ -0,0 +1,28 @@ +# frozen_string_literal: true + +# Copyright The OpenTelemetry Authors +# +# SPDX-License-Identifier: Apache-2.0 + +require 'bundler/gem_tasks' +require 'rake/testtask' +require 'yard' +require 'rubocop/rake_task' + +RuboCop::RakeTask.new + +Rake::TestTask.new :test do |t| + t.libs << 'test' + t.libs << 'lib' + t.test_files = FileList['test/**/*_test.rb'] +end + +YARD::Rake::YardocTask.new do |t| + t.stats_options = ['--list-undoc'] +end + +if RUBY_ENGINE == 'truffleruby' + task default: %i[test] +else + task default: %i[test rubocop yard] +end diff --git a/instrumentation/racecar/example/Gemfile b/instrumentation/racecar/example/Gemfile new file mode 100644 index 000000000..18a5d5f32 --- /dev/null +++ b/instrumentation/racecar/example/Gemfile @@ -0,0 +1,17 @@ +# frozen_string_literal: true + +# Copyright The OpenTelemetry Authors +# +# SPDX-License-Identifier: Apache-2.0 + +source 'https://rubygems.org' + +# DO NOT ADD DEPENDENCIES HERE! +# Please declare a minimum development dependency in the gemspec, +# then target specific versions in the Appraisals file. + +gem 'activesupport' +gem 'opentelemetry-instrumentation-base', path: '../../base' +gem 'opentelemetry-instrumentation-racecar', path: '../' +gem 'opentelemetry-sdk' +gem 'racecar' diff --git a/instrumentation/racecar/example/config/racecar.rb b/instrumentation/racecar/example/config/racecar.rb new file mode 100644 index 000000000..a88fc36c5 --- /dev/null +++ b/instrumentation/racecar/example/config/racecar.rb @@ -0,0 +1,8 @@ +# frozen_string_literal: true + +Racecar.configure do |config| + # Each config variable can be set using a writer attribute. + host = ENV.fetch('TEST_KAFKA_HOST') { '127.0.0.1' } + port = ENV.fetch('TEST_KAFKA_PORT') { 29_092 } + config.brokers = ["#{host}:#{port}"] +end diff --git a/instrumentation/racecar/example/consumer.rb b/instrumentation/racecar/example/consumer.rb new file mode 100644 index 000000000..652736587 --- /dev/null +++ b/instrumentation/racecar/example/consumer.rb @@ -0,0 +1,10 @@ +# frozen_string_literal: true + +# an example consumer class +class Consumer < Racecar::Consumer + subscribes_to 'racecar-example-topic' + + def process(message) + puts 'consuming message' + end +end diff --git a/instrumentation/racecar/example/trace_demonstration.sh b/instrumentation/racecar/example/trace_demonstration.sh new file mode 100755 index 000000000..472172914 --- /dev/null +++ b/instrumentation/racecar/example/trace_demonstration.sh @@ -0,0 +1,4 @@ +#!/usr/bin/env bash + +bundle check || bundle install +bundle exec racecar --require consumer --require tracing Consumer diff --git a/instrumentation/racecar/example/tracing.rb b/instrumentation/racecar/example/tracing.rb new file mode 100644 index 000000000..7bf7143ff --- /dev/null +++ b/instrumentation/racecar/example/tracing.rb @@ -0,0 +1,34 @@ +# frozen_string_literal: true + +require 'active_support' +require 'opentelemetry/sdk' +require 'opentelemetry-instrumentation-racecar' + +ENV['OTEL_TRACES_EXPORTER'] ||= 'console' +OpenTelemetry::SDK.configure do |c| + c.use 'OpenTelemetry::Instrumentation::Racecar' +end + +host = ENV.fetch('TEST_KAFKA_HOST') { '127.0.0.1' } +port = ENV.fetch('TEST_KAFKA_PORT') { 29_092 } +config = { "bootstrap.servers": "#{host}:#{port}" } +producer = Rdkafka::Config.new(config).producer +delivery_handles = [] + +topic_name = 'racecar-example-topic' + +delivery_handles << producer.produce( + topic: topic_name, + payload: 'never gonna', + key: 'Key 1' +) + +delivery_handles << producer.produce( + topic: topic_name, + payload: 'give you up', + key: 'Key 2' +) + +delivery_handles.each(&:wait) + +producer.close diff --git a/instrumentation/racecar/lib/opentelemetry-instrumentation-racecar.rb b/instrumentation/racecar/lib/opentelemetry-instrumentation-racecar.rb new file mode 100644 index 000000000..baceb3cb7 --- /dev/null +++ b/instrumentation/racecar/lib/opentelemetry-instrumentation-racecar.rb @@ -0,0 +1,7 @@ +# frozen_string_literal: true + +# Copyright The OpenTelemetry Authors +# +# SPDX-License-Identifier: Apache-2.0 + +require_relative './opentelemetry/instrumentation' diff --git a/instrumentation/racecar/lib/opentelemetry/instrumentation.rb b/instrumentation/racecar/lib/opentelemetry/instrumentation.rb new file mode 100644 index 000000000..57448c911 --- /dev/null +++ b/instrumentation/racecar/lib/opentelemetry/instrumentation.rb @@ -0,0 +1,19 @@ +# frozen_string_literal: true + +# Copyright The OpenTelemetry Authors +# +# SPDX-License-Identifier: Apache-2.0 + +# 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. +# +# The OpenTelemetry module provides global accessors for telemetry objects. +# See the documentation for the `opentelemetry-api` gem for details. +module OpenTelemetry + # Instrumentation should be able to handle the case when the library is not installed on a user's system. + module Instrumentation + end +end + +require_relative './instrumentation/racecar' diff --git a/instrumentation/racecar/lib/opentelemetry/instrumentation/racecar.rb b/instrumentation/racecar/lib/opentelemetry/instrumentation/racecar.rb new file mode 100644 index 000000000..ece61c6e7 --- /dev/null +++ b/instrumentation/racecar/lib/opentelemetry/instrumentation/racecar.rb @@ -0,0 +1,19 @@ +# frozen_string_literal: true + +# Copyright The OpenTelemetry Authors +# +# SPDX-License-Identifier: Apache-2.0 + +require 'opentelemetry' +require 'opentelemetry-instrumentation-base' + +module OpenTelemetry + module Instrumentation + # Contains the OpenTelemetry instrumentation for the Racecar gem + module Racecar + end + end +end + +require_relative './racecar/instrumentation' +require_relative './racecar/version' diff --git a/instrumentation/racecar/lib/opentelemetry/instrumentation/racecar/instrumentation.rb b/instrumentation/racecar/lib/opentelemetry/instrumentation/racecar/instrumentation.rb new file mode 100644 index 000000000..3ce37aae1 --- /dev/null +++ b/instrumentation/racecar/lib/opentelemetry/instrumentation/racecar/instrumentation.rb @@ -0,0 +1,51 @@ +# frozen_string_literal: true + +# Copyright The OpenTelemetry Authors +# +# SPDX-License-Identifier: Apache-2.0 + +module OpenTelemetry + module Instrumentation + module Racecar + # The Instrumentation class contains logic to detect and install the Racecar instrumentation + class Instrumentation < OpenTelemetry::Instrumentation::Base + MINIMUM_VERSION = Gem::Version.new('2.7') + + compatible do + !defined?(::ActiveSupport::Notifications).nil? && gem_version >= MINIMUM_VERSION + end + + install do |_config| + require_patches + patch + add_subscribers + end + + present do + defined?(::Racecar) + end + + private + + def require_patches + require_relative './patches/consumer' + end + + def add_subscribers + require_relative 'process_message_subscriber' + subscriber = ProcessMessageSubscriber.new + ::ActiveSupport::Notifications.subscribe('process_message.racecar', subscriber) + end + + def patch + ::Racecar::Consumer.prepend(Patches::Consumer) + end + + def gem_version + require 'racecar/version' + Gem::Version.new(::Racecar::VERSION) + end + end + end + end +end diff --git a/instrumentation/racecar/lib/opentelemetry/instrumentation/racecar/patches/consumer.rb b/instrumentation/racecar/lib/opentelemetry/instrumentation/racecar/patches/consumer.rb new file mode 100644 index 000000000..f1d46eae8 --- /dev/null +++ b/instrumentation/racecar/lib/opentelemetry/instrumentation/racecar/patches/consumer.rb @@ -0,0 +1,35 @@ +# frozen_string_literal: true + +# Copyright The OpenTelemetry Authors +# +# SPDX-License-Identifier: Apache-2.0 + +module OpenTelemetry + module Instrumentation + module Racecar + module Patches + # This module contains logic to patch Racecar::Consumer + module Consumer + def produce(payload, topic:, key: nil, partition: nil, partition_key: nil, headers: nil, create_time: nil) + attributes = { + 'messaging.system' => 'kafka', + 'messaging.destination' => topic, + 'messaging.destination_kind' => 'topic' + } + + headers ||= {} + + tracer.in_span("#{topic} send", attributes: attributes, kind: :producer) do + OpenTelemetry.propagation.inject(headers) + super + end + end + + def tracer + Racecar::Instrumentation.instance.tracer + end + end + end + end + end +end diff --git a/instrumentation/racecar/lib/opentelemetry/instrumentation/racecar/process_message_subscriber.rb b/instrumentation/racecar/lib/opentelemetry/instrumentation/racecar/process_message_subscriber.rb new file mode 100644 index 000000000..31199dfd5 --- /dev/null +++ b/instrumentation/racecar/lib/opentelemetry/instrumentation/racecar/process_message_subscriber.rb @@ -0,0 +1,59 @@ +# frozen_string_literal: true + +module OpenTelemetry + module Instrumentation + # This class contains the ASN subsciber that instruments message processing + class ProcessMessageSubscriber + def tracer + Racecar::Instrumentation.instance.tracer + end + + def start(_name, _id, payload) + attrs = attributes(payload) + + parent_context = OpenTelemetry.propagation.extract(payload[:headers], getter: OpenTelemetry::Common::Propagation.symbol_key_getter) + parent_token = OpenTelemetry::Context.attach(parent_context) + + span_context = OpenTelemetry::Trace.current_span(parent_context).context + links = [OpenTelemetry::Trace::Link.new(span_context)] if span_context.valid? + + span = tracer.start_span("#{payload[:topic]} process", kind: :consumer, attributes: attrs, links: links) + token = OpenTelemetry::Context.attach(OpenTelemetry::Trace.context_with_span(span)) + payload.merge!( + __opentelemetry_span: span, + __opentelemetry_ctx_token: token, + __opentelemetry_parent_ctx_token: parent_token + ) + end + + def attributes(payload) + attributes = { + 'messaging.system' => 'kafka', + 'messaging.destination' => payload[:topic], + 'messaging.destination_kind' => 'topic', + 'messaging.kafka.partition' => payload[:partition], + 'messaging.kafka.offset' => payload[:offset] + } + + attributes['messaging.kafka.message_key'] = payload[:key] if payload[:key] + attributes + end + + def finish(name, id, payload) + span = payload.delete(:__opentelemetry_span) + token = payload.delete(:__opentelemetry_ctx_token) + parent_token = payload.delete(:__opentelemetry_parent_ctx_token) + return unless span && token + + if (e = payload[:exception_object]) + span.record_exception(e) + span.status = OpenTelemetry::Trace::Status.error("Unhandled exception of type: #{e.class}") + end + + span.finish + OpenTelemetry::Context.detach(token) + OpenTelemetry::Context.detach(parent_token) + end + end + end +end diff --git a/instrumentation/racecar/lib/opentelemetry/instrumentation/racecar/version.rb b/instrumentation/racecar/lib/opentelemetry/instrumentation/racecar/version.rb new file mode 100644 index 000000000..db6106879 --- /dev/null +++ b/instrumentation/racecar/lib/opentelemetry/instrumentation/racecar/version.rb @@ -0,0 +1,13 @@ +# frozen_string_literal: true + +# Copyright The OpenTelemetry Authors +# +# SPDX-License-Identifier: Apache-2.0 + +module OpenTelemetry + module Instrumentation + module Racecar + VERSION = '0.1.0' + end + end +end diff --git a/instrumentation/racecar/opentelemetry-instrumentation-racecar.gemspec b/instrumentation/racecar/opentelemetry-instrumentation-racecar.gemspec new file mode 100644 index 000000000..c94604e2c --- /dev/null +++ b/instrumentation/racecar/opentelemetry-instrumentation-racecar.gemspec @@ -0,0 +1,52 @@ +# frozen_string_literal: true + +# Copyright The OpenTelemetry Authors +# +# SPDX-License-Identifier: Apache-2.0 + +lib = File.expand_path('lib', __dir__) +$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib) +require 'opentelemetry/instrumentation/racecar/version' + +Gem::Specification.new do |spec| + spec.name = 'opentelemetry-instrumentation-racecar' + spec.version = OpenTelemetry::Instrumentation::Racecar::VERSION + spec.authors = ['OpenTelemetry Authors'] + spec.email = ['cncf-opentelemetry-contributors@lists.cncf.io'] + + spec.summary = 'Racecar instrumentation for the OpenTelemetry framework' + spec.description = 'Racecar instrumentation for the OpenTelemetry framework' + spec.homepage = 'https://github.com/open-telemetry/opentelemetry-ruby-contrib' + spec.license = 'Apache-2.0' + + spec.files = ::Dir.glob('lib/**/*.rb') + + ::Dir.glob('*.md') + + ['LICENSE', '.yardopts'] + spec.require_paths = ['lib'] + spec.required_ruby_version = '>= 2.6.0' + + spec.add_dependency 'opentelemetry-api', '~> 1.0' + spec.add_dependency 'opentelemetry-instrumentation-base', '~> 0.21.0' + + spec.add_development_dependency 'activesupport' + spec.add_development_dependency 'appraisal', '~> 2.2.0' + spec.add_development_dependency 'bundler', '>= 1.17' + spec.add_development_dependency 'minitest', '~> 5.0' + spec.add_development_dependency 'opentelemetry-sdk', '~> 1.0' + spec.add_development_dependency 'opentelemetry-test-helpers' + spec.add_development_dependency 'racecar', '~> 2.7' + spec.add_development_dependency 'rake', '~> 12.3.3' + spec.add_development_dependency 'rspec-mocks' + spec.add_development_dependency 'rubocop', '~> 0.73.0' + spec.add_development_dependency 'simplecov', '~> 0.17.1' + spec.add_development_dependency 'webmock', '~> 3.7.6' + spec.add_development_dependency 'yard', '~> 0.9' + spec.add_development_dependency 'yard-doctest', '~> 0.1.6' + + if spec.respond_to?(:metadata) + spec.metadata['changelog_uri'] = "https://open-telemetry.github.io/opentelemetry-ruby-contrib/opentelemetry-instrumentation-racecar/v#{OpenTelemetry::Instrumentation::Racecar::VERSION}/file.CHANGELOG.html" + spec.metadata['source_code_uri'] = 'https://github.com/open-telemetry/opentelemetry-ruby-contrib/tree/main/instrumentation/racecar' + spec.metadata['bug_tracker_uri'] = 'https://github.com/open-telemetry/opentelemetry-ruby-contrib/issues' + spec.metadata['documentation_uri'] = "https://open-telemetry.github.io/opentelemetry-ruby-contrib/opentelemetry-instrumentation-racecar/v#{OpenTelemetry::Instrumentation::Racecar::VERSION}" + end +end diff --git a/instrumentation/racecar/test/.rubocop.yml b/instrumentation/racecar/test/.rubocop.yml new file mode 100644 index 000000000..dd9425858 --- /dev/null +++ b/instrumentation/racecar/test/.rubocop.yml @@ -0,0 +1,4 @@ +inherit_from: ../.rubocop.yml + +Metrics/BlockLength: + Enabled: false diff --git a/instrumentation/racecar/test/opentelemetry/instrumentation/racecar/instrumentation_test.rb b/instrumentation/racecar/test/opentelemetry/instrumentation/racecar/instrumentation_test.rb new file mode 100644 index 000000000..056993b4b --- /dev/null +++ b/instrumentation/racecar/test/opentelemetry/instrumentation/racecar/instrumentation_test.rb @@ -0,0 +1,30 @@ +# frozen_string_literal: true + +# Copyright The OpenTelemetry Authors +# +# SPDX-License-Identifier: Apache-2.0 + +require 'test_helper' + +require_relative '../../../../lib/opentelemetry/instrumentation/racecar' + +describe OpenTelemetry::Instrumentation::Racecar do + let(:instrumentation) { OpenTelemetry::Instrumentation::Racecar::Instrumentation.instance } + + it 'has #name' do + _(instrumentation.name).must_equal 'OpenTelemetry::Instrumentation::Racecar' + end + + it 'has #version' do + _(instrumentation.version).wont_be_nil + _(instrumentation.version).wont_be_empty + end + + describe '#install' do + it 'accepts argument' do + _(instrumentation.compatible?).must_equal(true) + _(instrumentation.install({})).must_equal(true) + instrumentation.instance_variable_set(:@installed, false) + end + end +end diff --git a/instrumentation/racecar/test/opentelemetry/instrumentation/racecar_test.rb b/instrumentation/racecar/test/opentelemetry/instrumentation/racecar_test.rb new file mode 100644 index 000000000..1f51feb35 --- /dev/null +++ b/instrumentation/racecar/test/opentelemetry/instrumentation/racecar_test.rb @@ -0,0 +1,213 @@ +# frozen_string_literal: true + +# Copyright The OpenTelemetry Authors +# +# SPDX-License-Identifier: Apache-2.0 + +require 'test_helper' +require 'securerandom' + +require 'racecar/cli' +require_relative '../../../lib/opentelemetry/instrumentation/racecar' + +describe OpenTelemetry::Instrumentation::Racecar do + let(:instrumentation) { OpenTelemetry::Instrumentation::Racecar::Instrumentation.instance } + let(:exporter) { EXPORTER } + let(:spans) { exporter.finished_spans } + let(:host) { ENV.fetch('TEST_KAFKA_HOST', '127.0.0.1') } + let(:port) { ENV.fetch('TEST_KAFKA_PORT', 29_092) } + + def wait_for_spans(count) + Timeout.timeout(60) do + sleep 0.1 while exporter.finished_spans.size < count + end + end + + let(:consumer_class) do + klass = Class.new(Racecar::Consumer) + klass.define_method(:process, &process_method) + klass.subscribes_to(topic_name) + stub_const('TestConsumer', klass) + end + + let(:tracer) do + OpenTelemetry.tracer_provider.tracer('test-tracer') + end + + def produce(messages) + config = { "bootstrap.servers": "#{host}:#{port}" } + producer = Rdkafka::Config.new(config).producer + producer.delivery_callback = ->(_) {} + + producer_messages.map do |msg| + tracer.in_span("#{msg[:topic]} send", kind: :producer) do + msg[:headers] ||= {} + OpenTelemetry.propagation.inject(msg[:headers]) + producer.produce(**msg) + end + end.each(&:wait) + + producer.close + end + + let(:racecar) do + Racecar.config.brokers = ["#{host}:#{port}"] + Racecar.config.pause_timeout = 0 # fail fast and exit + Racecar.config.load_consumer_class(consumer_class) + Racecar::Runner.new(consumer_class.new, config: Racecar.config, logger: Logger.new(STDOUT), instrumenter: Racecar.instrumenter) + end + + def run_racecar(racecar) + Thread.new do + Thread.current[:racecar] = racecar + racecar.run + rescue RuntimeError => e + raise e unless e.message == 'oops' + end + end + + def stop_racecar(thread) + thread[:racecar].stop + thread.join(60) + end + + let(:topic_name) do + rand_hash = SecureRandom.hex(10) + "consumer-patch-trace-#{rand_hash}" + end + + before do + # Clear spans + exporter.reset + + instrumentation.install + + produce(producer_messages) + + @racecar_thread = run_racecar(racecar) + wait_for_spans(expected_spans) + end + + after do + stop_racecar(@racecar_thread) + end + + describe '#process' do + describe 'when the consumer runs and publishes acks' do + let(:process_method) do + lambda do |message| + produce( + 'message seen', + topic: "ack-#{message.topic}" + ) + deliver! + end + end + + let(:producer_messages) do + [{ + topic: topic_name, + payload: 'never gonna', + key: 'Key 1' + }, { + topic: topic_name, + payload: 'give you up', + key: 'Key 2' + }] + end + + let(:expected_spans) { 6 } + + it 'traces each message and traces publishing' do + process_spans = spans.select { |s| s.name == "#{topic_name} process" } + racecar_send_spans = spans.select { |s| s.name == "ack-#{topic_name} send" } + + # First pair for send and process spans + first_process_span = process_spans[0] + _(first_process_span.name).must_equal("#{topic_name} process") + _(first_process_span.kind).must_equal(:consumer) + _(first_process_span.attributes['messaging.destination']).must_equal(topic_name) + _(first_process_span.attributes['messaging.kafka.partition']).wont_be_nil + + first_process_span_link = first_process_span.links[0] + linked_span_context = first_process_span_link.span_context + + linked_send_span = spans.find { |s| s.span_id == linked_span_context.span_id } + _(linked_send_span.name).must_equal("#{topic_name} send") + _(linked_send_span.trace_id).must_equal(first_process_span.trace_id) + _(linked_send_span.trace_id).must_equal(linked_span_context.trace_id) + + # first racecar ack span + first_send_span = racecar_send_spans[0] + _(first_send_span.name).must_equal("ack-#{topic_name} send") + _(first_send_span.kind).must_equal(:producer) + _(first_send_span.instrumentation_library.name).must_equal('OpenTelemetry::Instrumentation::Racecar') + _(first_send_span.parent_span_id).must_equal(first_process_span.span_id) + _(first_send_span.trace_id).must_equal(first_process_span.trace_id) + + # Second pair of send and process spans + second_process_span = process_spans[1] + _(second_process_span.name).must_equal("#{topic_name} process") + _(second_process_span.kind).must_equal(:consumer) + + second_process_span_link = second_process_span.links[0] + linked_span_context = second_process_span_link.span_context + + linked_send_span = spans.find { |s| s.span_id == linked_span_context.span_id } + _(linked_send_span.name).must_equal("#{topic_name} send") + _(linked_send_span.trace_id).must_equal(second_process_span.trace_id) + _(linked_send_span.trace_id).must_equal(linked_span_context.trace_id) + + # second racecar ack span + second_send_span = racecar_send_spans[1] + _(second_send_span.name).must_equal("ack-#{topic_name} send") + _(second_send_span.kind).must_equal(:producer) + _(second_send_span.instrumentation_library.name).must_equal('OpenTelemetry::Instrumentation::Racecar') + _(second_send_span.parent_span_id).must_equal(second_process_span.span_id) + _(second_send_span.trace_id).must_equal(second_process_span.trace_id) + end + end + + describe 'for an erroring consumer' do + let(:process_method) do + lambda do |_message| + raise 'oops' + end + end + + let(:producer_messages) do + [{ + topic: topic_name, + payload: 'never gonna', + key: 'Key 1' + }] + end + + let(:expected_spans) { 2 } + + it 'can consume and publish a message' do + process_spans = spans.select { |s| s.name == "#{topic_name} process" } + + # First pair for send and process spans + first_process_span = process_spans[0] + _(first_process_span.name).must_equal("#{topic_name} process") + _(first_process_span.kind).must_equal(:consumer) + _(first_process_span.attributes['messaging.destination']).must_equal(topic_name) + _(first_process_span.attributes['messaging.kafka.partition']).wont_be_nil + + first_process_span_link = first_process_span.links[0] + linked_span_context = first_process_span_link.span_context + + linked_send_span = spans.find { |s| s.span_id == linked_span_context.span_id } + _(linked_send_span.name).must_equal("#{topic_name} send") + _(linked_send_span.trace_id).must_equal(first_process_span.trace_id) + _(linked_send_span.trace_id).must_equal(linked_span_context.trace_id) + + event = first_process_span.events.first + _(event.name).must_equal('exception') + _(event.attributes['exception.type']).must_equal('RuntimeError') + _(event.attributes['exception.message']).must_equal('oops') + end + end + end +end diff --git a/instrumentation/racecar/test/test_helper.rb b/instrumentation/racecar/test/test_helper.rb new file mode 100644 index 000000000..32889aa09 --- /dev/null +++ b/instrumentation/racecar/test/test_helper.rb @@ -0,0 +1,22 @@ +# frozen_string_literal: true + +# Copyright The OpenTelemetry Authors +# +# SPDX-License-Identifier: Apache-2.0 + +require 'opentelemetry/sdk' + +require 'minitest/autorun' +require 'webmock/minitest' +require 'rspec/mocks/minitest_integration' + +# global opentelemetry-sdk setup: +EXPORTER = OpenTelemetry::SDK::Trace::Export::InMemorySpanExporter.new +span_processor = OpenTelemetry::SDK::Trace::Export::SimpleSpanProcessor.new(EXPORTER) + +OpenTelemetry::SDK.configure do |c| + c.add_span_processor span_processor +end + +require 'racecar' +require 'active_support'