diff --git a/google/cloud/storage/doc/storage-grpc.dox b/google/cloud/storage/doc/storage-grpc.dox deleted file mode 100644 index 62ea64a03f470..0000000000000 --- a/google/cloud/storage/doc/storage-grpc.dox +++ /dev/null @@ -1,120 +0,0 @@ -/*! - -@page storage-grpc Using the GCS+gRPC Plugin - -The GCS C++ client library includes an optional plugin to access GCS via gRPC. -When using GCS from Google Compute Engine (GCE) this plugin can enable higher -total throughput across large workloads that run on hundreds or thousands of -VMs. - -## Release Notes - -There are some features that the gRPC plugin does not implement or implements -differently from the REST-based implementation. - -1. For best performance consider using Protobuf >= 23.2 and gRPC >= 1.55.0. - Older versions of Protobuf requires enabling [ctype=CORD workarounds] at - compile-time. -1. To override the default endpoint you should use - [`EndpointOption`](@ref google::cloud::EndpointOption) instead of - [`RestEndpointOption`](@ref google::cloud::storage::RestEndpointOption). -1. The cloud path endpoint (`storage.googleapis.com`) works from any hosting - environment (on-prem, GKE, GCE, other cloud providers, etc.). For best - performance on GCE or GKE we default to the direct connectivity endpoint - `google-c2p:///storage.googleapis.com`. -1. The [`Fields`](@ref google::cloud::storage::Fields) request parameter is - passed verbatim to the backend. Some fields have different names in gRPC, and - the backend does not translate them. This is a rarely used feature, and we do - not anticipate the behavior change is likely to cause problems. If it does - cause any issues please [file a bug]. -1. All the `storage::Client::*AccessControl()` functions are emulated. For - functions that change state, the emulation uses an [OCC loop]. While this - preserves the semantics of a single RPC (e.g. no other concurrent changes - are lost), it requires making at least two RPCs. This may increase the cost - of calling these functions. Our telemetry shows these functions are not used - via the C++ client library, but you should keep this in mind before deciding - to use these functions in new code. -1. The functions to create, list, query, and delete HMAC keys and notifications - are unavailable in gRPC. Our telemetry indicates that these functions are - never used in C++, and therefore we do not anticipate this can cause - problems. - -[OCC loop]: https://en.wikipedia.org/wiki/Optimistic_concurrency_control -[file a bug]: https://github.com/googleapis/google-cloud-cpp/issues/new/choose -[ctype=CORD workarounds]: https://github.com/googleapis/google-cloud-cpp/blob/main/doc/ctype-cord-workarounds.md - -## Required code changes - -To use GCS+gRPC plugin you need to make some changes to how your application -initializes the GCS C++ client library. First, an additional header provides -the initialization functions: - -@snippet storage_grpc_samples.cc grpc-includes - -Then you initialize a `google::cloud::storage::Client` using a new function: - -@snippet storage_grpc_samples.cc grpc-default-client - -The `google::cloud::storage::Client` object returned by this function can be -used as before: - -@snippet storage_grpc_samples.cc grpc-read-write - -## Changing your build scripts - -If you are using CMake to compile your application, then you need to change the -`target_link_libraries()` command to use -`google-cloud-cpp::%storage_grpc` instead -of `google-cloud-cpp::%storage`. For example, our quickstart program for gRPC -uses: - -```{.cmake} -add_executable(quickstart_grpc quickstart_grpc.cc) -target_link_libraries(quickstart_grpc google-cloud-cpp::storage_grpc) -``` - -If you are using Bazel to compile your application, then you need to change -the dependencies from `@google_cloud_cpp//:storage` -to `@google_cloud_cpp//:storage_grpc`. -For example, our `grpc/quickstart uses: - -```{.py} -cc_binary( - name = "quickstart_grpc", - srcs = [ - "quickstart_grpc.cc", - ], - deps = [ - "@google_cloud_cpp//:storage_grpc", - ], -) -``` - -## gRPC+OpenTelemetry - -The gRPC client will default to enabling OpenTelemetry metrics. This means that -the library must be built with support for OpenTelemetry and support for the gRPC -OpenTelemetry plugin. Please note metrics require using a version of gRPC > 1.64. - -If you are using CMake to compile your application: - -1. Build and install OpenTelemetry with the following options: -```{.bash} --DWITH_ABSEIL=ON -``` - -1. Build and install gRPC with the OpenTelemetry plugin enabled: - -Build and and install gRPC with the following option: -```{.bash} --DgRPC_BUILD_GRPCPP_OTEL_PLUGIN=ON -``` - -If you are using Bazel and wish to disable gRPC metrics please -build with the following option: - -```{.bash} ---//google/cloud/storage:enable_grpc_metrics=false -``` - -*/ diff --git a/google/cloud/storage/doc/storage-main.dox b/google/cloud/storage/doc/storage-main.dox index 8b1b1669718c0..95619ea06a6b5 100644 --- a/google/cloud/storage/doc/storage-main.dox +++ b/google/cloud/storage/doc/storage-main.dox @@ -34,7 +34,6 @@ project. - @ref storage-auth-example - @ref storage-retry-examples - @ref storage-mocking shows how to write tests mocking the [Client] class - - The [Setting up your development environment] guide describes how to set up a C++ development environment in various platforms, including the Google Cloud C++ client libraries.