Mastering Hystrix: Practical Guide to Circuit Breaker Configuration in Spring Cloud

Introduction

This article, written after Hystrix entered maintenance mode, serves as a timely guide for developers who have already encountered issues with Hystrix. It explains important considerations for using circuit breakers, offering both theoretical background and practical parameter tuning.

Background

In a typical Spring Cloud stack, service calls follow the chain: Feign → Hystrix → Ribbon → Http Client (Apache HttpComponents or OkHttp). The diagram below illustrates this flow.

Configuration

Ⅰ Isolation Methods

Thread isolation (default) : Uses a thread pool for each dependent service. Requests are queued and processed with a timeout, allowing the system to absorb traffic spikes.

Semaphore isolation : Uses an atomic counter to limit concurrent threads. Requests exceeding the limit are rejected immediately, which cannot handle traffic bursts.

Ⅱ Circuit Breaker

If a target service becomes slow or times out frequently, the circuit breaker opens, preventing further calls and quickly releasing resources. When the service recovers, calls resume.

The process is analogous to a fuse.

Usage Steps

1. Add Dependency

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-hystrix</artifactId>
</dependency>

2. Configure Parameters

feign:
  hystrix:
    enabled: true
hystrix:
  command:
    default:
      execution:
        isolation:
          thread:
            timeoutInMilliseconds: 60000
  threadpool:
    default:
      coreSize: 10
      maxQueueSize: 50
      queueSizeRejectionThreshold: 30
      keepAliveTimeMinutes: 3

3. Configure Fallback

It is recommended to provide a distinct fallback implementation for each Feign client.

4. Advanced Configurations

Global settings can be overridden with service‑specific or method‑specific configurations. Example:

hystrix:
  command:
    default:
      execution:
        isolation:
          thread:
            timeoutInMilliseconds: 60000
  threadpool:
    default:
      coreSize: 10
      maxQueueSize: 50
      queueSizeRejectionThreshold: 30
      keepAliveTimeMinutes: 3
    base-rpc:
      coreSize: 10
      maxQueueSize: 30
      queueSizeRejectionThreshold: 20
      keepAliveTimeMinutes: 3
    BaseApiClient#searchItemSkuList(PosSkuSearch):
      coreSize: 10
      maxQueueSize: 40
      queueSizeRejectionThreshold: 30
      keepAliveTimeMinutes: 1

Annotations such as @HystrixCommand can also be used for configuration.

5. Dynamic Configuration Updates

To modify settings without restarting services, Hystrix can be managed via Netflix Archaius. Example code:

// Retrieve configuration
AbstractConfiguration config = ConfigurationManager.getConfigInstance();
// List keys under hystrix.threadpool
Iterable<String> iterable = () -> config.getKeys("hystrix.threadpool");
List<Property> result = StreamSupport.stream(iterable.spliterator(), false)
    .map(t -> new Property(t, config.getString(t, "")))
    .sorted(Comparator.comparing(Property::getName))
    .collect(Collectors.toList());
// Update a property
config.setProperty("hystrix.threadpool.base-rpc.coreSize", 20);
// Remove a property
config.clearProperty("hystrix.threadpool.base-rpc.coreSize");

Other Timeout Parameters

1. Feign Timeout

feign:
  hystrix:
    enabled: true
  client:
    config:
      default:
        connectTimeout: 5000
        readTimeout: 5000
      rpc-pos:
        connectTimeout: 5000
        readTimeout: 8000
      xx-rpc:
        connectTimeout: 5000
        readTimeout: 12000
      order-rpc:
        connectTimeout: 5000
        readTimeout: 8000

Feign’s timeout settings propagate to Ribbon and the underlying HTTP client.

2. Ribbon Timeout

# Global configuration
ribbon:
  ReadTimeout: 60000
  ConnectTimeout: 10000
  OkToRetryOnAllOperations: true
  MaxAutoRetriesNextServer: 2
  MaxAutoRetries: 0
  ServerListRefreshInterval: 5000
  retryableStatusCodes: 404,500
# Service‑specific configuration
base-rpc:
  ribbon:
    ReadTimeout: 60000
    ConnectTimeout: 10000
    OkToRetryOnAllOperations: true
    MaxAutoRetriesNextServer: 2
    MaxAutoRetries: 0
    ServerListRefreshInterval: 5000
    retryableStatusCodes: 404,500

Ribbon inherits timeout values from Feign when they are set.

3. HttpClient Timeout

feign:
  hystrix:
    enabled: true
  okhttp:
    enabled: true
  httpclient:
    enabled: false
    max-connections: 500
    max-connections-per-route: 50
    connection-timeout: 8000
    connection-timer-repeat: 6000
    time-to-live: 5
    time-to-live-unit: minutes

The rule is that the caller’s timeout overrides the callee’s timeout, implemented via Spring Boot’s auto‑configuration.

Summary: Feign ultimately decides the timeout values.

Hystrix Dashboard

To visualize Hystrix metrics, add the following dependency:

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-hystrix-dashboard</artifactId>
</dependency>

Appendix: Configuration Property Details

1. Command Properties

Properties prefixed with hystrix.command.default control the execution of HystrixCommand. Key parameters include execution.isolation.strategy and execution.isolation.thread.timeoutInMilliseconds.

2. Fallback

Properties under hystrix.command.default also affect getFallback() behavior for both thread and semaphore isolation strategies.

3. Circuit Breaker

These properties control the HystrixCircuitBreaker.

4. Metrics

Metrics‑related properties capture execution statistics for HystrixCommand and HystrixObservableCommand.

5. Request Context

These properties affect the HystrixRequestContext feature.

2. Collapser Properties

Properties prefixed with hystrix.collapser.default control HystrixCollapser behavior.

3. ThreadPool Properties

Properties prefixed with hystrix.threadpool.default configure the thread pool used by Hystrix commands. The default size of 10 threads is usually sufficient.

Conclusion

Although Hystrix is now in maintenance mode, many legacy systems still rely on it. This guide collects essential configuration details for those environments, serving as a reference rather than a promotional piece.