feat(storage): add resource span attributes for ACO ( App Centric Observability )

google/cloud/storage/async/client.h

@@ -18,6 +18,7 @@
 #include "google/cloud/storage/async/bucket_name.h"
 #include "google/cloud/storage/async/connection.h"
 #include "google/cloud/storage/async/object_descriptor.h"
+#include "google/cloud/storage/async/options.h"
 #include "google/cloud/storage/async/reader.h"
 #include "google/cloud/storage/async/rewriter.h"
 #include "google/cloud/storage/async/token.h"

google/cloud/storage/client.cc

@@ -555,7 +555,8 @@ Options DefaultOptions(Options opts) {
                                    STORAGE_CLIENT_DEFAULT_MAXIMUM_BACKOFF_DELAY,
                                    STORAGE_CLIENT_DEFAULT_BACKOFF_SCALING)
               .clone())
-      .set<IdempotencyPolicyOption>(AlwaysRetryIdempotencyPolicy().clone());
+      .set<IdempotencyPolicyOption>(AlwaysRetryIdempotencyPolicy().clone())
+      .set<storage_experimental::OTelSpanEnrichmentOption>(true);
 
   o = google::cloud::internal::MergeOptions(std::move(opts), std::move(o));
   // If the application did not set `DownloadStallTimeoutOption` then use the

google/cloud/storage/examples/storage_async_samples.cc

@@ -17,6 +17,7 @@
 // in the final rendering.
 //! [async-includes]
 #include "google/cloud/storage/async/client.h"
+#include "google/cloud/storage/async/options.h"
 #include "google/cloud/storage/async/read_all.h"
 
 //! [async-includes]

google/cloud/storage/google_cloud_cpp_storage.bzl

@@ -49,6 +49,7 @@ google_cloud_cpp_storage_hdrs = [
     "internal/binary_data_as_debug_string.h",
     "internal/bucket_access_control_parser.h",
     "internal/bucket_acl_requests.h",
+    "internal/bucket_metadata_cache.h",
     "internal/bucket_metadata_parser.h",
     "internal/bucket_requests.h",
     "internal/complex_option.h",
@@ -164,6 +165,7 @@ google_cloud_cpp_storage_srcs = [
     "internal/base64.cc",
     "internal/bucket_access_control_parser.cc",
     "internal/bucket_acl_requests.cc",
+    "internal/bucket_metadata_cache.cc",
     "internal/bucket_metadata_parser.cc",
     "internal/bucket_requests.cc",
     "internal/compute_engine_util.cc",

google/cloud/storage/google_cloud_cpp_storage.cmake

@@ -74,6 +74,8 @@ add_library(
     internal/bucket_access_control_parser.h
     internal/bucket_acl_requests.cc
     internal/bucket_acl_requests.h
+    internal/bucket_metadata_cache.cc
+    internal/bucket_metadata_cache.h
     internal/bucket_metadata_parser.cc
     internal/bucket_metadata_parser.h
     internal/bucket_requests.cc
@@ -420,6 +422,7 @@ if (BUILD_TESTING)
         idempotency_policy_test.cc
         internal/base64_test.cc
         internal/bucket_acl_requests_test.cc
+        internal/bucket_metadata_cache_test.cc
         internal/bucket_requests_test.cc
         internal/complex_option_test.cc
         internal/compute_engine_util_test.cc

google/cloud/storage/grpc_plugin.cc

@@ -18,7 +18,12 @@
 #include "google/cloud/storage/internal/grpc/default_options.h"
 #include "google/cloud/storage/internal/grpc/enable_metrics.h"
 #include "google/cloud/storage/internal/grpc/stub.h"
+#include "google/cloud/storage/internal/tracing_connection.h"
+#include "google/cloud/background_threads.h"
+#include "google/cloud/grpc_options.h"
 #include "google/cloud/internal/getenv.h"
+#include "google/cloud/internal/opentelemetry.h"
+#include <functional>
 #include <memory>
 #include <utility>
 
@@ -31,8 +36,15 @@ google::cloud::storage::Client MakeGrpcClient(Options opts) {
   opts = google::cloud::storage_internal::DefaultOptionsGrpc(std::move(opts));
   storage_internal::EnableGrpcMetrics(opts);
   auto stub = std::make_unique<storage_internal::GrpcStub>(opts);
+  storage_internal::TracingConnection::AsyncRunner runner;
+  if (google::cloud::internal::TracingEnabled(opts)) {
+    runner = [cq = stub->cq()](std::function<void()> f) mutable {
+      cq.RunAsync(std::move(f));
+    };
+  }
   return storage::internal::ClientImplDetails::CreateWithoutDecorations(
-      MakeStorageConnection(std::move(opts), std::move(stub)));
+      MakeStorageConnection(std::move(opts), std::move(stub),
+                            std::move(runner)));
 }
 
 GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_END

google/cloud/storage/grpc_plugin_test.cc

@@ -14,8 +14,10 @@
 
 #include "google/cloud/storage/grpc_plugin.h"
 #include "google/cloud/storage/options.h"
+#include "google/cloud/background_threads.h"
 #include "google/cloud/common_options.h"
 #include "google/cloud/credentials.h"
+#include "google/cloud/grpc_options.h"
 #include "google/cloud/testing_util/scoped_environment.h"
 #include <gmock/gmock.h>
 
@@ -97,6 +99,23 @@ TEST(GrpcPluginTest, GrpcMetricsExcludedLabelsOptionSingle) {
             opts.get<storage_experimental::GrpcMetricsExcludedLabelsOption>());
 }
 
+TEST(GrpcPluginTest, GrpcBackgroundThreadsFactoryOptionWithTracing) {
+  struct Fake : google::cloud::BackgroundThreads {
+    google::cloud::CompletionQueue cq() const override { return {}; }
+  };
+  bool invoked = false;
+  auto factory = [&invoked] {
+    invoked = true;
+    return std::make_unique<Fake>();
+  };
+  auto logging = ScopedEnvironment("CLOUD_STORAGE_ENABLE_TRACING", "1");
+  auto client = MakeGrpcClient(
+      TestOptions()
+          .set<GrpcBackgroundThreadsFactoryOption>(factory)
+          .set<storage_experimental::OTelSpanEnrichmentOption>(true));
+  EXPECT_TRUE(invoked);
+}
+
 }  // namespace
 GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_END
 }  // namespace storage

google/cloud/storage/internal/bucket_metadata_cache.cc

@@ -0,0 +1,104 @@
+// Copyright 2026 Google LLC
+//
+// 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
+//
+//     https://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 "google/cloud/storage/internal/bucket_metadata_cache.h"
+#include "google/cloud/storage/bucket_metadata.h"
+#include <mutex>
+#include <utility>
+
+namespace google {
+namespace cloud {
+namespace storage_internal {
+GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
+
+BucketCacheEntry BucketCacheEntry::FromMetadata(
+    storage::BucketMetadata const& m) {
+  std::string loc = m.location();
+  if (m.location_type() == "multi-region" ||
+      m.location_type() == "dual-region") {
+    loc = "global";
+  }
+  return {
+      "projects/" + std::to_string(m.project_number()) + "/buckets/" + m.name(),
+      std::move(loc)};
+}
+
+void BucketMetadataCache::MoveToFront(std::list<std::string>::iterator it) {
+  list_.splice(list_.begin(), list_, it);
+}
+
+absl::optional<BucketCacheEntry> BucketMetadataCache::Get(
+    std::string const& bucket_name) {
+  std::unique_lock<std::mutex> lk(mu_);
+  auto it = map_.find(bucket_name);
+  if (it == map_.end()) return absl::nullopt;
+
+  MoveToFront(it->second.second);
+  return it->second.first;
+}
+
+void BucketMetadataCache::Put(std::string const& bucket_name,
+                              BucketCacheEntry entry) {
+  if (max_size_ == 0) return;
+  std::unique_lock<std::mutex> lk(mu_);
+  auto it = map_.find(bucket_name);
+  if (it != map_.end()) {
+    it->second.first = std::move(entry);
+    MoveToFront(it->second.second);
+    return;
+  }
+
+  if (map_.size() >= max_size_ && !list_.empty()) {
+    auto oldest = list_.back();
+    list_.pop_back();
+    map_.erase(oldest);
+  }
+
+  list_.push_front(bucket_name);
+  map_[bucket_name] = {std::move(entry), list_.begin()};
+}
+
+void BucketMetadataCache::Invalidate(std::string const& bucket_name) {
+  std::unique_lock<std::mutex> lk(mu_);
+  auto it = map_.find(bucket_name);
+  if (it != map_.end()) {
+    list_.erase(it->second.second);
+    map_.erase(it);
+  }
+}
+
+void BucketMetadataCache::Clear() {
+  std::unique_lock<std::mutex> lk(mu_);
+  map_.clear();
+  list_.clear();
+}
+
+bool BucketMetadataCache::StartFetch(std::string const& bucket_name) {
+  std::unique_lock<std::mutex> lk(mu_);
+  if (in_flight_fetch_.find(bucket_name) != in_flight_fetch_.end()) {
+    return false;
+  }
+  in_flight_fetch_.insert(bucket_name);
+  return true;
+}
+
+void BucketMetadataCache::EndFetch(std::string const& bucket_name) {
+  std::unique_lock<std::mutex> lk(mu_);
+  in_flight_fetch_.erase(bucket_name);
+}
+
+GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_END
+}  // namespace storage_internal
+}  // namespace cloud
+}  // namespace google

google/cloud/storage/internal/bucket_metadata_cache.h

@@ -0,0 +1,99 @@
+// Copyright 2026 Google LLC
+//
+// 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
+//
+//     https://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 GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_STORAGE_INTERNAL_BUCKET_METADATA_CACHE_H
+#define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_STORAGE_INTERNAL_BUCKET_METADATA_CACHE_H
+
+#include "google/cloud/storage/version.h"
+#include "absl/types/optional.h"
+#include <cstddef>
+#include <list>
+#include <memory>
+#include <mutex>
+#include <string>
+#include <unordered_map>
+#include <unordered_set>
+#include <utility>
+
+namespace google {
+namespace cloud {
+namespace storage {
+GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
+class BucketMetadata;
+GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_END
+}  // namespace storage
+namespace storage_internal {
+GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
+
+struct BucketCacheEntry {
+  std::string id;
+  std::string location;
+
+  static BucketCacheEntry FromMetadata(storage::BucketMetadata const& m);
+};
+
+class BucketMetadataCache {
+ public:
+  explicit BucketMetadataCache(std::size_t max_size = 10000)
+      : max_size_(max_size) {}
+
+  absl::optional<BucketCacheEntry> Get(std::string const& bucket_name);
+  void Put(std::string const& bucket_name, BucketCacheEntry entry);
+  void Invalidate(std::string const& bucket_name);
+  void Clear();
+  bool StartFetch(std::string const& bucket_name);
+  void EndFetch(std::string const& bucket_name);
+
+ private:
+  void MoveToFront(std::list<std::string>::iterator it);
+
+  std::size_t max_size_;
+  std::mutex mu_;
+  std::list<std::string> list_;
+  std::unordered_map<std::string, std::pair<BucketCacheEntry,
+                                            std::list<std::string>::iterator>>
+      map_;
+  std::unordered_set<std::string> in_flight_fetch_;
+};
+
+// Tracks an in-flight fetch and clears it when destroyed.
+class ScopedFetch {
+ public:
+  ScopedFetch() = default;
+  // Shared ownership of BucketMetadataCache keeps the cache alive during async
+  // callbacks and ensures ScopedFetch remains copyable for lambda captures.
+  ScopedFetch(std::shared_ptr<BucketMetadataCache> cache,
+              std::string bucket_name)
+      : state_(std::make_shared<State>(std::move(cache),
+                                       std::move(bucket_name))) {}
+
+ private:
+  struct State {
+    State(std::shared_ptr<BucketMetadataCache> c, std::string b)
+        : cache(std::move(c)), bucket_name(std::move(b)) {}
+    ~State() {
+      if (cache) cache->EndFetch(bucket_name);
+    }
+    std::shared_ptr<BucketMetadataCache> cache;
+    std::string bucket_name;
+  };
+  std::shared_ptr<State> state_;
+};
+
+GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_END
+}  // namespace storage_internal
+}  // namespace cloud
+}  // namespace google
+
+#endif  // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_STORAGE_INTERNAL_BUCKET_METADATA_CACHE_H