tenacity - GitLite

KO | EN

gitlite — search

#javascript #hacktoberfest #react #ai #go #golang #machine-learning #deep-learning #linux #nodejs #awesome-list #security #ios #mcp

tenacity

(★ 204)

Dropwizard + Hystrix Module.

File Explorer

Download Latest Version (.zip)

- pom.xml
- pom.xml
- pom.xml
- pom.xml
- pom.xml
.gitignore
.travis.yml
CHANGES.md
findbugs-exclude.xml
LICENSE
maven_deploy_settings.xml
pom.xml
README.md
TODO.md

# Installation Guide

1. Get the code

git clone https://github.com/yammer/tenacity

Downloads the entire project code from GitHub to your computer.

cd tenacity

Moves into the project folder you just downloaded.

2. Maven (Java)

Medium Recommended

Prerequisites

Git Needed to download the project code from GitHub.
JDK (Java) Required to build and run Java projects.
Maven The build tool used for the mvn command.

mvn clean install

Installs dependencies and builds the project using Maven.

✅ A BUILD SUCCESS message means it worked. The output is created under target/.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

Tenacity [![Build Status](https://travis-ci.org/yammer/tenacity.svg?style=flat-square)](https://travis-ci.org/yammer/tenacity) [![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.yammer.tenacity/tenacity-core/badge.svg?style=flat-square)](https://maven-badges.herokuapp.com/maven-central/com.yammer.tenacity/tenacity-core)
========

Tenacity is [Dropwizard](http://www.dropwizard.io)+[Hystrix](https://github.com/Netflix/Hystrix).

[Dropwizard](http://www.dropwizard.io) is a framework for building REST services. [Hystrix](https://github.com/Netflix/Hystrix) is a resiliency library from [Netflix](https://github.com/Netflix) and [Ben Christensen](https://github.com/benjchristensen).

[Hystrix's](https://github.com/Netflix/Hystrix) goals are to:

1. Stop cascading failures.
2. Fail-fast and rapidly recover.
3. Reduce mean-time-to-discovery (with dashboards)
4. Reduce mean-time-to-recovery (with dynamic configuration)

Tenacity makes [Hystrix](https://github.com/Netflix/Hystrix) dropwizard-friendly and for dropwizard-developers to quickly leverage the benefits of Hystrix.

1. Uses dropwizard-bundles for bootstrapping: property strategies, metrics, dynamic configuration, and some resource endpoints (e.g. for dashboards).
2. Dropwizard-configuration style (YAML) for dependencies.
3. Abstractions to clearly configure a dependency operation (`TenacityCommand<ReturnType>`).
4. Ability to unit-test Hystrix: Resets static state held by Hystrix (metrics, counters, etc.). Increases rate at which a concurrent thread updates metrics.
5. Publishes measurements via [Metrics](https://github.com/dropwizard/metrics).

*Tenacity is meant to be used with [Breakerbox](https://github.com/yammer/breakerbox) which adds real-time visualization of metrics and dynamic configuration.*

Modules
-------

-   `tenacity-core`:            The building blocks to quickly use Hystrix within the context of Dropwizard.
-   `tenacity-client`:          Client for consuming the resources that `tenacity-core` adds.
-   `tenacity-testing`:         `TenacityTestRule` allows for easier unit testing. Resets internal state of Hystrix.
-   `tenacity-jdbi`:            Pulls in dropwizard-jdbi and provides a DBIExceptionLogger and SQLExceptionLogger to be used with the ExceptionLoggingCommandHook.

How To Use
==========

Here is a sample `TenacityCommand` that always succeeds:

```java
public class AlwaysSucceed extends TenacityCommand<String> {
    public AlwaysSucceed() {
        super(DependencyKey.ALWAYS_SUCCEED);
    }

@Override
    protected String run() throws Exception {
        return "value";
    }
}
```

A quick primer on the way to use a `TenacityCommand` if you are not familiar with [Hystrix's execution model](https://github.com/Netflix/Hystrix/wiki/How-To-Use#wiki-Synchronous-Execution):

Synchronous Execution
---------------------
```java
AlwaysSucceed command = new AlwaysSucceed();
String result = command.execute();
```

This executes the command synchronously but through the protection of a `Future.get(configurableTimeout)`.

Asynchronous Execution
----------------------

```java
Future<String> futureResult = command.queue();
```

Reactive Execution
------------------------------

```java
Observable<String> observable = new AlwaysSucceed().observe();
```

Fallbacks
---------

When execution fails, it is possible to gracefully degrade with the use of [fallbacks](https://github.com/Netflix/Hystrix/wiki/How-To-Use#wiki-Fallback).

Execution Flow
--------------

![Alt text](https://raw.githubusercontent.com/wiki/Netflix/Hystrix/images/hystrix-command-flow-chart.png)

TenacityCommand Constructor Arguments
-------------------------------------

Earlier we saw:

```java
public class AlwaysSucceed extends TenacityCommand<String> {
    public AlwaysSucceed() {
        super(DependencyKey.ALWAYS_SUCCEED);
    }
    ...
}
```

The arguments are:

1. `commandKey`: This creates a circuit-breaker, threadpool, and also the identifier that will be used in dashboards.
This should be your implementation of the `TenacityPropertyKey` interface.

*It is possible to create multiple circuit-breakers that leverage a single threadpool, but for simplicity we are not allowing that type of configuration.*

How to add Tenacity to your Dropwizard Service
----------

1. To leverage within dropwizard first add the following to your `pom.xml`:

```xml
    <dependency>
        <groupId>com.yammer.tenacity</groupId>
        <artifactId>tenacity-core</artifactId>
        <version>1.1.2</version>
    </dependency>
    ```
    
    Or you can leverage the tenacity-bom:
    
    ```xml
    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>com.yammer.tenacity</groupId>
                <artifactId>tenacity-bom</artifactId>
                <version>1.1.2</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>
    
    <dependency>
        <groupId>com.yammer.tenacity</groupId>
        <artifactId>tenacity-core</artifactId>
    </dependency>
    ```

2. Enumerate your dependencies. These will eventually be used as global identifiers in dashboards. We have found that it works best for us when you include the service and the external dependency at a minimum. Here is an example of `completie`'s dependencies. Note we also shave down some characters to save on space, again for UI purposes. In addition, you'll need to have an implementation of a `TenacityPropertyKeyFactory` which you can see an example of below.

```java
    public enum CompletieDependencyKeys implements TenacityPropertyKey {
        CMPLT_PRNK_USER, CMPLT_PRNK_GROUP, CMPLT_PRNK_SCND_ORDER, CMPLT_PRNK_NETWORK,
        CMPLT_TOKIE_AUTH,
        CMPLT_TYRANT_AUTH,
        CMPLT_WHVLL_PRESENCE
    }
    ```
    ```java
    public class CompletieDependencyKeyFactory implements TenacityPropertyKeyFactory {
        @Override
        public TenacityPropertyKey from(String value) {
            return CompletieDependencyKeys.valueOf(value.toUpperCase());
        }
    }
    ```
    
3. Create a `TenacityBundleConfigurationFactory` implementation - you can use the `BaseTenacityBundleConfigurationFactory` as your starting point. This will be used to register your custom tenacity dependencies and custom configurations.

```java
    public class CompletieTenacityBundleConfigurationFactory extends BaseTenacityBundleConfigurationFactory<CompletieConfiguration> {
    
      @Override
      public Map<TenacityPropertyKey, TenacityConfiguration> getTenacityConfigurations(CompletieConfiguration configuration) {
            final ImmutableMap.Builder<TenacityPropertyKey, TenacityConfiguration> builder = ImmutableMap.builder();
    
            builder.put(CompletieDependencyKeys.CMPLT_PRNK_USER, configuration.getRanking().getHystrixUserConfig());
            builder.put(CompletieDependencyKeys.CMPLT_PRNK_GROUP, configuration.getRanking().getHystrixGroupConfig());
            builder.put(CompletieDependencyKeys.CMPLT_PRNK_SCND_ORDER, configuration.getRanking().getHystrixSecondOrderConfig());
            builder.put(CompletieDependencyKeys.CMPLT_PRNK_NETWORK, configuration.getRanking().getHystrixNetworkConfig());
            builder.put(CompletieDependencyKeys.CMPLT_TOKIE_AUTH, configuration.getAuthentication().getHystrixConfig());
            builder.put(CompletieDependencyKeys.CMPLT_WHVLL_PRESENCE, configuration.getPresence().getHystrixConfig())
    
            return builder.build();
      }
    }
    ```
    
4. Then make sure you add the bundle in your `Application`.

`Map<TenacityPropertyKey, TenacityConfiguration>` type.

```java
    @Override
    public void initialize(Bootstrap<MyConfiguration> bootstrap) {
        ...
        bootstrap.addBundle(TenacityBundleBuilder
                                            .<MyConfiguration> newBuilder()
                                            .configurationFactory(new CompletieTenacityBundleConfigurationFactory())
                                            .build());
        ...
    }
    ```

5. Use `TenacityCommand` to select which custom tenacity configuration you want to use.

```java
    public class CompletieDependencyOnTokie extends TenacityCommand<String> {
        public CompletieDependencyOnTokie() {
            super(CompletieDependencyKeys.CMPLT_TOKIE_AUTH);
        }
        ...
    }
    ```
    
6. When testing use the `tenacity-testing` module. This registers appropriate custom publishers/strategies, clears global `Archaius` configuration state (Hystrix uses internally to manage configuration), and tweaks threads that calculate metrics which influence circuit breakers to update a more frequent interval. Simply use the `TenacityTestRule`.

```java
    @Rule
    public final TenacityTestRule tenacityTestRule = new TenacityTestRule();
    ```
    ```xml
    <dependency>
        <groupId>com.yammer.tenacity</groupId>
        <artifactId>tenacity-testing</artifactId>
        <version>1.1.2</version>
        <scope>test</scope>
    </dependency>
    ```

7. Last is to actually configure your dependencies once they are wrapped with `TenacityCommand`.

Configuration
=============

Once you have identified your dependencies you need to configure them appropriately. Here is the basic structure of a single
`TenacityConfiguration` that may be leverage multiple times through your service configuration:

Defaults
--------
```yaml
executionIsolationThreadTimeoutInMillis: 1000
executionIsolationStrategy: THREAD
threadpool:
    threadPoolCoreSize: 10
    keepAliveTimeMinutes: 1
    maxQueueSize: -1
    queueSizeRejectionThreshold: 5
    metricsRollingStatisticalWindowInMilliseconds: 10000
    metricsRollingStatisticalWindowBuckets: 10
circuitBreaker:
    requestVolumeThreshold: 20
    errorThresholdPercentage: 50
    sleepWindowInMillis: 5000
    metricsRollingStatisticalWindowInMilliseconds: 10000
    metricsRollingStatisticalWindowBuckets: 10
semaphore:
    maxConcurrentRequests: 10
    fallbackMaxConcurrentRequests: 10
```

The following two are the most important and you can probably get by just fine by defining just these two and leveraging the
defaults.

-   `executionIsolationStrategy`: Which to use THREAD or SEMAPHORE. Defaults to THREAD. [Execution Isolation Strategy](https://github.com/Netflix/Hystrix/wiki/Configuration#execution.isolation.strategy).
-   `executionIsolationThreadTimeoutInMillis`: How long the entire dependency command should take.
-   `threadPoolCoreSize`: Self explanatory.

Here are the rest of the descriptions:

-   `keepAliveTimeMinutes`: Thread keepAlive time in the thread pool.
-   `maxQueueSize`: -1 uses a `SynchronousQueue`. Anything >0 leverages a `BlockingQueue` and enables the `queueSizeRejectionThreshold` variable.
-   `queueSizeRejectionThreshold`: Disabled when using -1 for `maxQueueSize` otherwise self explanatory.
-   `requestVolumeThreshold`: The minimum number of requests that need to be received within the `metricsRollingStatisticalWindowInMilliseconds` in order to open a circuit breaker.
-   `errorThresholdPercentage`: The percentage of errors needed to trip a circuit breaker. In order for this to take effect the `requestVolumeThreshold` must first be satisfied.
-   `sleepWindowInMillis`: How long to keep the circuit breaker open, before trying again.

Here are the semaphore related items:

-   `maxConcurrentRequests`: The number of concurrent requests for a given key at any given time.
-   `fallbackMaxConcurrentRequests`: The number of concurrent requests for the fallback at any given time.

These are recommended to be left alone unless you know what you're doing:

-   `metricsRollingStatisticalWindowInMilliseconds`: How long to keep around metrics for calculating rates.
-   `metricsRollingStatisticalWindowBuckets`: How many different metric windows to keep in memory.

Once you are done configuring your Tenacity dependencies. Don't forget to tweak the necessary connect/read timeouts on HTTP clients.
We have some suggestions for how you go about this in the Equations section.

Breakerbox
----------
One of the great things about Tenacity is the ability to aid in the reduction of mean-time-to-discovery and mean-time-to-recovery for issues. This is available through a separate service [Breakerbox](https://github.com/yammer/breakerbox).

[Breakerbox](https://github.com/yammer/breakerbox) is a central dashboard and an on-the-fly configuration tool for Tenacity. In addition to the per-tenacity-command configurations shown above this configuration piece let's you define where and how often
to check for newer configurations.

```yaml
breakerbox:
  urls: http://breakerbox.yourcompany.com:8080/archaius/{service}
  initialDelay: 0s
  delay: 60s
  waitForInitialLoad: 0s
```

-   `urls` is a list of comma-deliminated list of urls for where to pull tenacity configurations. This will pull override configurations for all dependency keys for requested service.
-   `initialDelay` how long before the first poll for newer configuration executes.
-   `delay` the ongoing schedule to poll for newer configurations.
-   `waitForInitialLoad` is the amount of time to block Dropwizard from starting while waiting for `Breakerbox` configurations.

![Breakerbox Dashboard](http://yammer.github.io/tenacity/breakerbox_latest.png)
![Breakerbox Configure](http://yammer.github.io/tenacity/breakerbox_configure.png)

In order to add integration with Breakerbox you need to implement the following method in your `TenacityBundleConfigurationFactory` implementation:

```
@Override
public BreakerboxConfiguration getBreakerboxConfiguration(CompletieConfiguration configuration) {
   return configuration.getBreakerbox();
}
```

Configuration Hierarchy Order
-----------------------------

Configurations can happen in a lot of different spots so it's good to just spell it out clearly. The order in this list matters, the earlier items override those that come later.

1. [Breakerbox](https://github.com/yammer/breakerbox)
2. Local service configuration YAML
3. [Defaults](https://github.com/yammer/tenacity#defaults)

Configuration Equations
---------

How to configure your dependent services can be confusing. A good place to start if don't have a predefined SLA is to just look
at actual measurements. At Yammer, we set our max operational time for our actions somewhere between p99 and p999 for response times. We
do this because we have found it to actually be faster to fail those requests, retry, and optimistically get a p50 response time.

1. Tenacity
  -   executionIsolationThreadTimeoutInMillis = `p99 + median + extra`
  -   p99 < executionIsolationThreadTimeoutInMillis < p999
  -   threadpool
      *   size = `(p99 in seconds) * (m1 rate req/sec) + extra`
      *   10 is usually fine for most operations. Anything with a large pool should be understood why that is necessary (e.g. long response times)
      *   Extra: this number only meets the current traffic needs. Make sure to add some extra for bursts as well as growth.

2. HTTP client
  -   connectTimeout = `33% of executionIsolationThreadTimeoutInMillis`
  -   timeout (readTimeout) = `110% of executionIsolationThreadTimeoutInMillis`
      *   We put this timeout higher so that it doesn't raise a TimeoutException from the HTTP client, but instead from Hystrix.

*Note: These are just suggestions, feel free to look at Hystrix's configuration [documentation](https://github.com/Netflix/Hystrix/wiki/Configuration), or implement your own.*

Resources
=========

Tenacity adds resources under `/tenacity`:

1. `GET /tenacity/propertykeys`:  List of strings which are all the registered propertykeys with Tenacity.
2. `GET /tenacity/configuration/{key}`:         JSON representation of a `TenacityConfiguration` for the supplied {key}.
3. `GET /tenacity/circuitbreakers`:             Simple JSON representation of all circuitbreakers and their circuitbreaker status.
   `GET /tenacity/circuitbreakers/{key}`:       Single circuitbreaker status
   `PUT /tenacity/circuitbreakers/{key}`:       Expected "FORCED_CLOSED, FORCED_OPEN, or FORCED_RESET" as the body.
4. `GET /tenacity/metrics.stream`:              text/event-stream of Hystrix metrics.

By default these are put onto the main application port. If you want to place these instead on the admin port, 
you can configure this when building the `Tenacity` bundle.

```java
TenacityBundleBuilder
                .<MyConfiguration> newBuilder()
                ...
                .usingAdminPort()
                .build();
```

TenacityExceptionMapper
=======================

An exception mapper exists to serve as an aid for unhandled `HystrixRuntimeException`s. It is used to convert all the types of unhandled exceptions to be converted to a simple
HTTP status code. A common pattern here is to convert the unhandled `HystrixRuntimeException`s to [429 Too Many Requests](http://tools.ietf.org/html/rfc6585#section-4):

```java
TenacityBundleBuilder
                .<MyConfiguration> newBuilder()
                .configurationFactory(configurationFactory)
                .mapAllHystrixRuntimeExceptionsTo(429)
                .build();
```

ExceptionLoggingCommandHook
===========================

If you don't handle logging exceptions explicitly within each `TenacityCommand`, you can easily miss problems or at-least find them very hard to debug.
Instead you can add the `ExceptionLoggingCommandHook` to the `TenacityBundle` and register `ExceptionLogger`s to handle the logging of different kinds of Exceptions.
The `ExecutionLoggingCommandHook` acts as a `HystrixCommandExecutionHook` and intercepts all Exceptions that occur during the `run()` method of your `TenacityCommand`s.
By sequencing `ExceptionLogger`s from most specific to most general, the `ExceptionLoggingCommandHook` will be able to find the best `ExceptionLogger` for the type of Exception.

```java
TenacityBundleBuilder
                .<MyConfiguration> newBuilder()
                .configurationFactory(configurationFactory)
                .mapAllHystrixRuntimeExceptionsTo(429)
                .commandExecutionHook(new ExceptionLoggingCommandHook(
                    new DBIExceptionLogger(registry),
                    new SQLExceptionLogger(registry),
                    new DefaultExceptionLogger()
                ))
                .build();
```

TenacityJerseyClientBuilder
===========================
`TenacityJerseyClient` and `TenacityJerseyClientBuilder` to reduce configuration complexity when using Tenacity
and `JerseyClient`. At the moment these two have competing timeout configurations that can end up looking like application exceptions
when they are simply `TimeoutException`s being thrown by JerseyClient. `TenacityJerseyClient` aims to fix this by adjusting the socket read timeout
on a per-request basis on the currently set execution timeout value for resources built from `TenacityJerseyClient` and its associated
`TenacityPropertyKey`. Note: Metrics associated with the `TenacityPropertyKey` are *NOT* updated whenever the underlying `Client` is used. The `TenacityPropertyKey` metrics are only
ever updated when using `TenacityCommand` or `TenacityObservableCommand` at the moment.

```java
Client client = new JerseyClientBuilder(environment).build("some-external-dependency");
Client tenacityClient = TenacityJerseyClientBuilder
    .builder(YOUR_TENACITY_PROPERTY_KEY)
    .usingTimeoutPadding(Duration.milliseconds(50))
        //Padding to add in addition to the Tenacity set time. Default is 50ms.
        //Result: TenacityTimeout + TimeoutPadding = SocketReadTimeout
    .build(client);

//Then use tenacityClient the same way as you'd use client. TenacityClient overrides resource/asyncResource and those in turn are Tenacity*Resources.
//They adjust timeouts on every use or on a per-request basis.
```

TenacityCircuitBreakerHealthCheck
=================================
There is now the ability to add a `HealthCheck` which returns `unhealthy` when any circuit is open. This could be because a circuit is
forced open or because of environment circumstances. The default is for this not to be turned on. You can enable this `HealthCheck`
by configuring it on the bundle that is added to your application.

```java
TenacityBundleBuilder
                .newBuilder()
                ...
                .withCircuitBreakerHealthCheck()
                .build();
```

TenacityCommand.Builder
=======================
Java8 brings functional interfaces and `TenacityCommand`/`TenacityObservableCommand` offers support.

```java
TenacityCommand
      .builder(DependencyKey.GENERAL)
      .run(() -> 1)
      .fallback(() -> 2)
      .execute()
```
```java
TenacityObservableCommand
      .builder(DependencyKey.GENERAL)
      .run(() -> Observable.just(1))
      .fallback(() -> Observable.just(2))
      .observe()
```