docs: warnings about with_tracing()

src/gax/src/client_builder.rs

@@ -199,12 +199,12 @@ impl<F, Cr> ClientBuilder<F, Cr> {
         self
     }
 
-    /// Enables tracing.
-    ///
-    /// The client libraries can be dynamically instrumented with the Tokio
-    /// [tracing] framework. Setting this flag enables this instrumentation.
+    /// Enables observability signals for the client.
     ///
+    /// # Example
     /// ```
+    /// // In your `main` function enable a tracing subscriber, for example:
+    /// // tracing_subscriber::fmt::init();
     /// # use google_cloud_gax::client_builder::examples;
     /// # use google_cloud_gax::client_builder::Result;
     /// # async fn sample() -> anyhow::Result<()> {
@@ -215,7 +215,46 @@ impl<F, Cr> ClientBuilder<F, Cr> {
     /// # Ok(()) }
     /// ```
     ///
+    /// <div class="warning">
+    ///
+    /// Observability signals at any level may contain sensitive data such as resource names, full
+    /// URLs, and error messages.
+    ///
+    /// Review the contents of the spans and consult the [tracing] framework documentation to set up
+    /// filters and formatters to prevent leaking sensitive information, depending on your intended
+    /// use case.
+    ///
+    /// [OpenTelemetry Semantic Conventions]: https://opentelemetry.io/docs/concepts/semantic-conventions/
     /// [tracing]: https://docs.rs/tracing/latest/tracing/
+    ///
+    /// </div>
+    ///
+    /// The libraries are instrumented to generate the following signals:
+    ///
+    /// 1. `INFO` spans for each logical client request. Typically a single method call in the client
+    ///    struct gets such a span.
+    /// 1. A histogram metric measuring the elapsed time for each logical client request.
+    /// 1. `WARN` logs for each logical client requests that fail.
+    /// 1. `INFO` spans for each low-level attempt RPC attempt. Typically a single method in the client
+    ///    struct gets one such span, but there may be more if the library had to retry the RPC.
+    /// 1. `DEBUG` logs for each low-level attempt that fails.
+    ///
+    /// These spans and logs follow [OpenTelemetry Semantic Conventions] with additional Google
+    /// Cloud attributes. Both the spans and logs and are should be suitable for production
+    /// monitoring.
+    ///
+    /// The libraries also have `DEBUG` spans for each request, these include the full request body,
+    /// and the full response body for successful requests, and the full error message, with
+    /// details, for failed requests. Consider the contents of these requests and responses before
+    /// enabling them in production environments, as the request or responses may include sensitive
+    /// data.
+    ///
+    /// # More information
+    ///
+    /// The [Enable logging] guide shows you how to initialize a subscriber to
+    /// log events to the console.
+    ///
+    /// [Enable logging]: https://docs.cloud.google.com/rust/enable-logging
     pub fn with_tracing(mut self) -> Self {
         self.config.tracing = true;
         self

src/storage/src/storage/client.rs

@@ -632,24 +632,7 @@ impl ClientBuilder {
         self
     }
 
-    /// Enable debug logs and traces using the [tracing] framework.
-    ///
-    /// <div class="warning">
-    ///
-    /// Traces at any level may contain sensitive data like bucket names, object
-    /// names, full URLs and error messages. Traces at the `INFO` level follow
-    /// [OpenTelemetry Semantic Conventions] with additional Storage attributes,
-    /// and are intended to be suitable for production monitoring. Traces at
-    /// the `DEBUG` level or lower are meant for detailed debugging and include
-    /// the full content of requests, responses, and the debug information for
-    /// the client.
-    ///
-    /// Review the contents of the traces and consult the [tracing]
-    /// framework documentation to set up filters and formatters to prevent
-    /// leaking sensitive information, depending on your intended use case.
-    ///
-    /// [OpenTelemetry Semantic Conventions]: https://opentelemetry.io/docs/concepts/semantic-conventions/
-    /// </div>
+    /// Enables observability signals for the client.
     ///
     /// # Example
     /// ```
@@ -664,6 +647,40 @@ impl ClientBuilder {
     /// # Ok(()) }
     /// ```
     ///
+    /// <div class="warning">
+    ///
+    /// Observability signals at any level may contain sensitive data such as resource names (bucket
+    /// and object names), full URLs, and error messages.
+    ///
+    /// Review the contents of the spans and consult the [tracing] framework documentation to set up
+    /// filters and formatters to prevent leaking sensitive information, depending on your intended
+    /// use case.
+    ///
+    /// [OpenTelemetry Semantic Conventions]: https://opentelemetry.io/docs/concepts/semantic-conventions/
+    /// [tracing]: https://docs.rs/tracing/latest/tracing/
+    ///
+    /// </div>
+    ///
+    /// The libraries are instrumented to generate the following signals:
+    ///
+    /// 1. `INFO` spans for each logical client request. Typically a single method call in the client
+    ///    struct gets such a span.
+    /// 1. A histogram metric measuring the elapsed time for each logical client request.
+    /// 1. `WARN` logs for each logical client requests that fail.
+    /// 1. `INFO` spans for each low-level attempt RPC attempt. Typically a single method in the client
+    ///    struct gets one such span, but there may be more if the library had to retry the RPC.
+    /// 1. `DEBUG` logs for each low-level attempt that fails.
+    ///
+    /// These spans and logs follow [OpenTelemetry Semantic Conventions] with additional Google
+    /// Cloud attributes. Both the spans and logs and are should be suitable for production
+    /// monitoring.
+    ///
+    /// The libraries also have `DEBUG` spans for each request, these include the full request body,
+    /// and the full response body for successful requests, and the full error message, with
+    /// details, for failed requests. Consider the contents of these requests and responses before
+    /// enabling them in production environments, as the request or responses may include sensitive
+    /// data.
+    ///
     /// # More information
     ///
     /// The [Enable logging] guide shows you how to initialize a subscriber to