Netflix Hystrix

The hystrix-contrib module serves as a parent container for various Hystrix extension submodules. These submodules provide alternative implementations of core Hystrix strategies or integrations with specific request lifecycles and monitoring tools.

Common types of contrib submodules include:

• Alternative implementations of HystrixMetricsPublisher.
• Alternative implementations of HystrixPropertiesStrategy.
• Request lifecycle implementations (e.g., hystrix-request-servlet).
• Implementations of HystrixEventNotifier.
• Dashboard and monitoring tools.

Note: Third-party libraries that wrap Hystrix are not part of this repository but are documented in the Hystrix Wiki [Libraries] page.

Javanica supports different weaving modes for applying aspects:

• Runtime Weaving (RTW): The standard approach. Use the regular hystrix-javanica-X.Y.Z artifact.
• Compile Time Weaving (CTW): Requires the specific hystrix-javanica-ctw-X.Y.Z artifact (assembled with the AJC compiler). You must start your application with the JVM property -DWeavingMode=compile.
• Load Time Weaving (LTW): Has not been explicitly tested but is supported.

Warning: Javanica depends on internal AspectJ features. If you update your AspectJ version (tested with 1.8.7), you may encounter issues.

The module emits metrics in a text/event-stream format. There are two primary types of data emitted:

HystrixCommand

Emits real-time statistics for individual Hystrix commands, including error percentages, circuit breaker status, and latency percentiles (0, 25, 50, 75, 90, 95, 99, 99.5, 100).

HystrixThreadPool

Emits statistics for Hystrix thread pools, including current pool size, active thread counts, and queue sizes.

// Example HystrixCommand data
data: {
  "type": "HystrixCommand",
  "name": "PlaylistGet",
  "group": "PlaylistGet",
  "isCircuitBreakerOpen": false,
  "errorPercentage": 0,
  "requestCount": 121,
  "latencyExecute": {
    "0": 3,
    "50": 8,
    "99": 75,
    "100": 252
  }
}

// Example HystrixThreadPool data
data:
{
  "type": "HystrixThreadPool",
  "name": "ABClient",
  "currentPoolSize": 30,
  "currentActiveCount": 0,
  "currentQueueSize": 0
}

To isolate code, wrap it inside the run() method of a class extending HystrixCommand. You must provide a HystrixCommandGroupKey in the constructor.

Once defined, you can execute the command synchronously, asynchronously via a Future, or reactively using Observable.

public class CommandHelloWorld extends HystrixCommand<String> {

    private final String name;

    public CommandHelloWorld(String name) {
        super(HystrixCommandGroupKey.Factory.asKey("ExampleGroup"));
        this.name = name;
    }

    @Override
    protected String run() {
        return "Hello " + name + "!";
    }
}

// Usage:
String s = new CommandHelloWorld("Bob").execute();
Future<String> s = new CommandHelloWorld("Bob").queue();
Observable<String> s = new CommandHelloWorld("Bob").observe();

To use the core Hystrix functionality, add the hystrix-core dependency to your project.

Maven Coordinates:

• GroupId: com.netflix.hystrix
• ArtifactId: hystrix-core

Ivy Coordinates:

• Org: com.netflix.hystrix
• Name: hystrix-core

<!-- Maven -->
<dependency>
    <groupId>com.netflix.hystrix</groupId>
    <artifactId>hystrix-core</artifactId>
    <version>1.2.0</version>
</dependency>

<!-- Ivy -->
<dependency org="com.netflix.hystrix" name="hystrix-core" rev="1.2.0" />

To use the Hystrix Request Servlet Filters in your J2EE/Servlet environment, add the following dependency to your build configuration.

Note: The version used in these examples is 1.1.2. Check Maven Central for the latest available version.

<!-- Maven -->
<dependency>
    <groupId>com.netflix.hystrix</groupId>
    <artifactId>hystrix-request-servlet</artifactId>
    <version>1.1.2</version>
</dependency>

<!-- Ivy -->
<dependency org="com.netflix.hystrix" name="hystrix-request-servlet" rev="1.1.2" />

Hystrix Javanica uses AspectJ for AOP functionality. If your project already uses AspectJ, you must add the HystrixCommandAspect to your aop.xml file:

<aspects>
        ...
        <aspect name="com.netflix.hystrix.contrib.javanica.aop.aspectj.HystrixCommandAspect"/>
        ...
</aspects>

To maintain data consistency, use the Get-Set-Get pattern: use @CacheResult for retrieval (GET) and @CacheRemove for updates (SET) to ensure the cache is flushed when data changes.

Note: @CacheRemove can be used without @HystrixCommand if you add the com.netflix.hystrix.contrib.javanica.aop.aspectj.HystrixCacheAspect to your AOP configuration.

public class UserService {
    @CacheResult
    @HystrixCommand
    public User getUserById(@CacheKey String id) { // GET
        return storage.get(id);
    }

    @CacheRemove(commandKey = "getUserById")
    @HystrixCommand
    public void update(@CacheKey("id") User user) { // SET
        storage.put(user.getId(), user);
    }
}

To use Hystrix metrics with Netflix Servo, add the hystrix-servo-metrics-publisher dependency to your project. You can find the latest binaries and dependency information on Maven Central.

<!-- Maven -->
<dependency>
    <groupId>com.netflix.hystrix</groupId>
    <artifactId>hystrix-servo-metrics-publisher</artifactId>
    <version>1.1.2</version>
</dependency>

<!-- Ivy -->
<dependency org="com.netflix.hystrix" name="hystrix-servo-metrics-publisher" rev="1.1.2" />