0
# Utilization Streaming
1

2
Servlet that streams current Hystrix command and thread pool utilization metrics, providing real-time insight into resource usage and capacity.
3

4
## Capabilities
5

6
### HystrixUtilizationSseServlet
7

8
Servlet that streams current utilization metrics for commands and thread pools in text/event-stream format.
9

10
```java { .api }
11
/**
12
 * Streams Hystrix utilization metrics in text/event-stream format
13
 * Provides real-time resource utilization for commands and thread pools
14
 */
15
public class HystrixUtilizationSseServlet extends HystrixSampleSseServlet {
16
    
17
    /**
18
     * Default constructor using HystrixUtilizationStream and default delay
19
     */
20
    public HystrixUtilizationSseServlet();
21
    
22
    /**
23
     * Package-private constructor for testing with custom stream and delay
24
     * @param sampleStream Observable stream of utilization data
25
     * @param pausePollerThreadDelayInMs Delay between polling cycles in milliseconds
26
     */
27
    HystrixUtilizationSseServlet(Observable<HystrixUtilization> sampleStream, int pausePollerThreadDelayInMs);
28
    
29
    /**
30
     * Returns maximum number of concurrent connections allowed
31
     * @return Maximum concurrent connections (default: 5)
32
     */
33
    protected int getMaxNumberConcurrentConnectionsAllowed();
34
    
35
    /**
36
     * Returns current number of active connections
37
     * @return Current connection count
38
     */
39
    protected int getNumberCurrentConnections();
40
    
41
    /**
42
     * Atomically increments and returns current concurrent connection count
43
     * @return New connection count after increment
44
     */
45
    protected int incrementAndGetCurrentConcurrentConnections();
46
    
47
    /**
48
     * Atomically decrements current concurrent connection count
49
     */
50
    protected void decrementCurrentConcurrentConnections();
51
}
52
```
53

54
### HystrixUtilizationJsonStream (Deprecated)
55

56
Legacy utility for converting utilization objects to JSON format.
57

58
```java { .api }
59
/**
60
 * Links HystrixUtilizationStream and JSON encoding
61
 * @deprecated Since 1.5.4 - prefer mapping serialization on HystrixUtilizationStream.observe()
62
 */
63
@Deprecated
64
public class HystrixUtilizationJsonStream {
65
    
66
    /**
67
     * Default constructor using default utilization stream
68
     */
69
    public HystrixUtilizationJsonStream();
70
    
71
    /**
72
     * Constructor with custom stream generator
73
     * @param streamGenerator Function to generate utilization observable
74
     */
75
    public HystrixUtilizationJsonStream(Func1<Integer, Observable<HystrixUtilization>> streamGenerator);
76
    
77
    /**
78
     * Convert utilization object to JSON string
79
     * @param utilization Utilization object to convert
80
     * @return JSON string representation
81
     * @throws IOException if JSON generation fails
82
     */
83
    protected static String convertToJson(HystrixUtilization utilization) throws IOException;
84
    
85
    /**
86
     * @deprecated Use HystrixUtilizationStream.observe() instead
87
     */
88
    @Deprecated
89
    public Observable<HystrixUtilization> observe(int delay);
90
    
91
    /**
92
     * @deprecated Use HystrixUtilizationStream.observe() and convertToJson() instead
93
     */
94
    @Deprecated
95
    public Observable<String> observeJson(int delay);
96
}
97
```
98

99
**Web.xml Configuration:**
100

101
```xml
102
<servlet>
103
  <description></description>
104
  <display-name>HystrixUtilizationSseServlet</display-name>
105
  <servlet-name>HystrixUtilizationSseServlet</servlet-name>
106
  <servlet-class>com.netflix.hystrix.contrib.sample.stream.HystrixUtilizationSseServlet</servlet-class>
107
</servlet>
108
<servlet-mapping>
109
  <servlet-name>HystrixUtilizationSseServlet</servlet-name>
110
  <url-pattern>/hystrix/utilization.stream</url-pattern>
111
</servlet-mapping>
112
```
113

114
**Usage Examples:**
115

116
```java
117
// Deploy servlet via web.xml configuration
118
// Access utilization stream
119
curl http://localhost:8080/app/hystrix/utilization.stream
120

121
// Using deprecated JSON stream API
122
HystrixUtilizationJsonStream stream = new HystrixUtilizationJsonStream();
123
stream.observeJson(1000).subscribe(json -> {
124
    System.out.println("Utilization: " + json);
125
});
126
```
127

128
## Data Format
129

130
The servlet outputs current utilization information in JSON format:
131

132
### Utilization Structure
133

134
```json
135
data: {
136
  "type": "HystrixUtilization",
137
  "commands": {
138
    "GetUser": {
139
      "activeCount": 2
140
    },
141
    "GetUserPreferences": {
142
      "activeCount": 0
143
    },
144
    "CreateUser": {
145
      "activeCount": 1
146
    }
147
  },
148
  "threadpools": {
149
    "UserService": {
150
      "activeCount": 3,
151
      "queueSize": 0,
152
      "corePoolSize": 10,
153
      "poolSize": 10
154
    },
155
    "NotificationService": {
156
      "activeCount": 0,
157
      "queueSize": 2,
158
      "corePoolSize": 5,
159
      "poolSize": 5
160
    }
161
  }
162
}
163
```
164

165
### Command Utilization Fields
166

167
For each command, the utilization data includes:
168

169
- `activeCount` - Number of currently executing command instances
170

171
### Thread Pool Utilization Fields
172

173
For each thread pool, the utilization data includes:
174

175
- `activeCount` - Number of currently active threads
176
- `queueSize` - Current number of tasks in the queue
177
- `corePoolSize` - Core thread pool size
178
- `poolSize` - Current thread pool size
179

180
## Static Utility Methods
181

182
The deprecated JSON stream class provides static utility methods for JSON conversion:
183

184
```java { .api }
185
/**
186
 * Write command utilization data to JSON generator
187
 * @param json JSON generator to write to
188
 * @param key Command key
189
 * @param utilization Command utilization data
190
 * @throws IOException if JSON writing fails
191
 */
192
private static void writeCommandUtilizationJson(JsonGenerator json, HystrixCommandKey key, HystrixCommandUtilization utilization) throws IOException;
193

194
/**
195
 * Write thread pool utilization data to JSON generator
196
 * @param json JSON generator to write to
197
 * @param threadPoolKey Thread pool key
198
 * @param utilization Thread pool utilization data
199
 * @throws IOException if JSON writing fails
200
 */
201
private static void writeThreadPoolUtilizationJson(JsonGenerator json, HystrixThreadPoolKey threadPoolKey, HystrixThreadPoolUtilization utilization) throws IOException;
202
```
203

204
## Use Cases
205

206
### Real-time Monitoring
207

208
Monitor current resource usage across all Hystrix commands and thread pools:
209

210
```java
211
// Monitor utilization via HTTP stream
212
curl http://localhost:8080/app/hystrix/utilization.stream
213

214
// Process utilization data in JavaScript
215
const eventSource = new EventSource('/hystrix/utilization.stream');
216
eventSource.onmessage = function(event) {
217
    const utilization = JSON.parse(event.data);
218
    
219
    // Check for overloaded commands
220
    Object.entries(utilization.commands).forEach(([name, metrics]) => {
221
        if (metrics.activeCount > 10) {
222
            console.warn(`Command ${name} has high utilization: ${metrics.activeCount}`);
223
        }
224
    });
225
    
226
    // Check thread pool usage
227
    Object.entries(utilization.threadpools).forEach(([name, metrics]) => {
228
        const utilizationPercent = (metrics.activeCount / metrics.corePoolSize) * 100;
229
        if (utilizationPercent > 80) {
230
            console.warn(`Thread pool ${name} is ${utilizationPercent}% utilized`);
231
        }
232
    });
233
};
234
```
235

236
### Capacity Planning
237

238
Use utilization data to understand resource requirements:
239

240
- **Command Utilization**: Identify commands with consistently high concurrent execution
241
- **Thread Pool Utilization**: Determine optimal thread pool sizes based on actual usage
242
- **Queue Monitoring**: Track queue depths to detect bottlenecks
243

244
### Alerting Integration
245

246
Integrate with monitoring systems for automated alerting:
247

248
```java
249
// Example integration with monitoring system
250
HystrixUtilizationStream.getInstance()
251
    .observe()
252
    .subscribe(utilization -> {
253
        utilization.getCommandUtilizationMap().forEach((key, commandUtil) -> {
254
            if (commandUtil.getConcurrentCommandCount() > thresholds.get(key)) {
255
                alertingService.sendAlert("High command utilization", key.name());
256
            }
257
        });
258
        
259
        utilization.getThreadPoolUtilizationMap().forEach((key, poolUtil) -> {
260
            double utilizationPercent = (double) poolUtil.getCurrentActiveCount() / poolUtil.getCurrentCorePoolSize();
261
            if (utilizationPercent > 0.9) {
262
                alertingService.sendAlert("High thread pool utilization", key.name());
263
            }
264
        });
265
    });
266
```
267

268
## Migration from Deprecated API
269

270
```java
271
// Old approach (deprecated)
272
HystrixUtilizationJsonStream jsonStream = new HystrixUtilizationJsonStream();
273
jsonStream.observeJson(1000).subscribe(json -> {
274
    // process json
275
});
276

277
// New approach (recommended)
278
HystrixUtilizationStream.getInstance()
279
    .observe()
280
    .map(SerialHystrixUtilization::toJsonString)
281
    .subscribe(json -> {
282
        // process json
283
    });
284
```