0
# Hystrix Metrics Event Stream
1

2
Hystrix Metrics Event Stream is a Java library module within the Netflix Hystrix circuit breaker framework that provides real-time streaming of circuit breaker and thread pool metrics via Server-Sent Events (SSE). The module enables monitoring dashboards and applications to receive continuous metric updates including error rates, latency percentiles, circuit breaker states, and thread pool statistics.
3

4
## Package Information
5

6
- **Package Name**: hystrix-metrics-event-stream
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add to Maven dependencies:
10
  ```xml
11
  <dependency>
12
    <groupId>com.netflix.hystrix</groupId>
13
    <artifactId>hystrix-metrics-event-stream</artifactId>
14
    <version>1.5.18</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java
21
// Primary streaming servlets
22
import com.netflix.hystrix.contrib.metrics.eventstream.HystrixMetricsStreamServlet;
23
import com.netflix.hystrix.contrib.requests.stream.HystrixRequestEventsSseServlet;
24
import com.netflix.hystrix.contrib.sample.stream.HystrixConfigSseServlet;
25
import com.netflix.hystrix.contrib.sample.stream.HystrixUtilizationSseServlet;
26
import com.netflix.hystrix.contrib.sample.stream.HystrixSampleSseServlet;
27

28
// Legacy polling (deprecated)
29
import com.netflix.hystrix.contrib.metrics.eventstream.HystrixMetricsPoller;
30

31
// RxJava Observable types
32
import rx.Observable;
33
```
34

35
## Basic Usage
36

37
The primary use case is to expose Hystrix metrics via HTTP Server-Sent Events:
38

39
```xml
40
<!-- Configure in web.xml -->
41
<servlet>
42
  <servlet-name>HystrixMetricsStreamServlet</servlet-name>
43
  <servlet-class>com.netflix.hystrix.contrib.metrics.eventstream.HystrixMetricsStreamServlet</servlet-class>
44
</servlet>
45
<servlet-mapping>
46
  <servlet-name>HystrixMetricsStreamServlet</servlet-name>
47
  <url-pattern>/hystrix.stream</url-pattern>
48
</servlet-mapping>
49
```
50

51
Then access the stream:
52
```bash
53
curl http://hostname:port/appname/hystrix.stream
54
```
55

56
This produces continuous JSON events like:
57
```json
58
data: {
59
  "type": "HystrixCommand",
60
  "name": "PlaylistGet",
61
  "group": "PlaylistGet",
62
  "currentTime": 1355239617628,
63
  "isCircuitBreakerOpen": false,
64
  "errorPercentage": 0,
65
  "errorCount": 0,
66
  "requestCount": 121,
67
  "latencyExecute_mean": 13,
68
  "latencyTotal_mean": 15
69
}
70
```
71

72
## Architecture
73

74
The library is organized around several key components:
75

76
- **Servlet Layer**: HTTP servlets that implement Server-Sent Events streaming protocol
77
- **Poller Layer**: Background polling mechanisms for gathering metrics (deprecated)
78
- **Stream Processing**: RxJava-based reactive streams for real-time data processing
79
- **JSON Serialization**: Jackson-based JSON encoding of metric data
80
- **Connection Management**: Configurable concurrent connection limits and throttling
81

82
## Capabilities
83

84
### Metrics Streaming
85

86
Primary servlet for streaming Hystrix command and thread pool metrics in text/event-stream format.
87

88
```java { .api }
89
public class HystrixMetricsStreamServlet extends HystrixSampleSseServlet {
90
    public HystrixMetricsStreamServlet();
91
    HystrixMetricsStreamServlet(Observable<HystrixDashboardStream.DashboardData> sampleStream, int pausePollerThreadDelayInMs);
92
}
93
```
94

95
[Metrics Streaming](./metrics-streaming.md)
96

97
### Base SSE Servlet Framework
98

99
Abstract base class providing Server-Sent Events functionality for all streaming servlets.
100

101
```java { .api }
102
public abstract class HystrixSampleSseServlet extends HttpServlet {
103
    protected HystrixSampleSseServlet(Observable<String> sampleStream);
104
    protected HystrixSampleSseServlet(Observable<String> sampleStream, int pausePollerThreadDelayInMs);
105
    
106
    // Abstract methods for connection management
107
    protected abstract int getMaxNumberConcurrentConnectionsAllowed();
108
    protected abstract int getNumberCurrentConnections();
109
    protected abstract int incrementAndGetCurrentConcurrentConnections();
110
    protected abstract void decrementCurrentConcurrentConnections();
111
    
112
    // Lifecycle methods
113
    public static void shutdown();
114
    public void init() throws ServletException;
115
    public void destroy();
116
}
117
```
118

119
[Base SSE Framework](./base-sse-servlet.md)
120

121
### Request Events Streaming
122

123
Servlet that streams individual Hystrix request events as they occur.
124

125
```java { .api }
126
public class HystrixRequestEventsSseServlet extends HystrixSampleSseServlet {
127
    public HystrixRequestEventsSseServlet();
128
    HystrixRequestEventsSseServlet(Observable<HystrixRequestEvents> sampleStream, int pausePollerThreadDelayInMs);
129
}
130
```
131

132
[Request Events Streaming](./request-events-streaming.md)
133

134
### Configuration Streaming
135

136
Servlet that streams Hystrix configuration information.
137

138
```java { .api }
139
public class HystrixConfigSseServlet extends HystrixSampleSseServlet {
140
    public HystrixConfigSseServlet();
141
    HystrixConfigSseServlet(Observable<HystrixConfiguration> sampleStream, int pausePollerThreadDelayInMs);
142
}
143
```
144

145
[Configuration Streaming](./configuration-streaming.md)
146

147
### Utilization Streaming  
148

149
Servlet that streams current Hystrix command and thread pool utilization metrics.
150

151
```java { .api }
152
public class HystrixUtilizationSseServlet extends HystrixSampleSseServlet {
153
    public HystrixUtilizationSseServlet();
154
    HystrixUtilizationSseServlet(Observable<HystrixUtilization> sampleStream, int pausePollerThreadDelayInMs);
155
}
156
```
157

158
[Utilization Streaming](./utilization-streaming.md)
159

160
### Legacy Metrics Polling (Deprecated)
161

162
Polling-based metrics collection system (deprecated since 1.5.4).
163

164
```java { .api }
165
@Deprecated
166
public class HystrixMetricsPoller {
167
    public HystrixMetricsPoller(MetricsAsJsonPollerListener listener, int delay);
168
    public synchronized void start();
169
    public synchronized void pause();
170
    public synchronized void shutdown();
171
    public boolean isRunning();
172
    
173
    public static interface MetricsAsJsonPollerListener {
174
        public void handleJsonMetric(String json);
175
    }
176
}
177
```
178

179
[Legacy Metrics Polling](./legacy-metrics-polling.md)
180

181
## Configuration
182

183
### Connection Limits
184

185
All servlets support configurable maximum concurrent connections:
186

187
```java
188
// System property configuration (default: 5)
189
hystrix.config.stream.maxConcurrentConnections=10
190
```
191

192
### Threading
193

194
- Default pause delay: 500ms between polling cycles
195
- Uses RxJava IO scheduler for non-blocking stream processing
196
- Atomic connection counting for thread safety
197

198
## Types
199

200
```java { .api }
201
// Core Data Classes
202
public class HystrixDashboardStream.DashboardData {
203
    // Contains dashboard metrics for commands and thread pools
204
}
205

206
public interface HystrixRequestEvents {
207
    // Contains detailed request execution information including events and latencies
208
}
209

210
public interface HystrixConfiguration {
211
    // Contains complete configuration for commands, thread pools, and collapsers
212
    Map<HystrixCommandKey, HystrixCommandConfiguration> getCommandConfig();
213
    Map<HystrixThreadPoolKey, HystrixThreadPoolConfiguration> getThreadPoolConfig();
214
    Map<HystrixCollapserKey, HystrixCollapserConfiguration> getCollapserConfig();
215
}
216

217
public interface HystrixUtilization {
218
    // Contains current utilization metrics for commands and thread pools
219
    Map<HystrixCommandKey, HystrixCommandUtilization> getCommandUtilizationMap();
220
    Map<HystrixThreadPoolKey, HystrixThreadPoolUtilization> getThreadPoolUtilizationMap();
221
}
222

223
// RxJava Observable Type
224
public class Observable<T> {
225
    // Reactive stream for asynchronous data processing
226
}
227

228
// Configuration Properties
229
public class DynamicIntProperty {
230
    int get();
231
}
232
```
233

234
## Error Handling
235

236
- HTTP 503 responses when max concurrent connections exceeded
237
- Graceful handling of client disconnections
238
- Automatic cleanup of resources when servlets are destroyed
239
- Version mismatch protection for deprecated metrics fields