# netflix/hystrix architecture

> Architecture diagram of the GitHub repository netflix/hystrix, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/netflix/hystrix
- Repository: https://github.com/netflix/hystrix

## Overview

Hystrix is a fault-tolerance and latency-isolation library. A caller wraps remote work in a command and invokes it synchronously, asynchronously, or as an observable; the runtime applies isolation, circuit breaking, fallback, request caching, and optional batching. Runtime events feed metrics and operational streams, with adapters for several monitoring and web stacks. The README documents the main behavior; the sampled source/index supports selected wiring, but many runtime implementations were not excerpted, so uncertain connections are omitted or dashed.

Main entry points: [`hystrix-core/src/main/java/com/netflix/hystrix/HystrixCommandMetrics.java`](https://github.com/netflix/hystrix/blob/master/hystrix-core/src/main/java/com/netflix/hystrix/HystrixCommandMetrics.java) (Command metrics), [`hystrix-core/src/main/java/com/netflix/hystrix/AbstractCommand.java`](https://github.com/netflix/hystrix/blob/master/hystrix-core/src/main/java/com/netflix/hystrix/AbstractCommand.java) (Execution runtime), [`hystrix-core/src/main/java/com/netflix/hystrix/HystrixCommand.java`](https://github.com/netflix/hystrix/blob/master/hystrix-core/src/main/java/com/netflix/hystrix/HystrixCommand.java) (Hystrix command), [`hystrix-core/src/main/java/com/netflix/hystrix/metric/consumer/HystrixDashboardStream.java`](https://github.com/netflix/hystrix/blob/master/hystrix-core/src/main/java/com/netflix/hystrix/metric/consumer/HystrixDashboardStream.java) (Dashboard stream)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_execution["Command execution"]
  node_command["Hystrix command"]
  node_execution_core["Execution runtime"]
  node_circuit["Circuit breaker"]
  node_pool["Thread pool"]
  node_fallback["Fallback handling"]
end

subgraph group_request["Request features"]
  node_collapser["Request collapsing"]
  node_request_context["Request context"]
  node_request_cache["Request cache"]
end

subgraph group_observability["Metrics and streams"]
  node_command_metrics["Command metrics"]
  node_event_streams["Event streams"]
  node_dashboard_stream["Dashboard stream"]
  node_serialization["Dashboard serialization"]
end

subgraph group_adapters["Language and integrations"]
  node_javanica["Annotation API"]
  node_clojure["Clojure API<br/>[core.clj]"]
  node_jaxrs["JAX-RS streams"]
  node_codahale["Coda Hale publisher"]
  node_servo["Servo publisher"]
  node_yammer["Yammer publisher"]
end

node_caller(("Application caller"))
node_stream_client(("Monitoring client"))

node_caller -->|"invokes"| node_command
node_command -.->|"executes through"| node_execution_core
node_execution_core -.->|"checks circuit"| node_circuit
node_execution_core -.->|"isolates work"| node_pool
node_execution_core -.->|"runs fallback"| node_fallback
node_caller -.->|"may batch"| node_collapser
node_request_context -->|"scopes cache"| node_request_cache
node_command -.->|"may cache"| node_request_cache
node_command_metrics -->|"publishes events"| node_event_streams
node_event_streams -.->|"feeds metrics"| node_dashboard_stream
node_dashboard_stream -->|"serializes data"| node_serialization
node_jaxrs -->|"reads stream"| node_dashboard_stream
node_jaxrs -->|"serves events"| node_stream_client
node_caller -.->|"uses annotations"| node_javanica
node_javanica -.->|"adapts methods"| node_command
node_caller -.->|"uses API"| node_clojure
node_command_metrics -.->|"publishes metrics"| node_codahale
node_command_metrics -.->|"publishes metrics"| node_servo
node_command_metrics -.->|"publishes metrics"| node_yammer

click node_command "https://github.com/netflix/hystrix/blob/master/hystrix-core/src/main/java/com/netflix/hystrix/HystrixCommand.java"
click node_execution_core "https://github.com/netflix/hystrix/blob/master/hystrix-core/src/main/java/com/netflix/hystrix/AbstractCommand.java"
click node_circuit "https://github.com/netflix/hystrix/blob/master/hystrix-core/src/main/java/com/netflix/hystrix/HystrixCircuitBreaker.java"
click node_pool "https://github.com/netflix/hystrix/blob/master/hystrix-core/src/main/java/com/netflix/hystrix/HystrixThreadPool.java"
click node_fallback "https://github.com/netflix/hystrix/blob/master/hystrix-core/src/main/java/com/netflix/hystrix/AbstractCommand.java"
click node_collapser "https://github.com/netflix/hystrix/blob/master/hystrix-core/src/main/java/com/netflix/hystrix/collapser/RequestCollapser.java"
click node_request_context "https://github.com/netflix/hystrix/blob/master/hystrix-core/src/main/java/com/netflix/hystrix/strategy/concurrency/HystrixRequestContext.java"
click node_request_cache "https://github.com/netflix/hystrix/blob/master/hystrix-core/src/main/java/com/netflix/hystrix/HystrixRequestCache.java"
click node_command_metrics "https://github.com/netflix/hystrix/blob/master/hystrix-core/src/main/java/com/netflix/hystrix/HystrixCommandMetrics.java"
click node_event_streams "https://github.com/netflix/hystrix/blob/master/hystrix-core/src/main/java/com/netflix/hystrix/metric/HystrixThreadEventStream.java"
click node_dashboard_stream "https://github.com/netflix/hystrix/blob/master/hystrix-core/src/main/java/com/netflix/hystrix/metric/consumer/HystrixDashboardStream.java"
click node_serialization "https://github.com/netflix/hystrix/blob/master/hystrix-serialization/src/main/java/com/netflix/hystrix/serial/SerialHystrixDashboardData.java"
click node_javanica "https://github.com/netflix/hystrix/blob/master/hystrix-contrib/hystrix-javanica/src/main/java/com/netflix/hystrix/contrib/javanica/aop/aspectj/HystrixCommandAspect.java"
click node_clojure "https://github.com/netflix/hystrix/blob/master/hystrix-contrib/hystrix-clj/src/main/clojure/com/netflix/hystrix/core.clj"
click node_jaxrs "https://github.com/netflix/hystrix/blob/master/hystrix-contrib/hystrix-metrics-event-stream-jaxrs/src/main/java/com/netflix/hystrix/contrib/metrics/controller/HystrixMetricsStreamController.java"
click node_codahale "https://github.com/netflix/hystrix/blob/master/hystrix-contrib/hystrix-codahale-metrics-publisher/src/main/java/com/netflix/hystrix/contrib/codahalemetricspublisher/HystrixCodaHaleMetricsPublisher.java"
click node_servo "https://github.com/netflix/hystrix/blob/master/hystrix-contrib/hystrix-servo-metrics-publisher/src/main/java/com/netflix/hystrix/contrib/servopublisher/HystrixServoMetricsPublisher.java"
click node_yammer "https://github.com/netflix/hystrix/blob/master/hystrix-contrib/hystrix-yammer-metrics-publisher/src/main/java/com/netflix/hystrix/contrib/yammermetricspublisher/HystrixYammerMetricsPublisher.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_command,node_execution_core,node_circuit,node_pool,node_fallback,node_stream_client toneBlue
class node_collapser,node_request_context,node_request_cache toneAmber
class node_command_metrics,node_event_streams,node_dashboard_stream,node_serialization toneMint
class node_javanica,node_clojure,node_jaxrs,node_codahale,node_servo,node_yammer toneRose
class node_caller toneIndigo
```

## Components

### Command execution

- [Hystrix command](https://github.com/netflix/hystrix/blob/master/hystrix-core/src/main/java/com/netflix/hystrix/HystrixCommand.java): `hystrix-core/src/main/java/com/netflix/hystrix/HystrixCommand.java`
- [Execution runtime](https://github.com/netflix/hystrix/blob/master/hystrix-core/src/main/java/com/netflix/hystrix/AbstractCommand.java): `hystrix-core/src/main/java/com/netflix/hystrix/AbstractCommand.java`
- [Circuit breaker](https://github.com/netflix/hystrix/blob/master/hystrix-core/src/main/java/com/netflix/hystrix/HystrixCircuitBreaker.java): `hystrix-core/src/main/java/com/netflix/hystrix/HystrixCircuitBreaker.java`
- [Thread pool](https://github.com/netflix/hystrix/blob/master/hystrix-core/src/main/java/com/netflix/hystrix/HystrixThreadPool.java): `hystrix-core/src/main/java/com/netflix/hystrix/HystrixThreadPool.java`
- [Fallback handling](https://github.com/netflix/hystrix/blob/master/hystrix-core/src/main/java/com/netflix/hystrix/AbstractCommand.java): `hystrix-core/src/main/java/com/netflix/hystrix/AbstractCommand.java`

### Request features

- [Request collapsing](https://github.com/netflix/hystrix/blob/master/hystrix-core/src/main/java/com/netflix/hystrix/collapser/RequestCollapser.java): `hystrix-core/src/main/java/com/netflix/hystrix/collapser/RequestCollapser.java`
- [Request context](https://github.com/netflix/hystrix/blob/master/hystrix-core/src/main/java/com/netflix/hystrix/strategy/concurrency/HystrixRequestContext.java): `hystrix-core/src/main/java/com/netflix/hystrix/strategy/concurrency/HystrixRequestContext.java`
- [Request cache](https://github.com/netflix/hystrix/blob/master/hystrix-core/src/main/java/com/netflix/hystrix/HystrixRequestCache.java): `hystrix-core/src/main/java/com/netflix/hystrix/HystrixRequestCache.java`

### Metrics and streams

- [Command metrics](https://github.com/netflix/hystrix/blob/master/hystrix-core/src/main/java/com/netflix/hystrix/HystrixCommandMetrics.java): `hystrix-core/src/main/java/com/netflix/hystrix/HystrixCommandMetrics.java`
- [Event streams](https://github.com/netflix/hystrix/blob/master/hystrix-core/src/main/java/com/netflix/hystrix/metric/HystrixThreadEventStream.java): `hystrix-core/src/main/java/com/netflix/hystrix/metric/HystrixThreadEventStream.java`
- [Dashboard stream](https://github.com/netflix/hystrix/blob/master/hystrix-core/src/main/java/com/netflix/hystrix/metric/consumer/HystrixDashboardStream.java): `hystrix-core/src/main/java/com/netflix/hystrix/metric/consumer/HystrixDashboardStream.java`
- [Dashboard serialization](https://github.com/netflix/hystrix/blob/master/hystrix-serialization/src/main/java/com/netflix/hystrix/serial/SerialHystrixDashboardData.java): `hystrix-serialization/src/main/java/com/netflix/hystrix/serial/SerialHystrixDashboardData.java`

### Language and integrations

- [Annotation API](https://github.com/netflix/hystrix/blob/master/hystrix-contrib/hystrix-javanica/src/main/java/com/netflix/hystrix/contrib/javanica/aop/aspectj/HystrixCommandAspect.java): `hystrix-contrib/hystrix-javanica/src/main/java/com/netflix/hystrix/contrib/javanica/aop/aspectj/HystrixCommandAspect.java`
- [Clojure API](https://github.com/netflix/hystrix/blob/master/hystrix-contrib/hystrix-clj/src/main/clojure/com/netflix/hystrix/core.clj): `hystrix-contrib/hystrix-clj/src/main/clojure/com/netflix/hystrix/core.clj`
- [JAX-RS streams](https://github.com/netflix/hystrix/blob/master/hystrix-contrib/hystrix-metrics-event-stream-jaxrs/src/main/java/com/netflix/hystrix/contrib/metrics/controller/HystrixMetricsStreamController.java): `hystrix-contrib/hystrix-metrics-event-stream-jaxrs/src/main/java/com/netflix/hystrix/contrib/metrics/controller/HystrixMetricsStreamController.java`
- [Coda Hale publisher](https://github.com/netflix/hystrix/blob/master/hystrix-contrib/hystrix-codahale-metrics-publisher/src/main/java/com/netflix/hystrix/contrib/codahalemetricspublisher/HystrixCodaHaleMetricsPublisher.java): `hystrix-contrib/hystrix-codahale-metrics-publisher/src/main/java/com/netflix/hystrix/contrib/codahalemetricspublisher/HystrixCodaHaleMetricsPublisher.java`
- [Servo publisher](https://github.com/netflix/hystrix/blob/master/hystrix-contrib/hystrix-servo-metrics-publisher/src/main/java/com/netflix/hystrix/contrib/servopublisher/HystrixServoMetricsPublisher.java): `hystrix-contrib/hystrix-servo-metrics-publisher/src/main/java/com/netflix/hystrix/contrib/servopublisher/HystrixServoMetricsPublisher.java`
- [Yammer publisher](https://github.com/netflix/hystrix/blob/master/hystrix-contrib/hystrix-yammer-metrics-publisher/src/main/java/com/netflix/hystrix/contrib/yammermetricspublisher/HystrixYammerMetricsPublisher.java): `hystrix-contrib/hystrix-yammer-metrics-publisher/src/main/java/com/netflix/hystrix/contrib/yammermetricspublisher/HystrixYammerMetricsPublisher.java`

### Other components

- **Application caller**
- **Monitoring client**

## Connections

- Application caller → Hystrix command: invokes
- Hystrix command → Execution runtime: executes through
- Execution runtime → Circuit breaker: checks circuit (evidence: `hystrix-core/src/main/java/com/netflix/hystrix/AbstractCommand.java`)
- Execution runtime → Thread pool: isolates work (evidence: `hystrix-core/src/main/java/com/netflix/hystrix/AbstractCommand.java`)
- Execution runtime → Fallback handling: runs fallback (evidence: `hystrix-core/src/main/java/com/netflix/hystrix/AbstractCommand.java`)
- Application caller → Request collapsing: may batch
- Request context → Request cache: scopes cache (evidence: `hystrix-core/src/main/java/com/netflix/hystrix/strategy/concurrency/HystrixRequestContext.java`)
- Hystrix command → Request cache: may cache
- Command metrics → Event streams: publishes events (evidence: `hystrix-core/src/main/java/com/netflix/hystrix/HystrixCommandMetrics.java`)
- Event streams → Dashboard stream: feeds metrics
- Dashboard stream → Dashboard serialization: serializes data (evidence: `hystrix-serialization/src/main/java/com/netflix/hystrix/serial/SerialHystrixDashboardData.java`)
- JAX-RS streams → Dashboard stream: reads stream (evidence: `hystrix-contrib/hystrix-metrics-event-stream-jaxrs/src/main/java/com/netflix/hystrix/contrib/metrics/controller/HystrixMetricsStreamController.java`)
- JAX-RS streams → Monitoring client: serves events
- Application caller → Annotation API: uses annotations
- Annotation API → Hystrix command: adapts methods
- Application caller → Clojure API: uses API
- Command metrics → Coda Hale publisher: publishes metrics
- Command metrics → Servo publisher: publishes metrics
- Command metrics → Yammer publisher: publishes metrics
