Struct ClientBuilder

Source

pub struct ClientBuilder<F, Cr> { /* private fields */ }

Expand description

A generic builder for clients.

In the Google Cloud client libraries for Rust a “client” represents a connection to a specific service. Each client library defines one or more client types. All the clients are initialized using a ClientBuilder.

Applications obtain a builder with the correct generic types using the builder() method on each client:

use examples::Client; // Placeholder for examples
let builder = Client::builder();

To create a client with the default configuration just invoke the .build() method:

use examples::Client; // Placeholder for examples
let client = Client::builder().build().await?;

As usual, the builder offers several method to configure the client, and a .build() method to construct the client:

use examples::Client; // Placeholder for examples
let client = Client::builder()
    .with_endpoint("http://private.googleapis.com")
    .build().await?;

Implementations§

Source §

impl<F, Cr> ClientBuilder<F, Cr>

Source

pub async fn build<C>(self) -> Result<C>
where F: ClientFactory<Client = C, Credentials = Cr>,

Creates a new client.

use examples::Client; // Placeholder for examples
let client = Client::builder()
    .build().await?;

Source

pub fn with_endpoint<V: Into<String>>(self, v: V) -> Self

Sets the endpoint.

use examples::Client; // Placeholder for examples
let client = Client::builder()
    .with_endpoint("http://private.googleapis.com")
    .build().await?;

Source

pub fn with_tracing(self) -> Self

Enables observability signals for the client.

§Example

use examples::Client; // Placeholder for examples
let client = Client::builder()
    .with_tracing()
    .build().await?;
// For observing traces and logs, you must also enable a tracing subscriber in your `main` function,
// for example:
//     tracing_subscriber::fmt::init();
// For observing metrics, you must also install an OpenTelemetry meter provider in your `main` function,
// for example:
//     opentelemetry::global::set_meter_provider(provider.clone());

Observability signals at any level may contain sensitive data such as resource names, full URLs, and error messages.

Before configuring subscribers or exporters for traces and logs, 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.

The libraries are instrumented to generate the following signals:

INFO spans for each logical client request. Typically a single method call in the client struct gets such a span.
A histogram metric measuring the elapsed time for each logical client request.
WARN logs for each logical client requests that fail.
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.
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. These DEBUG spans use the client library crate followed by ::tracing as their target and the method name as the span name. You can use the name and/or target to set up your filters.

§More information

The Enable logging guide shows you how to initialize a subscriber to log events to the console.

Source

pub fn with_credentials<T: Into<Cr>>(self, v: T) -> Self

Configure the authentication credentials.

Most Google Cloud services require authentication, though some services allow for anonymous access, and some services provide emulators where no authentication is required. More information about valid credentials types can be found in the google-cloud-auth crate documentation.

use examples::Client; // Placeholder for examples
// Placeholder, normally use google_cloud_auth::credentials
use examples::credentials;
let client = Client::builder()
    .with_credentials(
        credentials::mds::Builder::new()
            .scopes(["https://www.googleapis.com/auth/cloud-platform.read-only"])
            .build())
    .build().await?;

Source

pub fn with_retry_policy<V: Into<RetryPolicyArg>>(self, v: V) -> Self

Configure the retry policy.

The client libraries can automatically retry operations that fail. The retry policy controls what errors are considered retryable, sets limits on the number of attempts or the time trying to make attempts.

use examples::Client; // Placeholder for examples
use gax::retry_policy::{AlwaysRetry, RetryPolicyExt};
let client = Client::builder()
    .with_retry_policy(AlwaysRetry.with_attempt_limit(3))
    .build().await?;

Source

pub fn with_backoff_policy<V: Into<BackoffPolicyArg>>(self, v: V) -> Self

Configure the retry backoff policy.

The client libraries can automatically retry operations that fail. The backoff policy controls how long to wait in between retry attempts.

use examples::Client; // Placeholder for examples
use gax::exponential_backoff::ExponentialBackoff;
use std::time::Duration;
let policy = ExponentialBackoff::default();
let client = Client::builder()
    .with_backoff_policy(policy)
    .build().await?;

Source

pub fn with_retry_throttler<V: Into<RetryThrottlerArg>>(self, v: V) -> Self

Configure the retry throttler.

Advanced applications may want to configure a retry throttler to Address Cascading Failures and when Handling Overload conditions. The client libraries throttle their retry loop, using a policy to control the throttling algorithm. Use this method to fine tune or customize the default retry throtler.

use examples::Client; // Placeholder for examples
use gax::retry_throttler::AdaptiveThrottler;
let client = Client::builder()
    .with_retry_throttler(AdaptiveThrottler::default())
    .build().await?;

Source

pub fn with_polling_error_policy<V: Into<PollingErrorPolicyArg>>( self, v: V, ) -> Self

Configure the polling error policy.

Some clients support long-running operations, the client libraries can automatically poll these operations until they complete. Polling may fail due to transient errors and applications may want to continue the polling loop despite such errors. The polling error policy controls which errors are treated as recoverable, and may limit the number of attempts and/or the total time polling the operation.

use examples::Client; // Placeholder for examples
use gax::polling_error_policy::Aip194Strict;
use gax::polling_error_policy::PollingErrorPolicyExt;
use std::time::Duration;
let client = Client::builder()
    .with_polling_error_policy(Aip194Strict
        .with_time_limit(Duration::from_secs(15 * 60))
        .with_attempt_limit(50))
    .build().await?;

Source

pub fn with_polling_backoff_policy<V: Into<PollingBackoffPolicyArg>>( self, v: V, ) -> Self

Configure the polling backoff policy.

Some clients support long-running operations, the client libraries can automatically poll these operations until they complete. The polling backoff policy controls how long the client waits between polling attempts.

use examples::Client; // Placeholder for examples
use gax::exponential_backoff::ExponentialBackoff;
use std::time::Duration;
let policy = ExponentialBackoff::default();
let client = Client::builder()
    .with_polling_backoff_policy(policy)
    .build().await?;