Define observability interface between core SDK and the wrapper

.github/workflows/columnar.yml

@@ -23,7 +23,7 @@ jobs:
       - name: Install build environment
         run: |
           sudo apt-get update -y
-          sudo apt-get install -y libssl-dev cmake gcc g++ curl gdb
+          sudo apt-get install -y libssl-dev cmake gcc g++ curl gdb libcurl4-openssl-dev libprotobuf-dev libgrpc-dev gdb
       - uses: actions/checkout@v4
         with:
           submodules: recursive

.github/workflows/linters.yml

@@ -48,7 +48,7 @@ jobs:
       - name: Install dependencies
         run: |
           sudo apt-get update -y
-          sudo apt-get install -y libssl-dev cmake curl wget gnupg2
+          sudo apt-get install -y libssl-dev cmake curl wget gnupg2 libcurl4-openssl-dev libprotobuf-dev libgrpc-dev libgrpc++-dev gdb protobuf-compiler protobuf-compiler-grpc
           wget -O - https://apt.llvm.org/llvm-snapshot.gpg.key | sudo gpg --dearmor --output /etc/apt/keyrings/llvm-snapshot.gpg
           sudo bash -c "echo 'deb [signed-by=/etc/apt/keyrings/llvm-snapshot.gpg] https://apt.llvm.org/noble/ llvm-toolchain-noble-${LLVM_VERSION} main' >> /etc/apt/sources.list"
           sudo apt-get update -y
@@ -75,7 +75,7 @@ jobs:
       - name: Install dependencies
         run: |
           sudo apt-get update -y
-          sudo apt-get install -y libssl-dev cmake curl wget gnupg2 cppcheck
+          sudo apt-get install -y libssl-dev cmake curl wget gnupg2 clang clang-tools cppcheck libcurl4-openssl-dev libprotobuf-dev libgrpc-dev libgrpc++-dev gdb protobuf-compiler protobuf-compiler-grpc
       - name: Run cppcheck
         run: ./bin/check-cppcheck
 
@@ -88,7 +88,7 @@ jobs:
       - name: Install dependencies
         run: |
           sudo apt-get update -y
-          sudo apt-get install -y libssl-dev cmake curl wget gnupg2
+          sudo apt-get install -y libssl-dev cmake curl wget gnupg2 clang clang-tools clang-tidy libcurl4-openssl-dev libprotobuf-dev libgrpc-dev libgrpc++-dev gdb protobuf-compiler protobuf-compiler-grpc
           wget -O - https://apt.llvm.org/llvm-snapshot.gpg.key | sudo gpg --dearmor --output /etc/apt/keyrings/llvm-snapshot.gpg
           sudo bash -c "echo 'deb [signed-by=/etc/apt/keyrings/llvm-snapshot.gpg] https://apt.llvm.org/noble/ llvm-toolchain-noble-${LLVM_VERSION} main' >> /etc/apt/sources.list"
           sudo apt-get update -y

.github/workflows/sanitizers.yml

@@ -31,7 +31,7 @@ jobs:
       - name: Install dependencies
         run: |
           sudo apt-get update -y
-          sudo apt-get install -y libssl-dev cmake curl wget gnupg2 gdb clang clang-tools valgrind
+          sudo apt-get install -y libssl-dev cmake curl wget gnupg2 libcurl4-openssl-dev libprotobuf-dev libgrpc-dev gdb clang clang-tools valgrind
       - uses: actions/checkout@v4
         with:
           submodules: recursive

.github/workflows/tests.yml

@@ -26,7 +26,7 @@ jobs:
       - name: Install dependencies
         run: |
           sudo apt-get update -y
-          sudo apt-get install -y libssl-dev cmake gcc g++ curl gdb
+          sudo apt-get install -y libssl-dev cmake gcc g++ curl libcurl4-openssl-dev libprotobuf-dev libgrpc-dev libgrpc++-dev gdb protobuf-compiler protobuf-compiler-grpc
       - uses: actions/checkout@v4
         with:
           submodules: recursive

CMakeLists.txt

@@ -75,15 +75,20 @@ set(couchbase_cxx_client_FILES
     core/agent_group.cxx
     core/agent_group_config.cxx
     core/analytics_query_options.cxx
+    core/app_telemetry_address.cxx
+    core/app_telemetry_meter.cxx
+    core/app_telemetry_reporter.cxx
     core/bucket.cxx
+    core/chrono_utils.cxx
     core/cluster.cxx
     core/cluster_agent.cxx
     core/cluster_agent_config.cxx
+    core/cluster_credentials.cxx
     core/cluster_options.cxx
     core/collections_component.cxx
+    core/columnar/backoff_calculator.cxx
     core/columnar/columnar_agent.cxx
     core/columnar/columnar_agent_config.cxx
-    core/columnar/backoff_calculator.cxx
     core/columnar/columnar_error.cxx
     core/columnar/error_codes.cxx
     core/columnar/management_component.cxx
@@ -96,6 +101,7 @@ set(couchbase_cxx_client_FILES
     core/dispatcher.cxx
     core/document_id.cxx
     core/error_context/key_value.cxx
+    core/file_signal_sink.cxx
     core/free_form_http_request.cxx
     core/http_component.cxx
     core/impl/analytics.cxx
@@ -105,14 +111,13 @@ set(couchbase_cxx_client_FILES
     core/impl/binary_collection.cxx
     core/impl/boolean_field_query.cxx
     core/impl/boolean_query.cxx
-    core/impl/public_bucket.cxx
     core/impl/bucket_manager.cxx
-    core/impl/public_cluster.cxx
     core/impl/collection.cxx
     core/impl/collection_manager.cxx
     core/impl/common_error_category.cxx
     core/impl/configuration_profiles_registry.cxx
     core/impl/conjunction_query.cxx
+    core/impl/crypto.cxx
     core/impl/date_range.cxx
     core/impl/date_range_facet.cxx
     core/impl/date_range_facet_result.cxx
@@ -141,7 +146,6 @@ set(couchbase_cxx_client_FILES
     core/impl/internal_term_facet_result.cxx
     core/impl/key_value_error_category.cxx
     core/impl/key_value_error_context.cxx
-    core/impl/public_logger.cxx
     core/impl/lookup_in_replica.cxx
     core/impl/management_error_category.cxx
     core/impl/match_all_query.cxx
@@ -157,6 +161,11 @@ set(couchbase_cxx_client_FILES
     core/impl/observe_seqno.cxx
     core/impl/phrase_query.cxx
     core/impl/prefix_query.cxx
+    core/impl/public_bucket.cxx
+    core/impl/public_cluster.cxx
+    core/impl/public_logger.cxx
+    core/impl/public_scan_result.cxx
+    core/impl/public_transaction_get_result.cxx
     core/impl/query.cxx
     core/impl/query_error_category.cxx
     core/impl/query_error_context.cxx
@@ -166,7 +175,6 @@ set(couchbase_cxx_client_FILES
     core/impl/replica_utils.cxx
     core/impl/retry_action.cxx
     core/impl/retry_reason.cxx
-    core/impl/public_scan_result.cxx
     core/impl/scope.cxx
     core/impl/search.cxx
     core/impl/search_error_category.cxx
@@ -206,13 +214,11 @@ set(couchbase_cxx_client_FILES
     core/impl/transaction_error_category.cxx
     core/impl/transaction_get_multi_replicas_from_preferred_server_group_spec.cxx
     core/impl/transaction_get_multi_spec.cxx
-    core/impl/public_transaction_get_result.cxx
     core/impl/transaction_op_error_category.cxx
     core/impl/vector_query.cxx
     core/impl/vector_search.cxx
     core/impl/view_error_category.cxx
     core/impl/wildcard_query.cxx
-    core/impl/crypto.cxx
     core/io/config_tracker.cxx
     core/io/dns_client.cxx
     core/io/dns_config.cxx
@@ -225,6 +231,7 @@ set(couchbase_cxx_client_FILES
     core/io/mcbp_session.cxx
     core/io/streams.cxx
     core/key_value_config.cxx
+    core/log_entry.cxx
     core/logger/custom_rotating_file_sink.cxx
     core/logger/logger.cxx
     core/management/analytics_link_azure_blob_external.cxx
@@ -241,6 +248,7 @@ set(couchbase_cxx_client_FILES
     core/mcbp/queue_request.cxx
     core/mcbp/server_duration.cxx
     core/meta/version.cxx
+    core/metric_measurement.cxx
     core/metrics/logging_meter.cxx
     core/metrics/meter_wrapper.cxx
     core/n1ql_query_options.cxx
@@ -339,6 +347,7 @@ set(couchbase_cxx_client_FILES
     core/operations/management/view_index_get_all.cxx
     core/operations/management/view_index_upsert.cxx
     core/origin.cxx
+    core/orphan_reporter.cxx
     core/platform/base64.cc
     core/platform/dirutils.cc
     core/platform/random.cc
@@ -393,8 +402,11 @@ set(couchbase_cxx_client_FILES
     core/scan_result.cxx
     core/search_query_options.cxx
     core/seed_config.cxx
+    core/signal_bridge.cxx
+    core/signal_data.cxx
     core/topology/capabilities.cxx
     core/topology/configuration.cxx
+    core/trace_span.cxx
     core/tracing/threshold_logging_tracer.cxx
     core/tracing/tracer_wrapper.cxx
     core/transactions/active_transaction_record.cxx
@@ -432,11 +444,6 @@ set(couchbase_cxx_client_FILES
     core/utils/url_codec.cxx
     core/view_query_options.cxx
     core/websocket_codec.cxx
-    core/app_telemetry_address.cxx
-    core/app_telemetry_meter.cxx
-    core/app_telemetry_reporter.cxx
-    core/cluster_credentials.cxx
-    core/orphan_reporter.cxx
 )
 
 set(couchbase_cxx_client_LIBRARIES)

bin/validate-test-labels

@@ -1,52 +1,50 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
-require 'find'
-require 'set'
+require "find"
 
-ALLOWED_LABELS = [
-    'unit',
-    'integration',
-    'benchmark',
-    'transactions',
+ALLOWED_LABELS = %w[
+  unit
+  integration
+  benchmark
+  transactions
 ].freeze
 
-test_dir = File.expand_path('../test', __dir__)
+test_dir = File.expand_path("../test", __dir__)
 tests_missing_label = []
-invalid_labels = Set[]
+tests_missing_allowed_label = []
 
 Find.find(test_dir) do |path|
-    next unless File.file?(path)
-    next unless File.basename(path).start_with?('test_')
-    content = File.read(path)
-    content.delete("\n").scan(/TEST_CASE\(("(.*?)")\)/) do |match|
-        labels = match[0].scan(/\[(.*?)\]/)
-        if labels.empty?
-            tests_missing_label << "#{match[0]} (#{path})"
-        else
-            labels.flatten.each do |label|
-                unless ALLOWED_LABELS.include?(label)
-                    invalid_labels << label
-                end
-            end
-        end
+  next unless File.file?(path)
+  next unless File.basename(path).start_with?("test_")
+
+  content = File.read(path)
+  content.delete("\n").scan(/TEST_CASE\(("(.*?)")\)/) do |match|
+    test_name = "#{match[0]} (#{path})"
+    labels = match[0].scan(/\[(.*?)\]/)
+    if labels.empty?
+      tests_missing_label << test_name
+    elsif !labels.flatten.intersect?(ALLOWED_LABELS)
+      tests_missing_allowed_label << test_name
     end
+  end
 end
 
 unless tests_missing_label.empty?
-    puts "Tests missing label:"
-    tests_missing_label.each do |test|
-        puts "  #{test}"
-    end
+  puts "Tests missing label:"
+  tests_missing_label.each do |test|
+    puts "  #{test}"
+  end
 end
 
-unless invalid_labels.empty?
-    puts "Invalid labels found:"
-    invalid_labels.each do |label|
-        puts "  #{label}"
-    end
+unless tests_missing_allowed_label.empty?
+  puts "Tests have labels, but missing allowed ones:"
+  tests_missing_allowed_label.each do |label|
+    puts "  #{label}"
+  end
 end
 
-unless tests_missing_label.empty? && invalid_labels.empty?
-    puts "\nERROR: Missing or unexpected test labels found. This can result in tests not being run in CI."
-    exit 1
+unless tests_missing_label.empty? && tests_missing_allowed_label.empty?
+  puts "\nERROR: Missing or unexpected test labels found. This can result in tests not being run in CI."
+  exit 1
 end

cmake/ThirdPartyDependencies.cmake

@@ -39,6 +39,34 @@ if(NOT TARGET spdlog::spdlog)
     "SPDLOG_FMT_EXTERNAL OFF")
 endif()
 
+if(NOT TARGET opentelemetry)
+  # https://github.com/open-telemetry/opentelemetry-cpp/releases
+  cpmaddpackage(
+    NAME
+    opentelemetry
+    VERSION
+    1.23.0
+    GITHUB_REPOSITORY
+    "open-telemetry/opentelemetry-cpp"
+    EXCLUDE_FROM_ALL ON
+    OPTIONS
+    "OPENTELEMETRY_INSTALL OFF"
+    "WITH_ABI_VERSION_1 OFF"
+    "WITH_ABI_VERSION_2 ON"
+    "WITH_ABSEIL OFF"
+    "WITH_BENCHMARK OFF"
+    "WITH_EXAMPLES OFF"
+    "WITH_FUNC_TESTS OFF"
+    "WITH_OTLP_GRPC ON"
+    "WITH_OTLP_HTTP ON"
+    "WITH_STL CXX17"
+    "BUILD_TESTING OFF"
+    "BUILD_SHARED_LIBS OFF"
+    "CMAKE_C_VISIBILITY_PRESET hidden"
+    "CMAKE_CXX_VISIBILITY_PRESET hidden"
+    "CMAKE_POSITION_INDEPENDENT_CODE ON")
+endif()
+
 if(NOT TARGET Microsoft.GSL::GSL)
   # https://github.com/microsoft/GSL/releases
   cpmaddpackage(
@@ -264,3 +292,7 @@ declare_system_library(Microsoft.GSL::GSL)
 declare_system_library(spdlog::spdlog)
 declare_system_library(asio)
 declare_system_library(taocpp::json)
+declare_system_library(snappy)
+
+declare_system_library(opentelemetry_exporter_otlp_http)
+declare_system_library(opentelemetry_exporter_otlp_http_metric)

core/chrono_utils.cxx

@@ -0,0 +1,63 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *   Copyright 2025-Current 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 "chrono_utils.hxx"
+
+#include <array>
+#include <chrono>
+#include <stdexcept>
+
+namespace couchbase::core
+{
+auto
+to_iso8601_utc(std::time_t time_in_seconds, std::int64_t microseconds) -> std::string
+{
+  std::tm tm{};
+#if defined(_MSC_VER)
+  gmtime_s(&tm, &time_in_seconds);
+#else
+  gmtime_r(&time_in_seconds, &tm);
+#endif
+
+  std::array<char, 100> buffer{};
+  auto rc = std::snprintf(buffer.data(),
+                          buffer.size(),
+                          "%04d-%02d-%02dT%02d:%02d:%02d.%06lldZ",
+                          tm.tm_year + 1900,
+                          tm.tm_mon + 1,
+                          tm.tm_mday,
+                          tm.tm_hour,
+                          tm.tm_min,
+                          tm.tm_sec,
+                          static_cast<long long>(microseconds));
+  auto bytes_written = static_cast<std::size_t>(rc);
+  if (rc < 0 || bytes_written >= buffer.size()) {
+    throw std::range_error("unable to format date: not enough memory in the buffer");
+  }
+  return { buffer.data(), bytes_written };
+}
+
+auto
+to_iso8601_utc(const std::chrono::system_clock::time_point& time_point) -> std::string
+{
+  const auto duration{ time_point.time_since_epoch() };
+  const auto seconds{ std::chrono::duration_cast<std::chrono::seconds>(duration) };
+  const auto micros{ std::chrono::duration_cast<std::chrono::microseconds>(duration - seconds) };
+
+  return to_iso8601_utc(std::chrono::system_clock::to_time_t(time_point), micros.count());
+}
+} // namespace couchbase::core