Skip to content

RCBC-524: OpenTelemetry integration #216

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
DemetrisChr wants to merge 9 commits into
base: main
Choose a base branch
from
Open

RCBC-524: OpenTelemetry integration #216

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
bb24ec2
RCBC-524: OpenTelemetry integration
DemetrisChr Jan 22, 2026
fd7b831
fix: improve regex pattern precision in CI workflow
avsej Jan 22, 2026
570bfe3
fix(rcb_query.cxx): add missing bucket_name to error message
avsej Jan 22, 2026
4e89bf1
Add Rakefile, README, API docs, change namespace of Otel tracer/meter
DemetrisChr Jan 27, 2026
6887e5f
GHA: Include couchbase-opentelemetry in uploaded artifacts
DemetrisChr Jan 27, 2026
4b7b2a2
GHA: Install couchbase-opentelemetry gem for tests
DemetrisChr Jan 27, 2026
3a44e02
Otel test: Add check for cluster label support
DemetrisChr Jan 27, 2026
f3cb3ee
Fix alpine build
DemetrisChr Jan 27, 2026
c5d92e7
Fix typos
DemetrisChr Jan 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
143 changes: 109 additions & 34 deletions .github/workflows/tests.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ jobs:
runs-on: ubuntu-22.04
outputs:
gem_version: ${{ steps.build_gem.outputs.gem_version }}
otel_gem_version: ${{ steps.build_otel_gem.outputs.otel_gem_version }}
steps:
- uses: actions/checkout@v4
with:
Expand All @@ -30,15 +31,22 @@ jobs:
with:
ruby-version: 3.3
bundler-cache: true
- name: Build
- name: Build couchbase gem
id: build_gem
run: |
COMMITS_SINCE_LAST_TAG=$(git describe --tags --always --long | awk -F '-' '{print $2}')
ruby bin/jenkins/patch-version.rb ${COMMITS_SINCE_LAST_TAG}
GEM_VERSION=$(ruby -r ./lib/couchbase/version.rb -e "puts Couchbase::VERSION[:sdk]")
echo "gem_version=${GEM_VERSION}" >> "$GITHUB_OUTPUT"
bundle exec rake build
- name: RDoc
- name: Build couchbase-opentelemetry gem
id: build_otel_gem
run: |
cd couchbase-opentelemetry
OTEL_GEM_VERSION=$(ruby -r ./lib/couchbase/opentelemetry/version.rb -e "puts Couchbase::OpenTelemetry::VERSION")
echo "otel_gem_version=${OTEL_GEM_VERSION}" >> "$GITHUB_OUTPUT"
bundle exec rake build
- name: Generate documentation for the couchbase gem
run: |
cat > patch-readme.rb <<EOF
require_relative "./lib/couchbase/version.rb"
Expand All @@ -50,36 +58,69 @@ jobs:
File.write("README.md", new_content)
EOF
ruby patch-readme.rb
bundle exec yard doc --hide-api private --output-dir docs/couchbase-ruby-client-${{ steps.build_gem.outputs.gem_version }} lib --main README.md
- uses: actions/upload-artifact@v4
bundle exec rake doc
- name: Generate documentation for the couchbase-opentelemetry gem
run: |
cd couchbase-opentelemetry
cat > patch-readme.rb <<EOF
require_relative "./lib/couchbase/opentelemetry/version.rb"
gemfile = <<EOS.strip
gem "couchbase-opentelemetry", "#{Couchbase::OpenTelemetry::VERSION}"
EOS
old_content = File.read("README.md")
new_content = old_content.gsub(/(gem "couchbase-opentelemetry", ").*?"/, gemfile)
File.write("README.md", new_content)
EOF
ruby patch-readme.rb
bundle exec rake doc
- name: Upload artifact - couchbase gem
uses: actions/upload-artifact@v4
with:
name: couchbase-${{ steps.build_gem.outputs.gem_version }}
path: |
pkg/*.gem
- uses: actions/upload-artifact@v4
- name: Upload artifact - couchbase-opentelemetry gem
uses: actions/upload-artifact@v4
with:
name: couchbase-opentelemetry-${{ steps.build_otel_gem.outputs.otel_gem_version }}
path: |
couchbase-opentelemetry/pkg/*.gem
- name: Upload artifact - scripts
uses: actions/upload-artifact@v4
with:
retention-days: 1
name: scripts-${{ steps.build_gem.outputs.gem_version }}
path: |
Gemfile
Rakefile
couchbase*.gemspec
lib/couchbase/**/version.rb
Gemfile
bin/**/*
couchbase.gemspec
lib/couchbase/version.rb
task/**/*
- uses: actions/upload-artifact@v4
couchbase-opentelemetry/Rakefile
couchbase-opentelemetry/couchbase-opentelemetry*.gemspec
couchbase-opentelemetry/lib/couchbase/opentelemetry/version.rb
- name: Upload artifact - tests and test data
uses: actions/upload-artifact@v4
with:
retention-days: 1
name: tests-${{ steps.build_gem.outputs.gem_version }}
path: |
test/**/*
test_data/**/*
- uses: actions/upload-artifact@v4
- name: Upload artifact - couchbase gem docs
uses: actions/upload-artifact@v4
with:
name: docs-${{ steps.build_gem.outputs.gem_version }}
path: |
docs/**/*

doc/**/*
- name: Upload artifact - couchbase-opentelemetry gem docs
uses: actions/upload-artifact@v4
with:
name: otel-docs-${{ steps.build_otel_gem.outputs.otel_gem_version }}
path: |
couchbase-opentelemetry/doc/**/*

build_alpine_x86_64:
# FIXME(SA): add aarch64 for Alpine Linux
# Right now github does not allow to execute JS-based actions (like
Expand Down Expand Up @@ -131,6 +172,10 @@ jobs:
with:
path: pkg
name: couchbase-${{ needs.source.outputs.gem_version }}
- uses: actions/download-artifact@v4
with:
path: pkg
name: couchbase-opentelemetry-${{ needs.source.outputs.otel_gem_version }}
- name: Build gem
env:
SUPPORTED_RUBY_VERSIONS: "3.2 3.3 3.4 4.0"
Expand Down Expand Up @@ -457,6 +502,9 @@ jobs:
- uses: actions/download-artifact@v4
with:
name: couchbase-${{ needs.source.outputs.gem_version }}-x86_64-linux
- uses: actions/download-artifact@v4
with:
name: couchbase-opentelemetry-${{ needs.source.outputs.otel_gem_version }}
- uses: actions/download-artifact@v4
with:
name: scripts-${{ needs.source.outputs.gem_version }}
Expand All @@ -468,12 +516,17 @@ jobs:
ruby-version: ${{ matrix.ruby }}
- name: Install
run: |
COUCHBASE_GEM_PATH=$(realpath couchbase-*.gem)
UNPACKED_GEM_PATH=$(gem unpack ${COUCHBASE_GEM_PATH} | grep "Unpacked gem" | cut -d "'" -f 2)
gem unpack --spec --target ${UNPACKED_GEM_PATH} ${COUCHBASE_GEM_PATH}
ruby -i.bak -pe "gsub(/gemspec/, 'gem \"couchbase\", path: \"${UNPACKED_GEM_PATH}\"')" Gemfile
COUCHBASE_GEM_PATH=$(realpath couchbase-${{ needs.source.outputs.gem_version }}-*.gem)
COUCHBASE_OPENTELEMETRY_GEM_PATH=$(realpath couchbase-opentelemetry-${{ needs.source.outputs.otel_gem_version }}.gem)
mkdir -p local-gem-repo/gems
mv ${COUCHBASE_GEM_PATH} local-gem-repo/gems
mv ${COUCHBASE_OPENTELEMETRY_GEM_PATH} local-gem-repo/gems
GEM_REPO_PATH=$(realpath local-gem-repo)
gem generate_index --directory local-gem-repo
ruby -i.bak -pe "gsub(/gemspec$/, 'gem \"couchbase\", source: \"file://${GEM_REPO_PATH}\"')" Gemfile
ruby -i.bak -pe "gsub(/gemspec path: \"couchbase-opentelemetry\"$/, 'gem \"couchbase-opentelemetry\", source: \"file://${GEM_REPO_PATH}\"')" Gemfile
bundle install
bundle exec ruby -r bundler/setup -r couchbase -e 'pp Couchbase::VERSION, Couchbase::BUILD_INFO'
bundle exec ruby -r bundler/setup -r couchbase -r couchbase/opentelemetry -e 'pp Couchbase::VERSION, Couchbase::BUILD_INFO, {otel: Couchbase::OpenTelemetry::VERSION}'
- name: Test
env:
CB_CAVES_LOGS_DIR: caves-logs
Expand Down Expand Up @@ -518,6 +571,9 @@ jobs:
- uses: actions/download-artifact@v4
with:
name: couchbase-${{ needs.source.outputs.gem_version }}-arm64-darwin
- uses: actions/download-artifact@v4
with:
name: couchbase-opentelemetry-${{ needs.source.outputs.otel_gem_version }}
- uses: actions/download-artifact@v4
with:
name: scripts-${{ needs.source.outputs.gem_version }}
Expand All @@ -530,14 +586,17 @@ jobs:
- name: Install
run: |
set -xe
COUCHBASE_GEM_PATH=$(realpath couchbase-*.gem)
UNPACKED_GEM_PATH=$(gem unpack ${COUCHBASE_GEM_PATH} | grep "Unpacked gem" | cut -d "'" -f 2)
gem unpack --spec --target ${UNPACKED_GEM_PATH} ${COUCHBASE_GEM_PATH}
ruby -i.bak -pe "gsub(/gemspec/, 'gem \"couchbase\", path: \"${UNPACKED_GEM_PATH}\"')" Gemfile
find .
ls -ld ${UNPACKED_GEM_PATH}
COUCHBASE_GEM_PATH=$(realpath couchbase-${{ needs.source.outputs.gem_version }}-*.gem)
COUCHBASE_OPENTELEMETRY_GEM_PATH=$(realpath couchbase-opentelemetry-${{ needs.source.outputs.otel_gem_version }}.gem)
mkdir -p local-gem-repo/gems
mv ${COUCHBASE_GEM_PATH} local-gem-repo/gems
mv ${COUCHBASE_OPENTELEMETRY_GEM_PATH} local-gem-repo/gems
GEM_REPO_PATH=$(realpath local-gem-repo)
gem generate_index --directory local-gem-repo
ruby -i.bak -pe "gsub(/gemspec$/, 'gem \"couchbase\", source: \"file://${GEM_REPO_PATH}\"')" Gemfile
ruby -i.bak -pe "gsub(/gemspec path: \"couchbase-opentelemetry\"$/, 'gem \"couchbase-opentelemetry\", source: \"file://${GEM_REPO_PATH}\"')" Gemfile
bundle install
bundle exec ruby -r bundler/setup -r couchbase -e 'pp Couchbase::VERSION, Couchbase::BUILD_INFO'
bundle exec ruby -r bundler/setup -r couchbase -r couchbase/opentelemetry -e 'pp Couchbase::VERSION, Couchbase::BUILD_INFO, {otel: Couchbase::OpenTelemetry::VERSION}'
- name: Test
env:
CB_CAVES_LOGS_DIR: caves-logs
Expand Down Expand Up @@ -591,6 +650,9 @@ jobs:
- uses: actions/download-artifact@v4
with:
name: couchbase-${{ needs.source.outputs.gem_version }}-x86_64-darwin
- uses: actions/download-artifact@v4
with:
name: couchbase-opentelemetry-${{ needs.source.outputs.otel_gem_version }}
- uses: actions/download-artifact@v4
with:
name: scripts-${{ needs.source.outputs.gem_version }}
Expand All @@ -602,12 +664,17 @@ jobs:
ruby-version: ${{ matrix.ruby }}
- name: Install
run: |
COUCHBASE_GEM_PATH=$(realpath couchbase-*.gem)
UNPACKED_GEM_PATH=$(gem unpack ${COUCHBASE_GEM_PATH} | grep "Unpacked gem" | cut -d "'" -f 2)
gem unpack --spec --target ${UNPACKED_GEM_PATH} ${COUCHBASE_GEM_PATH}
ruby -i.bak -pe "gsub(/gemspec/, 'gem \"couchbase\", path: \"${UNPACKED_GEM_PATH}\"')" Gemfile
COUCHBASE_GEM_PATH=$(realpath couchbase-${{ needs.source.outputs.gem_version }}-*.gem)
COUCHBASE_OPENTELEMETRY_GEM_PATH=$(realpath couchbase-opentelemetry-${{ needs.source.outputs.otel_gem_version }}.gem)
mkdir -p local-gem-repo/gems
mv ${COUCHBASE_GEM_PATH} local-gem-repo/gems
mv ${COUCHBASE_OPENTELEMETRY_GEM_PATH} local-gem-repo/gems
GEM_REPO_PATH=$(realpath local-gem-repo)
gem generate_index --directory local-gem-repo
ruby -i.bak -pe "gsub(/gemspec$/, 'gem \"couchbase\", source: \"file://${GEM_REPO_PATH}\"')" Gemfile
ruby -i.bak -pe "gsub(/gemspec path: \"couchbase-opentelemetry\"$/, 'gem \"couchbase-opentelemetry\", source: \"file://${GEM_REPO_PATH}\"')" Gemfile
bundle install
bundle exec ruby -r bundler/setup -r couchbase -e 'pp Couchbase::VERSION, Couchbase::BUILD_INFO'
bundle exec ruby -r bundler/setup -r couchbase -r couchbase/opentelemetry -e 'pp Couchbase::VERSION, Couchbase::BUILD_INFO, {otel: Couchbase::OpenTelemetry::VERSION}'
- name: Test
env:
CB_CAVES_LOGS_DIR: caves-logs
Expand Down Expand Up @@ -696,6 +763,9 @@ jobs:
- uses: actions/download-artifact@v4
with:
name: couchbase-${{ needs.source.outputs.gem_version }}-x86_64-linux
- uses: actions/download-artifact@v4
with:
name: couchbase-opentelemetry-${{ needs.source.outputs.otel_gem_version }}
- uses: actions/download-artifact@v4
with:
name: scripts-${{ needs.source.outputs.gem_version }}
Expand All @@ -707,12 +777,17 @@ jobs:
ruby-version: 3.3
- name: Install
run: |
COUCHBASE_GEM_PATH=$(realpath couchbase-*.gem)
UNPACKED_GEM_PATH=$(gem unpack ${COUCHBASE_GEM_PATH} | grep "Unpacked gem" | cut -d "'" -f 2)
gem unpack --spec --target ${UNPACKED_GEM_PATH} ${COUCHBASE_GEM_PATH}
ruby -i.bak -pe "gsub(/gemspec/, 'gem \"couchbase\", path: \"${UNPACKED_GEM_PATH}\"')" Gemfile
COUCHBASE_GEM_PATH=$(realpath couchbase-${{ needs.source.outputs.gem_version }}-*.gem)
COUCHBASE_OPENTELEMETRY_GEM_PATH=$(realpath couchbase-opentelemetry-${{ needs.source.outputs.otel_gem_version }}.gem)
mkdir -p local-gem-repo/gems
mv ${COUCHBASE_GEM_PATH} local-gem-repo/gems
mv ${COUCHBASE_OPENTELEMETRY_GEM_PATH} local-gem-repo/gems
GEM_REPO_PATH=$(realpath local-gem-repo)
gem generate_index --directory local-gem-repo
ruby -i.bak -pe "gsub(/gemspec$/, 'gem \"couchbase\", source: \"file://${GEM_REPO_PATH}\"')" Gemfile
ruby -i.bak -pe "gsub(/gemspec path: \"couchbase-opentelemetry\"$/, 'gem \"couchbase-opentelemetry\", source: \"file://${GEM_REPO_PATH}\"')" Gemfile
bundle install
bundle exec ruby -r bundler/setup -r couchbase -e 'pp Couchbase::VERSION, Couchbase::BUILD_INFO'
bundle exec ruby -r bundler/setup -r couchbase -r couchbase/opentelemetry -e 'pp Couchbase::VERSION, Couchbase::BUILD_INFO, {otel: Couchbase::OpenTelemetry::VERSION}'
- name: Test
env:
TEST_SERVER_VERSION: ${{ matrix.server }}
Expand Down
6 changes: 3 additions & 3 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,14 +8,14 @@
.byebug_history
/.rakeTasks
/.ruby-version
/.yardoc
/**/.yardoc
/_yardoc/
/cmake-build-*/
/build*
/coverage/
/doc/
/**/doc/
/ext/cache/
/pkg/
/**/pkg/
/test/reports/
/tmp/
/logs/
Expand Down
1 change: 1 addition & 0 deletions .yardopts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
--no-progress --output-dir doc/couchbase-ruby-client-master lib - README.md
--tag couchbase.stability:"Stability"
--transitive-tag couchbase.stability
--hide-api private
3 changes: 3 additions & 0 deletions Gemfile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ source "https://rubygems.org"
git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }

gemspec
gemspec path: "couchbase-opentelemetry"

gem "rake"

Expand All @@ -35,6 +36,8 @@ group :development do
gem "minitest", "< 6.0"
gem "minitest-reporters"
gem "mutex_m"
gem "opentelemetry-metrics-sdk"
gem "opentelemetry-sdk"
gem "rack"
gem "reek"
gem "rubocop", require: false
Expand Down
2 changes: 1 addition & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ Please attach version information to the ticket/post. To obtain this information

## Installation

The library has been tested with MRI 3.1, 3.2, 3.3 and 3.4. Supported platforms are Linux and MacOS.
The library has been tested with MRI 3.2, 3.3, 3.4 and 4.0. Supported platforms are Linux and MacOS.

Add this line to your application's Gemfile:

Expand Down
1 change: 1 addition & 0 deletions couchbase-opentelemetry/.rubocop.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
inherit_from: ../.rubocop.yml
4 changes: 4 additions & 0 deletions couchbase-opentelemetry/.yardopts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
--no-progress --output-dir doc/couchbase-ruby-client-master lib - README.md
--tag couchbase.stability:"Stability"
--transitive-tag couchbase.stability
--hide-api private
83 changes: 83 additions & 0 deletions couchbase-opentelemetry/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
# Couchbase Ruby Client OpenTelemetry Integration

## Installation

The library has been tested with MRI 3.2, 3.3, 3.4 and 4.0. Supported platforms are Linux and MacOS.

Add this line to your application's Gemfile:

```ruby
gem "couchbase-opentelemetry", "0.1.0"
```

And then execute:

$ bundle install

Or install it yourself as:

$ gem install couchbase-opentelemetry

## Usage

Here is an example on how to set up Tracing and Metrics with OpenTelemetry:

```ruby
require "couchbase"
require "couchbase/opentelemetry"

require "opentelemetry-sdk"
require "opentelemetry-metrics-sdk"

# Initialize a tracer provider
tracer_provider = OpenTelemetry::SDK::Trace::TracerProvider.new
tracer_provider.add_span_processor(
OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
OpenTelemetry::Exporter::OTLP::Exporter.new(endpoint: "https://<hostname>:<port>/v1/traces")
)
)

# Initialize the Couchbase OpenTelemetry Request Tracer
tracer = Couchbase::OpenTelemetry::RequestTracer.new(tracer_provider)

# Initialize a meter provider
meter_provider = OpenTelemetry::SDK::Metrics::MeterProvider.new
meter_provider.add_metric_reader(
OpenTelemetry::SDK::Metrics::Export::PeriodicMetricReader.new(
exporter: OpenTelemetry::Exporter::OTLP::Metrics::MetricsExporter.new(
endpoint: "https://<hostname>:<port>/v1/metrics"
)
)
)

# Initialize the Couchbase OpenTelemetry Meter
meter = Couchbase::OpenTelemetry::Meter.new(meter_provider)

# Configure tracer and meter in cluster options
options = Couchbase::Options::Cluster.new(
authenticator: Couchbase::PasswordAuthenticator.new("Administrator", "password")
tracer: tracer,
meter: meter
)

# Initialize cluster instance
cluster = Cluster.connect("couchbase://127.0.0.1", options)
```

## License

The gem is available as open source under the terms of the [Apache 2.0 License](https://opensource.org/licenses/Apache-2.0).

Copyright 2025-Present Couchbase, Inc.

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.
Loading
Loading