couchbase 3.7.0 → 3.8.1

data/ext/couchbase/couchbase/metrics/otel_meter.hxx

@@ -17,75 +17,50 @@
 
 #pragma once
 
-#include "opentelemetry/sdk/metrics/meter.h"
 #include <couchbase/metrics/meter.hxx>
 
+#include <opentelemetry/context/context.h>
+#include <opentelemetry/metrics/meter.h>
+#include <opentelemetry/metrics/sync_instruments.h>
+
 #include <algorithm>
-#include <iostream>
-#include <thread>
+#include <memory>
+#include <mutex>
+#include <shared_mutex>
 #include <utility>
-
-using couchbase::metrics::meter;
-using couchbase::metrics::value_recorder;
-
-namespace nostd = opentelemetry::nostd;
-namespace metrics_api = opentelemetry::metrics;
-namespace metrics_sdk = opentelemetry::sdk::metrics;
+#include <variant>
 
 namespace couchbase::metrics
 {
-
-class otel_sync_histogram
-{
-public:
-  otel_sync_histogram(nostd::shared_ptr<metrics_api::Histogram<std::uint64_t>> histogram_counter)
-    : histogram_counter_(histogram_counter)
-  {
-  }
-
-  void record(std::uint64_t value,
-              const opentelemetry::common::KeyValueIterable& tags,
-              opentelemetry::context::Context& ctx)
-  {
-    histogram_counter_->Record(value, tags, ctx);
-  }
-
-private:
-  nostd::shared_ptr<metrics_api::Histogram<std::uint64_t>> histogram_counter_;
-  std::mutex mutex_;
-};
-
+template<typename T>
 class otel_value_recorder : public couchbase::metrics::value_recorder
 {
 public:
   explicit otel_value_recorder(
-    nostd::shared_ptr<metrics_api::Histogram<std::uint64_t>> histogram_counter,
+    opentelemetry::nostd::shared_ptr<opentelemetry::metrics::Histogram<T>> histogram,
     const std::map<std::string, std::string>& tags)
-    : histogram_counter_(histogram_counter)
-    , tags_(tags)
-  {
-  }
-  void record_value(std::int64_t value) override
+    : histogram_{ std::move(histogram) }
+    , tags_{ tags }
   {
-    value = std::max<int64_t>(value, 0);
-    auto uvalue = static_cast<std::uint64_t>(value);
-    histogram_counter_->Record(
-      uvalue, opentelemetry::common::KeyValueIterableView<decltype(tags_)>{ tags_ }, context_);
+    tags_.erase("__unit");
   }
 
-  const std::map<std::string, std::string> tags()
-  {
-    return tags_;
-  }
-
-  nostd::shared_ptr<metrics_api::Histogram<std::uint64_t>> histogram_counter()
+  void record_value(std::int64_t value) override
   {
-    return histogram_counter_;
+    if constexpr (std::is_same_v<T, double>) {
+      auto value_in_seconds = static_cast<double>(value) / 1'000'000.0;
+      histogram_->Record(
+        value_in_seconds, opentelemetry::common::KeyValueIterableView{ tags_ }, context_);
+    } else {
+      value = std::max<int64_t>(value, 0);
+      auto uvalue = static_cast<std::uint64_t>(value);
+      histogram_->Record(uvalue, opentelemetry::common::KeyValueIterableView{ tags_ }, context_);
+    }
   }
 
 private:
-  nostd::shared_ptr<metrics_api::Histogram<std::uint64_t>> histogram_counter_;
-  const std::map<std::string, std::string> tags_;
+  opentelemetry::nostd::shared_ptr<opentelemetry::metrics::Histogram<T>> histogram_;
+  std::map<std::string, std::string> tags_{};
   opentelemetry::context::Context context_{};
   std::mutex mutex_;
 };
@@ -93,47 +68,67 @@ private:
 class otel_meter : public couchbase::metrics::meter
 {
 public:
-  explicit otel_meter(nostd::shared_ptr<metrics_api::Meter> meter)
-    : meter_(meter)
+  explicit otel_meter(opentelemetry::nostd::shared_ptr<opentelemetry::metrics::Meter> meter)
+    : meter_{ std::move(meter) }
   {
   }
 
   auto get_value_recorder(const std::string& name, const std::map<std::string, std::string>& tags)
     -> std::shared_ptr<value_recorder> override
   {
-    // first look up the histogram, in case we already have it...
-    std::scoped_lock<std::mutex> lock(mutex_);
-    auto it = recorders_.equal_range(name);
-    if (it.first == it.second) {
-      // this name isn't associated with any histogram, so make one and return it.
-      // Note we'd like to make one with more buckets than default, given the range of
-      // response times we'd like to display (queries vs kv for instance), but otel
-      // api doesn't seem to allow this.
-      return recorders_
-        .insert({ name,
-                  std::make_shared<otel_value_recorder>(
-                    meter_->CreateUInt64Histogram(name, "", "us"), tags) })
-        ->second;
+    bool in_seconds{ false };
+    if (tags.count("__unit") > 0) {
+      if (tags.at("__unit") == "s") {
+        in_seconds = true;
+      }
     }
-    // so it is already, lets see if we already have one with those tags, or need
-    // to make a new one (using the histogram we already have).
-    for (auto itr = it.first; itr != it.second; itr++) {
-      if (tags == itr->second->tags()) {
-        return itr->second;
+
+    {
+      // Check if we already have the histogram
+      std::shared_lock lock(mutex_);
+      if (in_seconds) {
+        if (const auto it = double_histograms_.find(name); it != double_histograms_.end()) {
+          return std::make_shared<otel_value_recorder<double>>(it->second, tags);
+        }
+      } else {
+        if (const auto it = uint_histograms_.find(name); it != uint_histograms_.end()) {
+          return std::make_shared<otel_value_recorder<std::uint64_t>>(it->second, tags);
+        }
+      }
+    }
+
+    {
+      // We have to check if we already have the histogram again, before creating it, in case
+      // another thread created it while we were waiting for  the exclusive lock
+      std::scoped_lock lock(mutex_);
+      if (in_seconds) {
+        if (const auto it = double_histograms_.find(name); it != double_histograms_.end()) {
+          return std::make_shared<otel_value_recorder<double>>(it->second, tags);
+        }
+        // Not found, we have to create it
+        auto histogram = meter_->CreateDoubleHistogram(name, "", "s");
+        double_histograms_.emplace(name, std::move(histogram));
+        return std::make_shared<otel_value_recorder<double>>(double_histograms_.at(name), tags);
+      } else {
+        if (const auto it = uint_histograms_.find(name); it != uint_histograms_.end()) {
+          return std::make_shared<otel_value_recorder<std::uint64_t>>(it->second, tags);
+        }
+        // Not found, we have to create it
+        auto histogram = meter_->CreateUInt64Histogram(name);
+        uint_histograms_.emplace(name, std::move(histogram));
+        return std::make_shared<otel_value_recorder<std::uint64_t>>(uint_histograms_.at(name),
+                                                                    tags);
       }
     }
-    // if you are here, we need to add one with these tags and the histogram associated with the
-    // name.
-    return recorders_
-      .insert(
-        { name,
-          std::make_shared<otel_value_recorder>(it.first->second->histogram_counter(), tags) })
-      ->second;
   }
 
 private:
-  nostd::shared_ptr<metrics_api::Meter> meter_;
-  std::mutex mutex_;
-  std::multimap<std::string, std::shared_ptr<otel_value_recorder>> recorders_;
+  opentelemetry::nostd::shared_ptr<opentelemetry::metrics::Meter> meter_;
+  std::shared_mutex mutex_;
+  std::map<std::string, opentelemetry::nostd::shared_ptr<opentelemetry::metrics::Histogram<double>>>
+    double_histograms_;
+  std::map<std::string,
+           opentelemetry::nostd::shared_ptr<opentelemetry::metrics::Histogram<std::uint64_t>>>
+    uint_histograms_;
 };
 } // namespace couchbase::metrics

data/ext/couchbase/couchbase/network_options.hxx

@@ -114,6 +114,22 @@ public:
     return *this;
   }
 
+  /**
+   * Enables or disables lazy connection of data endpoints.
+   *
+   * When enabled, connections are established only when the first operation for a given endpoint is
+   * scheduled, rather than at cluster object construction time.
+   *
+   * @volatile This option is considered unstable and may change in future releases.
+   *
+   * @since 1.3.0
+   */
+  auto enable_lazy_connections(bool enable) -> network_options&
+  {
+    enable_lazy_connections_ = enable;
+    return *this;
+  }
+
   struct built {
     std::string network;
     std::string server_group;
@@ -123,6 +139,7 @@ public:
     std::chrono::milliseconds config_poll_interval;
     std::chrono::milliseconds idle_http_connection_timeout;
     std::optional<std::size_t> max_http_connections;
+    bool enable_lazy_connections;
   };
 
   [[nodiscard]] auto build() const -> built
@@ -136,6 +153,7 @@ public:
       config_poll_interval_,
       idle_http_connection_timeout_,
       max_http_connections_,
+      enable_lazy_connections_,
     };
   }
 
@@ -149,5 +167,6 @@ private:
   std::chrono::milliseconds config_poll_floor_{ default_config_poll_floor };
   std::chrono::milliseconds idle_http_connection_timeout_{ default_idle_http_connection_timeout };
   std::optional<std::size_t> max_http_connections_{};
+  bool enable_lazy_connections_{ false };
 };
 } // namespace couchbase

data/ext/couchbase/couchbase/node_id.hxx

@@ -0,0 +1,123 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *   Copyright 2024-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.
+ */
+
+#pragma once
+
+#include <cstdint>
+#include <functional>
+#include <string>
+
+namespace couchbase
+{
+
+/**
+ * Uniquely identifies a cluster node.
+ *
+ * On Couchbase Server 8.0.1+ the identifier is the server-assigned node UUID.
+ * On older releases, a stable opaque token is derived from the node's hostname
+ * and management port.
+ *
+ * The type is equality-comparable, ordered, and hashable.
+ *
+ * @since 1.3.2
+ * @uncommitted
+ */
+class node_id
+{
+public:
+  /**
+   * Creates an empty (invalid) node_id.
+   *
+   * @since 1.3.2
+   * @uncommitted
+   */
+  node_id() = default;
+
+  /**
+   * User-facing identifier string.
+   *
+   * Returns node_uuid when the server provides one, otherwise a stable
+   * hex-encoded hash derived from hostname and management port.
+   *
+   * @return opaque identifier string (empty for default-constructed instances)
+   *
+   * @since 1.3.2
+   * @uncommitted
+   */
+  [[nodiscard]] auto id() const -> const std::string&;
+
+  /**
+   * The server-assigned node UUID (empty on servers before 8.0.1).
+   *
+   * @since 1.3.2
+   * @uncommitted
+   */
+  [[nodiscard]] auto node_uuid() const -> const std::string&;
+
+  /**
+   * The hostname of the node.
+   *
+   * @since 1.3.2
+   * @uncommitted
+   */
+  [[nodiscard]] auto hostname() const -> const std::string&;
+
+  /**
+   * The port of the node's key-value service.
+   *
+   * This reflects the port actually used by the client: the TLS port when the
+   * cluster connection is TLS-enabled, otherwise the plain port.
+   *
+   * @since 1.3.2
+   * @uncommitted
+   */
+  [[nodiscard]] auto port() const -> std::uint16_t;
+
+  /**
+   * Returns true when the node_id was properly initialized (not default-constructed).
+   *
+   * @since 1.3.2
+   * @uncommitted
+   */
+  explicit operator bool() const;
+
+  auto operator==(const node_id& other) const -> bool;
+  auto operator!=(const node_id& other) const -> bool;
+  auto operator<(const node_id& other) const -> bool;
+
+private:
+  friend class internal_node_id;
+
+  node_id(std::string node_uuid, std::string hostname, std::uint16_t port);
+
+  std::string node_uuid_{};
+  std::string hostname_{};
+  std::uint16_t port_{ 0 };
+  // Computed once at construction: node_uuid_ if non-empty, otherwise a
+  // deterministic hex-encoded CRC32 hash of "hostname:port".
+  std::string id_{};
+};
+
+} // namespace couchbase
+
+template<>
+struct std::hash<couchbase::node_id> {
+  auto operator()(const couchbase::node_id& nid) const noexcept -> std::size_t
+  {
+    return std::hash<std::string>{}(nid.id());
+  }
+};

data/ext/couchbase/couchbase/node_id_for_options.hxx

@@ -0,0 +1,61 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *   Copyright 2024-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.
+ */
+
+#pragma once
+
+#include <couchbase/common_options.hxx>
+#include <couchbase/error.hxx>
+#include <couchbase/node_id.hxx>
+
+#include <functional>
+
+namespace couchbase
+{
+
+/**
+ * Options for @ref collection#node_id_for().
+ *
+ * @since 1.3.2
+ * @uncommitted
+ */
+struct node_id_for_options : public common_options<node_id_for_options> {
+  /**
+   * Immutable value object representing consistent options.
+   *
+   * @since 1.3.2
+   * @internal
+   */
+  struct built : public common_options<node_id_for_options>::built {
+  };
+
+  /**
+   * Validates options and returns them as an immutable value.
+   *
+   * @return consistent options as an immutable value
+   *
+   * @since 1.3.2
+   * @internal
+   */
+  [[nodiscard]] auto build() const -> built
+  {
+    return { build_common_options() };
+  }
+};
+
+using node_id_for_handler = std::function<void(error, node_id)>;
+
+} // namespace couchbase

data/ext/couchbase/couchbase/node_ids_options.hxx

@@ -0,0 +1,62 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *   Copyright 2024-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.
+ */
+
+#pragma once
+
+#include <couchbase/common_options.hxx>
+#include <couchbase/error.hxx>
+#include <couchbase/node_id.hxx>
+
+#include <functional>
+#include <vector>
+
+namespace couchbase
+{
+
+/**
+ * Options for @ref collection#node_ids().
+ *
+ * @since 1.3.2
+ * @uncommitted
+ */
+struct node_ids_options : public common_options<node_ids_options> {
+  /**
+   * Immutable value object representing consistent options.
+   *
+   * @since 1.3.2
+   * @internal
+   */
+  struct built : public common_options<node_ids_options>::built {
+  };
+
+  /**
+   * Validates options and returns them as an immutable value.
+   *
+   * @return consistent options as an immutable value
+   *
+   * @since 1.3.2
+   * @internal
+   */
+  [[nodiscard]] auto build() const -> built
+  {
+    return { build_common_options() };
+  }
+};
+
+using node_ids_handler = std::function<void(error, std::vector<node_id>)>;
+
+} // namespace couchbase

data/ext/couchbase/couchbase/password_authenticator.hxx

@@ -43,5 +43,6 @@ private:
   bool ldap_compatible_{ false };
 
   friend class cluster_options;
+  friend class cluster;
 };
 } // namespace couchbase

data/ext/couchbase/couchbase/result.hxx

@@ -18,6 +18,9 @@
 #pragma once
 
 #include <couchbase/cas.hxx>
+#include <couchbase/node_id.hxx>
+
+#include <utility>
 
 namespace couchbase
 {
@@ -48,6 +51,19 @@ public:
   {
   }
 
+  /**
+   * @param cas
+   * @param node_id identity of the node that served the request
+   *
+   * @since 1.3.2
+   * @uncommitted
+   */
+  result(couchbase::cas cas, couchbase::node_id node_id)
+    : cas_(cas)
+    , node_id_(std::move(node_id))
+  {
+  }
+
   /**
    * @return
    *
@@ -59,8 +75,34 @@ public:
     return cas_;
   }
 
+  /**
+   * Returns the identity of the cluster node that served this request.
+   *
+   * The returned node_id is default-constructed (falsy) when the node
+   * could not be determined.
+   *
+   * @return identity of the serving node
+   *
+   * @since 1.3.2
+   * @uncommitted
+   */
+  [[nodiscard]] auto node_id() const -> const couchbase::node_id&
+  {
+    return node_id_;
+  }
+
+  /**
+   * @since 1.3.2
+   * @internal
+   */
+  void node_id(couchbase::node_id id)
+  {
+    node_id_ = std::move(id);
+  }
+
 private:
   couchbase::cas cas_{ 0U };
+  couchbase::node_id node_id_{};
 };
 
 } // namespace couchbase

data/ext/couchbase/couchbase/tracing/otel_tracer.hxx

@@ -18,18 +18,15 @@
 #pragma once
 
 #include <couchbase/tracing/request_tracer.hxx>
-#include <opentelemetry/exporters/ostream/span_exporter.h>
-#include <opentelemetry/sdk/trace/simple_processor.h>
-#include <opentelemetry/sdk/trace/tracer_provider.h>
+
 #include <opentelemetry/trace/tracer.h>
 
-namespace nostd = opentelemetry::nostd;
 namespace couchbase::tracing
 {
 class otel_request_span : public couchbase::tracing::request_span
 {
 public:
-  explicit otel_request_span(nostd::shared_ptr<opentelemetry::trace::Span> span)
+  explicit otel_request_span(opentelemetry::nostd::shared_ptr<opentelemetry::trace::Span> span)
     : span_(std::move(span))
   {
   }
@@ -45,42 +42,43 @@ public:
   {
     span_->End();
   }
-  nostd::shared_ptr<opentelemetry::trace::Span> wrapped_span()
+  auto wrapped_span() -> opentelemetry::nostd::shared_ptr<opentelemetry::trace::Span>
   {
     return span_;
   }
 
 private:
-  nostd::shared_ptr<opentelemetry::trace::Span> span_;
+  opentelemetry::nostd::shared_ptr<opentelemetry::trace::Span> span_;
 };
 
 class otel_request_tracer : public couchbase::tracing::request_tracer
 {
 public:
-  otel_request_tracer(nostd::shared_ptr<opentelemetry::trace::Tracer> tracer)
+  explicit otel_request_tracer(
+    opentelemetry::nostd::shared_ptr<opentelemetry::trace::Tracer> tracer)
     : tracer_(std::move(tracer))
   {
   }
 
-  auto start_span(std::string name, std::shared_ptr<couchbase::tracing::request_span> parent = {})
+  auto start_span(std::string name, std::shared_ptr<couchbase::tracing::request_span> parent)
     -> std::shared_ptr<couchbase::tracing::request_span> override
   {
-    auto wrapped_parent = std::dynamic_pointer_cast<otel_request_span>(parent);
+    const auto wrapped_parent = std::dynamic_pointer_cast<otel_request_span>(parent);
+    opentelemetry::trace::StartSpanOptions opts;
+    opts.kind = opentelemetry::trace::SpanKind::kClient;
     if (wrapped_parent) {
-      opentelemetry::trace::StartSpanOptions opts;
       opts.parent = wrapped_parent->wrapped_span()->GetContext();
-      return std::make_shared<otel_request_span>(tracer_->StartSpan(name, opts));
     }
-    return std::make_shared<otel_request_span>(tracer_->StartSpan(name));
+    return std::make_shared<otel_request_span>(tracer_->StartSpan(name, opts));
   }
 
-  auto wrap_span(nostd::shared_ptr<opentelemetry::trace::Span> span)
+  auto wrap_span(opentelemetry::nostd::shared_ptr<opentelemetry::trace::Span> span)
     -> std::shared_ptr<couchbase::tracing::otel_request_span>
   {
-    return std::make_shared<couchbase::tracing::otel_request_span>(span);
+    return std::make_shared<couchbase::tracing::otel_request_span>(std::move(span));
   }
 
 private:
-  nostd::shared_ptr<opentelemetry::trace::Tracer> tracer_;
+  opentelemetry::nostd::shared_ptr<opentelemetry::trace::Tracer> tracer_;
 };
-} // namespace couchbase::tracing
+} // namespace couchbase::tracing

data/ext/couchbase/couchbase/tracing/request_span.hxx

@@ -51,12 +51,12 @@ public:
     return name_;
   }
 
-  [[nodiscard]] auto parent() const -> std::shared_ptr<request_span>
+  [[nodiscard]] virtual auto parent() const -> std::shared_ptr<request_span>
   {
     return parent_;
   }
 
-  virtual auto uses_tags() const -> bool
+  [[nodiscard]] virtual auto uses_tags() const -> bool
   {
     return true;
   }

data/ext/couchbase.cxx

@@ -25,8 +25,10 @@
 #include "rcb_diagnostics.hxx"
 #include "rcb_exceptions.hxx"
 #include "rcb_extras.hxx"
+#include "rcb_hdr_histogram.hxx"
 #include "rcb_logger.hxx"
 #include "rcb_multi.hxx"
+#include "rcb_observability.hxx"
 #include "rcb_query.hxx"
 #include "rcb_range_scan.hxx"
 #include "rcb_search.hxx"
@@ -64,5 +66,7 @@ Init_libcouchbase(void)
   couchbase::ruby::init_diagnostics(cBackend);
   couchbase::ruby::init_extras(cBackend);
   couchbase::ruby::init_logger_methods(cBackend);
+  couchbase::ruby::init_hdr_histogram(mCouchbase);
+  couchbase::ruby::init_observability(cBackend);
 }
 }

data/ext/extconf.rb

@@ -97,6 +97,7 @@ cmake_flags = [
   "-DCOUCHBASE_CXX_CLIENT_BUILD_TOOLS=OFF",
   "-DCOUCHBASE_CXX_CLIENT_BUILD_EXAMPLES=OFF",
   "-DCOUCHBASE_CXX_CLIENT_INSTALL=OFF",
+  "-DCOUCHBASE_CXX_CLIENT_BUILD_OPENTELEMETRY=OFF",
 ]
 
 if version.start_with?("4")