couchbase 3.7.0 → 3.8.0

data/ext/rcb_hdr_histogram.cxx

@@ -0,0 +1,219 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *   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.
+ */
+
+#include "rcb_hdr_histogram.hxx"
+#include "rcb_exceptions.hxx"
+
+#include <hdr/hdr_histogram.h>
+#include <ruby.h>
+
+#include <mutex>
+#include <shared_mutex>
+#include <vector>
+
+namespace couchbase::ruby
+{
+namespace
+{
+struct cb_hdr_histogram_data {
+  hdr_histogram* histogram{ nullptr };
+  std::shared_mutex mutex{};
+};
+
+void
+cb_hdr_histogram_close(cb_hdr_histogram_data* hdr_histogram_data)
+{
+  if (hdr_histogram_data->histogram != nullptr) {
+    hdr_close(hdr_histogram_data->histogram);
+    hdr_histogram_data->histogram = nullptr;
+  }
+}
+
+void
+cb_HdrHistogramC_mark(void* /* ptr */)
+{
+  /* no embedded ruby objects -- no mark */
+}
+
+void
+cb_HdrHistogramC_free(void* ptr)
+{
+  auto* hdr_histogram_data = static_cast<cb_hdr_histogram_data*>(ptr);
+  cb_hdr_histogram_close(hdr_histogram_data);
+  hdr_histogram_data->~cb_hdr_histogram_data();
+  ruby_xfree(hdr_histogram_data);
+}
+
+std::size_t
+cb_HdrHistogramC_memsize(const void* ptr)
+{
+  const auto* hdr_histogram_data = static_cast<const cb_hdr_histogram_data*>(ptr);
+  return sizeof(*hdr_histogram_data);
+}
+
+const rb_data_type_t cb_hdr_histogram_type{
+  "Couchbase/Utils/HdrHistogramC",
+  {
+    cb_HdrHistogramC_mark,
+    cb_HdrHistogramC_free,
+    cb_HdrHistogramC_memsize,
+// only one reserved field when GC.compact implemented
+#ifdef T_MOVED
+    nullptr,
+#endif
+    {},
+  },
+#ifdef RUBY_TYPED_FREE_IMMEDIATELY
+  nullptr,
+  nullptr,
+  RUBY_TYPED_FREE_IMMEDIATELY,
+#endif
+};
+
+VALUE
+cb_HdrHistogramC_allocate(VALUE klass)
+{
+  cb_hdr_histogram_data* hdr_histogram = nullptr;
+  VALUE obj =
+    TypedData_Make_Struct(klass, cb_hdr_histogram_data, &cb_hdr_histogram_type, hdr_histogram);
+  new (hdr_histogram) cb_hdr_histogram_data();
+  return obj;
+}
+
+VALUE
+cb_HdrHistogramC_initialize(VALUE self,
+                            VALUE lowest_discernible_value,
+                            VALUE highest_trackable_value,
+                            VALUE significant_figures)
+{
+  Check_Type(lowest_discernible_value, T_FIXNUM);
+  Check_Type(highest_trackable_value, T_FIXNUM);
+  Check_Type(significant_figures, T_FIXNUM);
+
+  std::int64_t lowest = NUM2LL(lowest_discernible_value);
+  std::int64_t highest = NUM2LL(highest_trackable_value);
+  int sigfigs = NUM2INT(significant_figures);
+
+  cb_hdr_histogram_data* hdr_histogram;
+  TypedData_Get_Struct(self, cb_hdr_histogram_data, &cb_hdr_histogram_type, hdr_histogram);
+
+  int res;
+  {
+    const std::unique_lock lock(hdr_histogram->mutex);
+    res = hdr_init(lowest, highest, sigfigs, &hdr_histogram->histogram);
+  }
+  if (res != 0) {
+    rb_raise(exc_couchbase_error(), "failed to initialize HDR histogram");
+    return self;
+  }
+
+  return self;
+}
+
+VALUE
+cb_HdrHistogramC_close(VALUE self)
+{
+  cb_hdr_histogram_data* hdr_histogram;
+  TypedData_Get_Struct(self, cb_hdr_histogram_data, &cb_hdr_histogram_type, hdr_histogram);
+  {
+    const std::unique_lock lock(hdr_histogram->mutex);
+    cb_hdr_histogram_close(hdr_histogram);
+  }
+  return Qnil;
+}
+
+VALUE
+cb_HdrHistogramC_record_value(VALUE self, VALUE value)
+{
+  Check_Type(value, T_FIXNUM);
+
+  std::int64_t val = NUM2LL(value);
+
+  cb_hdr_histogram_data* hdr_histogram;
+  TypedData_Get_Struct(self, cb_hdr_histogram_data, &cb_hdr_histogram_type, hdr_histogram);
+
+  {
+    const std::shared_lock lock(hdr_histogram->mutex);
+    hdr_record_value_atomic(hdr_histogram->histogram, val);
+  }
+  return Qnil;
+}
+
+VALUE
+cb_HdrHistogramC_get_percentiles_and_reset(VALUE self, VALUE percentiles)
+{
+  Check_Type(percentiles, T_ARRAY);
+
+  cb_hdr_histogram_data* hdr_histogram;
+  TypedData_Get_Struct(self, cb_hdr_histogram_data, &cb_hdr_histogram_type, hdr_histogram);
+
+  std::vector<std::int64_t> percentile_values{};
+  std::int64_t total_count;
+  {
+    const std::unique_lock lock(hdr_histogram->mutex);
+    total_count = hdr_histogram->histogram->total_count;
+    for (std::size_t i = 0; i < static_cast<std::size_t>(RARRAY_LEN(percentiles)); ++i) {
+      VALUE entry = rb_ary_entry(percentiles, static_cast<long>(i));
+      Check_Type(entry, T_FLOAT);
+      double perc = NUM2DBL(entry);
+      std::int64_t value_at_perc = hdr_value_at_percentile(hdr_histogram->histogram, perc);
+      percentile_values.push_back(value_at_perc);
+    }
+    hdr_reset(hdr_histogram->histogram);
+  }
+
+  static const VALUE sym_total_count = rb_id2sym(rb_intern("total_count"));
+  static const VALUE sym_percentiles = rb_id2sym(rb_intern("percentiles"));
+  VALUE res = rb_hash_new();
+  rb_hash_aset(res, sym_total_count, LL2NUM(total_count));
+  VALUE perc_array = rb_ary_new_capa(static_cast<long>(percentile_values.size()));
+  for (const auto& val : percentile_values) {
+    rb_ary_push(perc_array, LL2NUM(val));
+  }
+  rb_hash_aset(res, sym_percentiles, perc_array);
+  return res;
+}
+
+VALUE
+cb_HdrHistogramC_bin_count(VALUE self)
+{
+  cb_hdr_histogram_data* hdr_histogram;
+  TypedData_Get_Struct(self, cb_hdr_histogram_data, &cb_hdr_histogram_type, hdr_histogram);
+
+  std::int32_t bin_count;
+  {
+    const std::unique_lock lock(hdr_histogram->mutex);
+    bin_count = hdr_histogram->histogram->bucket_count;
+  }
+  return LONG2NUM(bin_count);
+}
+} // namespace
+
+void
+init_hdr_histogram(VALUE mCouchbase)
+{
+  VALUE mUtils = rb_define_module_under(mCouchbase, "Utils");
+  VALUE cHdrHistogramC = rb_define_class_under(mUtils, "HdrHistogramC", rb_cObject);
+  rb_define_alloc_func(cHdrHistogramC, cb_HdrHistogramC_allocate);
+  rb_define_method(cHdrHistogramC, "initialize", cb_HdrHistogramC_initialize, 3);
+  rb_define_method(cHdrHistogramC, "close", cb_HdrHistogramC_close, 0);
+  rb_define_method(cHdrHistogramC, "record_value", cb_HdrHistogramC_record_value, 1);
+  rb_define_method(cHdrHistogramC, "bin_count", cb_HdrHistogramC_bin_count, 0);
+  rb_define_method(
+    cHdrHistogramC, "get_percentiles_and_reset", cb_HdrHistogramC_get_percentiles_and_reset, 1);
+}
+} // namespace couchbase::ruby

data/ext/rcb_hdr_histogram.hxx

@@ -0,0 +1,28 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *   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.
+ */
+
+#ifndef COUCHBASE_RUBY_RCB_HDR_HISTOGRAM_HXX
+#define COUCHBASE_RUBY_RCB_HDR_HISTOGRAM_HXX
+
+#include <ruby/internal/value.h>
+
+namespace couchbase::ruby
+{
+void
+init_hdr_histogram(VALUE mCouchbase);
+} // namespace couchbase::ruby
+#endif // COUCHBASE_RUBY_RCB_HDR_HISTOGRAM_HXX

data/ext/rcb_multi.cxx

@@ -17,7 +17,20 @@
 
 #include <core/cluster.hxx>
 #include <core/document_id.hxx>
+
+// TODO(DC): Compilation fails unless all operations that support legacy durability are included
+// This is probably something we should address in the C++ core. Including them all for now.
+#include <core/operations/document_append.hxx>
+#include <core/operations/document_decrement.hxx>
 #include <core/operations/document_get.hxx>
+#include <core/operations/document_increment.hxx>
+#include <core/operations/document_insert.hxx>
+#include <core/operations/document_mutate_in.hxx>
+#include <core/operations/document_prepend.hxx>
+#include <core/operations/document_remove.hxx>
+#include <core/operations/document_replace.hxx>
+#include <core/operations/document_upsert.hxx>
+
 #include <couchbase/cluster.hxx>
 #include <couchbase/upsert_options.hxx>
 
@@ -32,7 +45,6 @@ namespace couchbase::ruby
 {
 namespace
 {
-
 void
 cb_extract_array_of_ids(std::vector<core::document_id>& ids, VALUE arg)
 {
@@ -82,21 +94,29 @@ cb_extract_array_of_ids(std::vector<core::document_id>& ids, VALUE arg)
 
 void
 cb_extract_array_of_id_content(
-  std::vector<std::pair<std::string, couchbase::codec::encoded_value>>& id_content,
-  VALUE arg)
+  std::vector<std::pair<core::document_id, couchbase::codec::encoded_value>>& id_content,
+  VALUE bucket_name,
+  VALUE scope_name,
+  VALUE collection_name,
+  VALUE tuples)
 {
-  if (TYPE(arg) != T_ARRAY) {
+  cb_check_type(bucket_name, T_STRING);
+  cb_check_type(scope_name, T_STRING);
+  cb_check_type(collection_name, T_STRING);
+
+  if (TYPE(tuples) != T_ARRAY) {
     throw ruby_exception(
       rb_eArgError,
-      rb_sprintf("Type of ID/content tuples must be an Array, but given %+" PRIsVALUE, arg));
+      rb_sprintf("Type of ID/content tuples must be an Array, but given %+" PRIsVALUE, tuples));
   }
-  auto num_of_tuples = static_cast<std::size_t>(RARRAY_LEN(arg));
+
+  auto num_of_tuples = static_cast<std::size_t>(RARRAY_LEN(tuples));
   if (num_of_tuples < 1) {
     throw ruby_exception(rb_eArgError, "Array of ID/content tuples must not be empty");
   }
   id_content.reserve(num_of_tuples);
   for (std::size_t i = 0; i < num_of_tuples; ++i) {
-    VALUE entry = rb_ary_entry(arg, static_cast<long>(i));
+    VALUE entry = rb_ary_entry(tuples, static_cast<long>(i));
     if (TYPE(entry) != T_ARRAY || RARRAY_LEN(entry) != 3) {
       throw ruby_exception(rb_eArgError,
                            rb_sprintf("ID/content tuple must be represented as an Array[id, "
@@ -118,27 +138,40 @@ cb_extract_array_of_id_content(
       throw ruby_exception(rb_eArgError,
                            rb_sprintf("Flags must be an Integer, but given %+" PRIsVALUE, flags));
     }
-    id_content.emplace_back(
-      cb_string_new(id),
-      couchbase::codec::encoded_value{ cb_binary_new(content), FIX2UINT(flags) });
+    id_content.emplace_back(core::document_id{ cb_string_new(bucket_name),
+                                               cb_string_new(scope_name),
+                                               cb_string_new(collection_name),
+                                               cb_string_new(id) },
+                            couchbase::codec::encoded_value{
+                              cb_binary_new(content),
+                              FIX2UINT(flags),
+                            });
   }
 }
 
 void
-cb_extract_array_of_id_cas(std::vector<std::pair<std::string, couchbase::cas>>& id_cas, VALUE arg)
+cb_extract_array_of_id_cas(std::vector<std::pair<core::document_id, couchbase::cas>>& id_cas,
+                           VALUE bucket_name,
+                           VALUE scope_name,
+                           VALUE collection_name,
+                           VALUE tuples)
 {
-  if (TYPE(arg) != T_ARRAY) {
+  cb_check_type(bucket_name, T_STRING);
+  cb_check_type(scope_name, T_STRING);
+  cb_check_type(collection_name, T_STRING);
+
+  if (TYPE(tuples) != T_ARRAY) {
     throw ruby_exception(
       rb_eArgError,
-      rb_sprintf("Type of ID/CAS tuples must be an Array, but given %+" PRIsVALUE, arg));
+      rb_sprintf("Type of ID/CAS tuples must be an Array, but given %+" PRIsVALUE, tuples));
   }
-  auto num_of_tuples = static_cast<std::size_t>(RARRAY_LEN(arg));
+  auto num_of_tuples = static_cast<std::size_t>(RARRAY_LEN(tuples));
   if (num_of_tuples < 1) {
     rb_raise(rb_eArgError, "Array of ID/CAS tuples must not be empty");
   }
   id_cas.reserve(num_of_tuples);
   for (std::size_t i = 0; i < num_of_tuples; ++i) {
-    VALUE entry = rb_ary_entry(arg, static_cast<long>(i));
+    VALUE entry = rb_ary_entry(tuples, static_cast<long>(i));
     if (TYPE(entry) != T_ARRAY || RARRAY_LEN(entry) != 2) {
       throw ruby_exception(
         rb_eArgError,
@@ -156,7 +189,11 @@ cb_extract_array_of_id_cas(std::vector<std::pair<std::string, couchbase::cas>>&
       cb_extract_cas(cas_val, cas);
     }
 
-    id_cas.emplace_back(cb_string_new(id), cas_val);
+    id_cas.emplace_back(core::document_id{ cb_string_new(bucket_name),
+                                           cb_string_new(scope_name),
+                                           cb_string_new(collection_name),
+                                           cb_string_new(id) },
+                        cas_val);
   }
 }
 
@@ -222,45 +259,72 @@ cb_Backend_document_upsert_multi(VALUE self,
                                  VALUE id_content,
                                  VALUE options)
 {
-  auto cluster = cb_backend_to_public_api_cluster(self);
-
-  try {
-    couchbase::upsert_options opts;
-    set_timeout(opts, options);
-    set_expiry(opts, options);
-    set_durability(opts, options);
-    set_preserve_expiry(opts, options);
+  auto cluster = cb_backend_to_core_api_cluster(self);
 
-    auto c = cluster.bucket(cb_string_new(bucket))
-               .scope(cb_string_new(scope))
-               .collection(cb_string_new(collection));
+  Check_Type(bucket, T_STRING);
+  Check_Type(scope, T_STRING);
+  Check_Type(collection, T_STRING);
+  if (!NIL_P(options)) {
+    Check_Type(options, T_HASH);
+  }
 
-    std::vector<std::pair<std::string, couchbase::codec::encoded_value>> tuples{};
-    cb_extract_array_of_id_content(tuples, id_content);
+  try {
+    std::vector<std::pair<core::document_id, couchbase::codec::encoded_value>> tuples{};
+    cb_extract_array_of_id_content(tuples, bucket, scope, collection, id_content);
 
     auto num_of_tuples = tuples.size();
-    std::vector<
-      std::pair<std::string, std::future<std::pair<couchbase::error, couchbase::mutation_result>>>>
-      futures;
+    std::vector<std::pair<std::string, std::future<core::operations::upsert_response>>> futures;
     futures.reserve(num_of_tuples);
 
     for (auto& [id, content] : tuples) {
-      futures.emplace_back(id, c.upsert(id, std::move(content), opts));
+      core::operations::upsert_request req{
+        id,
+        std::move(content.data),
+      };
+      req.flags = content.flags;
+      cb_extract_timeout(req, options);
+      cb_extract_expiry(req, options);
+      cb_extract_durability_level(req, options);
+      cb_extract_preserve_expiry(req, options);
+
+      std::promise<core::operations::upsert_response> promise;
+      futures.emplace_back(id.key(), promise.get_future());
+
+      if (const auto legacy_durability = extract_legacy_durability_constraints(options);
+          legacy_durability.has_value()) {
+        cluster.execute(
+          core::operations::upsert_request_with_legacy_durability{
+            std::move(req),
+            legacy_durability.value().first,
+            legacy_durability.value().second,
+          },
+          [promise = std::move(promise)](auto&& resp) mutable {
+            promise.set_value(std::forward<decltype(resp)>(resp));
+          });
+      } else {
+        cluster.execute(std::move(req), [promise = std::move(promise)](auto&& resp) mutable {
+          promise.set_value(std::forward<decltype(resp)>(resp));
+        });
+      }
     }
 
     VALUE res = rb_ary_new_capa(static_cast<long>(num_of_tuples));
     for (auto& [id, f] : futures) {
-      auto [err, resp] = f.get();
-      VALUE entry = to_mutation_result_value(resp);
-      if (err.ec()) {
+      auto resp = f.get();
+      VALUE entry;
+      if (resp.ctx.ec()) {
+        entry = rb_hash_new();
         static const auto sym_error = rb_id2sym(rb_intern("error"));
-        rb_hash_aset(entry, sym_error, cb_map_error(err, "unable (multi)upsert"));
+        rb_hash_aset(entry, sym_error, cb_map_error(resp.ctx, "unable (multi)upsert"));
+      } else {
+        entry = cb_create_mutation_result(resp);
       }
       static const auto sym_id = rb_id2sym(rb_intern("id"));
       rb_hash_aset(entry, sym_id, cb_str_new(id));
       rb_ary_push(res, entry);
     }
     return res;
+
   } catch (const std::system_error& se) {
     rb_exc_raise(cb_map_error_code(
       se.code(), fmt::format("failed to perform {}: {}", __func__, se.what()), false));
@@ -278,50 +342,69 @@ cb_Backend_document_remove_multi(VALUE self,
                                  VALUE id_cas,
                                  VALUE options)
 {
-  auto cluster = cb_backend_to_public_api_cluster(self);
+  auto cluster = cb_backend_to_core_api_cluster(self);
 
+  Check_Type(bucket, T_STRING);
+  Check_Type(scope, T_STRING);
+  Check_Type(collection, T_STRING);
   if (!NIL_P(options)) {
     Check_Type(options, T_HASH);
   }
 
   try {
-    couchbase::remove_options opts;
-    set_timeout(opts, options);
-    set_durability(opts, options);
-
-    std::vector<std::pair<std::string, couchbase::cas>> tuples{};
-    cb_extract_array_of_id_cas(tuples, id_cas);
-
-    auto c = cluster.bucket(cb_string_new(bucket))
-               .scope(cb_string_new(scope))
-               .collection(cb_string_new(collection));
+    std::vector<std::pair<core::document_id, couchbase::cas>> tuples{};
+    cb_extract_array_of_id_cas(tuples, bucket, scope, collection, id_cas);
 
     auto num_of_tuples = tuples.size();
-    std::vector<
-      std::pair<std::string, std::future<std::pair<couchbase::error, couchbase::mutation_result>>>>
-      futures;
+    std::vector<std::pair<std::string, std::future<core::operations::remove_response>>> futures;
     futures.reserve(num_of_tuples);
 
     for (const auto& [id, cas] : tuples) {
-      opts.cas(cas);
-      futures.emplace_back(id, c.remove(id, opts));
+      core::operations::remove_request req{
+        id,
+      };
+      cb_extract_timeout(req, options);
+      cb_extract_durability_level(req, options);
+      req.cas = cas;
+
+      std::promise<core::operations::remove_response> promise;
+      futures.emplace_back(id.key(), promise.get_future());
+
+      if (const auto legacy_durability = extract_legacy_durability_constraints(options);
+          legacy_durability.has_value()) {
+        cluster.execute(
+          core::operations::remove_request_with_legacy_durability{
+            std::move(req),
+            legacy_durability.value().first,
+            legacy_durability.value().second,
+          },
+          [promise = std::move(promise)](auto&& resp) mutable {
+            promise.set_value(std::forward<decltype(resp)>(resp));
+          });
+      } else {
+        cluster.execute(std::move(req), [promise = std::move(promise)](auto&& resp) mutable {
+          promise.set_value(std::forward<decltype(resp)>(resp));
+        });
+      }
     }
 
     VALUE res = rb_ary_new_capa(static_cast<long>(num_of_tuples));
     for (auto& [id, f] : futures) {
-      auto [ctx, resp] = f.get();
-      VALUE entry = to_mutation_result_value(resp);
-      if (ctx.ec()) {
+      auto resp = f.get();
+      VALUE entry;
+      if (resp.ctx.ec()) {
+        entry = rb_hash_new();
         static const auto sym_error = rb_id2sym(rb_intern("error"));
-        rb_hash_aset(entry, sym_error, cb_map_error(ctx, "unable (multi)remove"));
+        rb_hash_aset(entry, sym_error, cb_map_error(resp.ctx, "unable (multi)remove"));
+      } else {
+        entry = cb_create_mutation_result(resp);
       }
       static const auto sym_id = rb_id2sym(rb_intern("id"));
       rb_hash_aset(entry, sym_id, cb_str_new(id));
-
       rb_ary_push(res, entry);
     }
-
     return res;
+
   } catch (const std::system_error& se) {
     rb_exc_raise(cb_map_error_code(
       se.code(), fmt::format("failed to perform {}: {}", __func__, se.what()), false));

data/ext/rcb_observability.cxx

@@ -0,0 +1,132 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *   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.
+ */
+
+#include "rcb_observability.hxx"
+
+#include "rcb_backend.hxx"
+#include "rcb_utils.hxx"
+
+#include <core/cluster.hxx>
+#include <core/cluster_label_listener.hxx>
+#include <core/tracing/wrapper_sdk_tracer.hxx>
+
+#include <ruby.h>
+
+#include <chrono>
+#include <memory>
+
+namespace couchbase::ruby
+{
+namespace
+{
+VALUE
+core_span_to_rb_hash(std::shared_ptr<couchbase::core::tracing::wrapper_sdk_span> core_span)
+{
+  VALUE res = rb_hash_new();
+
+  static VALUE sym_name = rb_id2sym(rb_intern("name"));
+  static VALUE sym_attributes = rb_id2sym(rb_intern("attributes"));
+  static VALUE sym_start_timestamp = rb_id2sym(rb_intern("start_timestamp"));
+  static VALUE sym_end_timestamp = rb_id2sym(rb_intern("end_timestamp"));
+  static VALUE sym_children = rb_id2sym(rb_intern("children"));
+
+  VALUE attributes = rb_hash_new();
+
+  for (const auto& [key, value] : core_span->uint_tags()) {
+    rb_hash_aset(attributes, cb_str_new(key), ULL2NUM(value));
+  }
+
+  for (const auto& [key, value] : core_span->string_tags()) {
+    rb_hash_aset(attributes, cb_str_new(key), cb_str_new(value));
+  }
+
+  rb_hash_aset(res, sym_name, cb_str_new(core_span->name()));
+  rb_hash_aset(res, sym_attributes, attributes);
+  rb_hash_aset(res,
+               sym_start_timestamp,
+               LL2NUM(std::chrono::duration_cast<std::chrono::microseconds>(
+                        core_span->start_time().time_since_epoch())
+                        .count()));
+  rb_hash_aset(res,
+               sym_end_timestamp,
+               LL2NUM(std::chrono::duration_cast<std::chrono::microseconds>(
+                        core_span->end_time().time_since_epoch())
+                        .count()));
+
+  VALUE children = rb_ary_new_capa(static_cast<long>(core_span->children().size()));
+  for (const auto& child : core_span->children()) {
+    rb_ary_push(children, core_span_to_rb_hash(child));
+  }
+  rb_hash_aset(res, sym_children, children);
+
+  return res;
+}
+} // namespace
+
+void
+cb_add_core_spans(VALUE observability_handler,
+                  std::shared_ptr<couchbase::core::tracing::wrapper_sdk_span> parent_span,
+                  std::size_t retry_attempts)
+{
+  const auto children = parent_span->children();
+  VALUE spans = rb_ary_new_capa(static_cast<long>(children.size()));
+
+  for (const auto& child : parent_span->children()) {
+    rb_ary_push(spans, core_span_to_rb_hash(child));
+  }
+
+  static ID add_backend_spans_func = rb_intern("add_spans_from_backend");
+  rb_funcall(observability_handler, add_backend_spans_func, 1, spans);
+
+  static ID add_retries_func = rb_intern("add_retries");
+  rb_funcall(observability_handler, add_retries_func, 1, ULONG2NUM(retry_attempts));
+}
+
+namespace
+{
+VALUE
+cb_Backend_cluster_labels(VALUE self)
+{
+  VALUE res = rb_hash_new();
+  {
+    auto cluster = cb_backend_to_core_api_cluster(self);
+    auto labels = cluster.cluster_label_listener()->cluster_labels();
+
+    static const auto sym_cluster_name = rb_id2sym(rb_intern("cluster_name"));
+    static const auto sym_cluster_uuid = rb_id2sym(rb_intern("cluster_uuid"));
+
+    if (labels.cluster_name.has_value()) {
+      rb_hash_aset(res, sym_cluster_name, cb_str_new(labels.cluster_name.value()));
+    } else {
+      rb_hash_aset(res, sym_cluster_name, Qnil);
+    }
+    if (labels.cluster_uuid.has_value()) {
+      rb_hash_aset(res, sym_cluster_uuid, cb_str_new(labels.cluster_uuid.value()));
+    } else {
+      rb_hash_aset(res, sym_cluster_uuid, Qnil);
+    }
+  }
+  return res;
+}
+} // namespace
+
+void
+init_observability(VALUE cBackend)
+{
+  rb_define_method(cBackend, "cluster_labels", cb_Backend_cluster_labels, 0);
+}
+} // namespace couchbase::ruby