* MethodBuilder is a collection of APIs for client configuration at
a higher level than the Finagle 6 APIs while improving upon the deprecated
ClientBuilder.
* MethodBuilder is a collection of APIs for client configuration at
a higher level than the Finagle 6 APIs while improving upon the deprecated
ClientBuilder. MethodBuilder provides:
Logical success rate metrics.
Retries based on application-level requests and responses (e.g. a code in
the Thrift response).
Configuration of per-attempt and total timeouts.
All of these can be customized per method (or endpoint) while sharing a single
underlying Finagle client. Concretely, a single service might offer both
getOneTweet as well as deleteTweets, whilst each having
wildly different characteristics. The get is idempotent and has a tight latency
distribution while the delete is not idempotent and has a wide latency
distribution. If users want different configurations, without MethodBuilder
they must create separate Finagle clients for each grouping. While long-lived
clients in Finagle are not expensive, they are not free. They create
duplicate metrics and waste heap, file descriptors, and CPU.
Retries are intended to help clients improve success rate by trying
failed requests additional times. Care must be taken by developers
to only retry when it is known to be safe to issue the request multiple
times. This is because the client cannot always be sure what the
backend service has done. An example of a request that is safe to
retry would be a read-only request.
Defaults to using the client's ResponseClassifier to retry failures
marked as retryable.
See withRetryForClassifier for details.
A com.twitter.finagle.service.RetryBudget is used to prevent retries from overwhelming
the backend service. The budget is shared across clients created from
an initial MethodBuilder. As such, even if the retry rules
deem the request retryable, it may not be retried if there is insufficient
budget.
Additional information regarding retries can be found in the
user guide.
The classifier is also used to determine the logical success metrics of
the client. Logical here means after any retries are run. For example
should a request result in retryable failure on the first attempt, but
succeed upon retry, this is exposed through metrics as a success.
Logical success rate metrics are scoped to
"clnt/your_client_label/method_name/logical" and get "success" and
"requests" counters along with a "request_latency_ms" stat.
*
MethodBuilder
is a collection of APIs for client configuration at a higher level than the Finagle 6 APIs while improving upon the deprecated ClientBuilder.MethodBuilder
provides:All of these can be customized per method (or endpoint) while sharing a single underlying Finagle client. Concretely, a single service might offer both
getOneTweet
as well asdeleteTweets
, whilst each having wildly different characteristics. The get is idempotent and has a tight latency distribution while the delete is not idempotent and has a wide latency distribution. If users want different configurations, withoutMethodBuilder
they must create separate Finagle clients for each grouping. While long-lived clients in Finagle are not expensive, they are not free. They create duplicate metrics and waste heap, file descriptors, and CPU.Example
Given an example IDL:
This gives you a
Service
that has timeouts and retries onAnException
when theerrorCode
is0
:Timeouts
Defaults to using the StackClient's configuration.
An example of setting a per-request timeout of 50 milliseconds and a total timeout of 100 milliseconds:
Retries
Retries are intended to help clients improve success rate by trying failed requests additional times. Care must be taken by developers to only retry when it is known to be safe to issue the request multiple times. This is because the client cannot always be sure what the backend service has done. An example of a request that is safe to retry would be a read-only request.
Defaults to using the client's ResponseClassifier to retry failures marked as retryable. See withRetryForClassifier for details.
A com.twitter.finagle.service.RetryBudget is used to prevent retries from overwhelming the backend service. The budget is shared across clients created from an initial
MethodBuilder
. As such, even if the retry rules deem the request retryable, it may not be retried if there is insufficient budget.Finagle will automatically retry failures that are known to be safe to retry via com.twitter.finagle.service.RequeueFilter. This includes WriteExceptions and retryable nacks. As these should have already been retried, we avoid retrying them again by ignoring them at this layer.
Additional information regarding retries can be found in the user guide.
The classifier is also used to determine the logical success metrics of the client. Logical here means after any retries are run. For example should a request result in retryable failure on the first attempt, but succeed upon retry, this is exposed through metrics as a success. Logical success rate metrics are scoped to "clnt/your_client_label/method_name/logical" and get "success" and "requests" counters along with a "request_latency_ms" stat.
The user guide.
com.twitter.finagle.ThriftMux.Client.methodBuilder to construct instances.