0
# Statistics
1

2
Monitoring and statistics interfaces provide comprehensive tracking of performance, throughput, and resource usage in Siddhi applications. The statistics module enables integration with monitoring systems and provides runtime insights into application behavior.
3

4
## Statistics Levels
5

6
### Level
7

8
Enumeration for statistics levels controlling the depth of monitoring and performance tracking.
9

10
```java { .api }
11
public enum Level {
12
    OFF,     // No statistics collection
13
    BASIC,   // Basic performance metrics
14
    DETAIL   // Detailed statistics with comprehensive tracking
15
}
16
```
17

18
## Runtime Statistics Management
19

20
### SiddhiAppRuntime Statistics
21

22
```java { .api }
23
public class SiddhiAppRuntime {
24
    // Statistics Configuration
25
    public Level getRootMetricsLevel();
26
    public void enableStats(Level level);
27
}
28
```
29

30
### Usage Examples
31

32
```java
33
// Configure statistics at runtime
34
SiddhiAppRuntime runtime = siddhiManager.createSiddhiAppRuntime(siddhiApp);
35

36
// Check current statistics level
37
Level currentLevel = runtime.getRootMetricsLevel();
38
System.out.println("Current stats level: " + currentLevel);
39

40
// Enable basic statistics
41
runtime.enableStats(Level.BASIC);
42

43
// Start runtime with statistics enabled
44
runtime.start();
45

46
// Process events...
47
InputHandler handler = runtime.getInputHandler("StockStream");
48
handler.send(new Object[]{"IBM", 150.0, 1000L});
49

50
// Enable detailed statistics for troubleshooting
51
runtime.enableStats(Level.DETAIL);
52

53
// Disable statistics for production performance
54
runtime.enableStats(Level.OFF);
55
```
56

57
## Statistics Configuration
58

59
### StatisticsConfiguration
60

61
Configuration holder for Siddhi statistics module providing integration with monitoring systems.
62

63
```java { .api }
64
public class StatisticsConfiguration {
65
    // Constructor
66
    public StatisticsConfiguration(StatisticsTrackerFactory factory);
67
    
68
    // Configuration Access
69
    public StatisticsTrackerFactory getFactory();
70
    public String getMetricPrefix();
71
    public void setMetricPrefix(String metricPrefix);
72
}
73
```
74

75
### SiddhiManager Statistics Setup
76

77
```java { .api }
78
public class SiddhiManager {
79
    // Statistics Configuration
80
    public void setStatisticsConfiguration(StatisticsConfiguration statisticsConfiguration);
81
}
82
```
83

84
### Usage Examples
85

86
```java
87
// Create custom statistics factory
88
StatisticsTrackerFactory customFactory = new CustomStatisticsTrackerFactory();
89

90
// Configure statistics
91
StatisticsConfiguration statsConfig = new StatisticsConfiguration(customFactory);
92
statsConfig.setMetricPrefix("siddhi.trading.app");
93

94
// Apply to SiddhiManager
95
SiddhiManager siddhiManager = new SiddhiManager();
96
siddhiManager.setStatisticsConfiguration(statsConfig);
97

98
// All applications created will use this configuration
99
SiddhiAppRuntime runtime = siddhiManager.createSiddhiAppRuntime(tradingApp);
100
runtime.enableStats(Level.BASIC);
101
```
102

103
## Statistics Interfaces
104

105
### StatisticsManager
106

107
Interface for statistics management providing centralized control over metrics collection.
108

109
```java { .api }
110
public interface StatisticsManager {
111
    // Statistics lifecycle
112
    void startReporting();
113
    void stopReporting();
114
    
115
    // Metric registration
116
    void registerStatisticsReporter(StatisticsReporter reporter);
117
    void unregisterStatisticsReporter(StatisticsReporter reporter);
118
    
119
    // Configuration
120
    void setStatisticsConfiguration(StatisticsConfiguration configuration);
121
}
122
```
123

124
### StatisticsTrackerFactory
125

126
Factory for creating statistics trackers for different types of metrics.
127

128
```java { .api }
129
public interface StatisticsTrackerFactory {
130
    // Tracker creation
131
    LatencyTracker createLatencyTracker(String name, StatisticsManager statisticsManager);
132
    ThroughputTracker createThroughputTracker(String name, StatisticsManager statisticsManager);
133
    MemoryUsageTracker createMemoryUsageTracker(String name, StatisticsManager statisticsManager);
134
    BufferedEventsTracker createBufferedEventsTracker(String name, StatisticsManager statisticsManager);
135
}
136
```
137

138
## Performance Tracking
139

140
### LatencyTracker
141

142
Interface for latency tracking measuring processing time and response times.
143

144
```java { .api }
145
public interface LatencyTracker {
146
    // Latency measurement
147
    void markIn();
148
    void markOut();
149
    
150
    // Batch latency tracking
151
    void markIn(long count);
152
    void markOut(long count);
153
    
154
    // Statistics retrieval
155
    double getAverageLatency();
156
    double getMaxLatency();
157
    double getMinLatency();
158
}
159
```
160

161
### ThroughputTracker
162

163
Interface for throughput tracking measuring events processed per unit time.
164

165
```java { .api }
166
public interface ThroughputTracker {
167
    // Event counting
168
    void eventIn();
169
    void eventIn(long count);
170
    
171
    // Throughput measurement
172
    double getThroughput();
173
    long getTotalEvents();
174
    
175
    // Time-based statistics
176
    double getThroughputForLastNSeconds(int seconds);
177
}
178
```
179

180
### Usage Examples
181

182
```java
183
// Custom statistics tracking implementation
184
public class CustomStatisticsTrackerFactory implements StatisticsTrackerFactory {
185
    
186
    @Override
187
    public LatencyTracker createLatencyTracker(String name, StatisticsManager manager) {
188
        return new CustomLatencyTracker(name);
189
    }
190
    
191
    @Override
192
    public ThroughputTracker createThroughputTracker(String name, StatisticsManager manager) {
193
        return new CustomThroughputTracker(name);
194
    }
195
    
196
    // Custom latency tracker with Micrometer integration
197
    private class CustomLatencyTracker implements LatencyTracker {
198
        private final Timer timer;
199
        private Timer.Sample sample;
200
        
201
        public CustomLatencyTracker(String name) {
202
            this.timer = Timer.builder(name + ".latency")
203
                    .description("Processing latency")
204
                    .register(meterRegistry);
205
        }
206
        
207
        @Override
208
        public void markIn() {
209
            this.sample = Timer.start(meterRegistry);
210
        }
211
        
212
        @Override
213
        public void markOut() {
214
            if (sample != null) {
215
                sample.stop(timer);
216
            }
217
        }
218
        
219
        @Override
220
        public double getAverageLatency() {
221
            return timer.mean(TimeUnit.MILLISECONDS);
222
        }
223
    }
224
}
225
```
226

227
## Resource Monitoring
228

229
### MemoryUsageTracker
230

231
Interface for memory usage tracking monitoring resource consumption.
232

233
```java { .api }
234
public interface MemoryUsageTracker {
235
    // Memory measurement
236
    void registerObject(Object object, long size);
237
    void unregisterObject(Object object);
238
    
239
    // Usage statistics
240
    long getCurrentMemoryUsage();
241
    long getMaxMemoryUsage();
242
    
243
    // Reporting
244
    void reportMemoryUsage();
245
}
246
```
247

248
### BufferedEventsTracker
249

250
Interface for buffered events tracking monitoring queue sizes and processing backlogs.
251

252
```java { .api }
253
public interface BufferedEventsTracker {
254
    // Buffer monitoring
255
    void eventBuffered();
256
    void eventRemoved();
257
    void eventBuffered(long count);
258
    void eventRemoved(long count);
259
    
260
    // Buffer statistics
261
    long getCurrentBufferSize();
262
    long getMaxBufferSize();
263
    double getAverageBufferSize();
264
}
265
```
266

267
### MemoryCalculable
268

269
Interface for memory calculation capability enabling objects to report their memory usage.
270

271
```java { .api }
272
public interface MemoryCalculable {
273
    long getSize();
274
}
275
```
276

277
## Advanced Statistics Examples
278

279
### Comprehensive Monitoring Setup
280

281
```java
282
// Complete monitoring setup with multiple trackers
283
public class ComprehensiveMonitoring {
284
    private final SiddhiAppRuntime runtime;
285
    private final LatencyTracker processingLatency;
286
    private final ThroughputTracker inputThroughput;
287
    private final MemoryUsageTracker memoryTracker;
288
    private final BufferedEventsTracker bufferTracker;
289
    
290
    public ComprehensiveMonitoring(SiddhiAppRuntime runtime, StatisticsTrackerFactory factory) {
291
        this.runtime = runtime;
292
        
293
        // Create trackers for different metrics
294
        StatisticsManager statsManager = getStatisticsManager(runtime);
295
        this.processingLatency = factory.createLatencyTracker("processing", statsManager);
296
        this.inputThroughput = factory.createThroughputTracker("input", statsManager);
297
        this.memoryTracker = factory.createMemoryUsageTracker("memory", statsManager);
298
        this.bufferTracker = factory.createBufferedEventsTracker("buffer", statsManager);
299
    }
300
    
301
    public void startMonitoring() {
302
        // Enable detailed statistics
303
        runtime.enableStats(Level.DETAIL);
304
        
305
        // Start periodic reporting
306
        ScheduledExecutorService scheduler = Executors.newScheduledThreadPool(1);
307
        scheduler.scheduleAtFixedRate(this::reportMetrics, 10, 10, TimeUnit.SECONDS);
308
    }
309
    
310
    private void reportMetrics() {
311
        System.out.println("=== Siddhi App Metrics ===");
312
        System.out.println("Processing Latency: " + processingLatency.getAverageLatency() + " ms");
313
        System.out.println("Input Throughput: " + inputThroughput.getThroughput() + " events/sec");
314
        System.out.println("Memory Usage: " + formatBytes(memoryTracker.getCurrentMemoryUsage()));
315
        System.out.println("Buffer Size: " + bufferTracker.getCurrentBufferSize() + " events");
316
        System.out.println("========================");
317
    }
318
    
319
    private String formatBytes(long bytes) {
320
        return String.format("%.2f MB", bytes / (1024.0 * 1024.0));
321
    }
322
}
323
```
324

325
### Performance Alerting
326

327
```java
328
// Performance monitoring with alerting
329
public class PerformanceMonitor extends StreamCallback {
330
    private final ThroughputTracker throughputTracker;
331
    private final LatencyTracker latencyTracker;
332
    private final double throughputThreshold = 1000.0; // events/sec
333
    private final double latencyThreshold = 100.0;     // milliseconds
334
    
335
    @Override
336
    public void receive(Event[] events) {
337
        // Track throughput
338
        throughputTracker.eventIn(events.length);
339
        
340
        // Measure processing latency
341
        latencyTracker.markIn();
342
        processEvents(events);
343
        latencyTracker.markOut();
344
        
345
        // Check performance thresholds
346
        checkPerformanceThresholds();
347
    }
348
    
349
    private void checkPerformanceThresholds() {
350
        double currentThroughput = throughputTracker.getThroughput();
351
        double currentLatency = latencyTracker.getAverageLatency();
352
        
353
        if (currentThroughput < throughputThreshold) {
354
            alertLowThroughput(currentThroughput);
355
        }
356
        
357
        if (currentLatency > latencyThreshold) {
358
            alertHighLatency(currentLatency);
359
        }
360
    }
361
    
362
    private void alertLowThroughput(double throughput) {
363
        System.err.println("ALERT: Low throughput detected: " + throughput + " events/sec");
364
        // Send alert to monitoring system
365
    }
366
    
367
    private void alertHighLatency(double latency) {
368
        System.err.println("ALERT: High latency detected: " + latency + " ms");
369
        // Send alert to monitoring system
370
    }
371
}
372
```
373

374
### Memory Monitoring
375

376
```java
377
// Memory usage monitoring for Siddhi components
378
public class MemoryMonitor {
379
    private final SiddhiAppRuntime runtime;
380
    
381
    public void monitorMemoryUsage() {
382
        // Monitor table memory usage
383
        Collection<Table> tables = runtime.getTables();
384
        long totalTableMemory = 0;
385
        
386
        for (Table table : tables) {
387
            if (table instanceof MemoryCalculable) {
388
                long tableMemory = ((MemoryCalculable) table).getSize();
389
                totalTableMemory += tableMemory;
390
                System.out.println("Table memory: " + formatBytes(tableMemory));
391
            }
392
        }
393
        
394
        System.out.println("Total table memory: " + formatBytes(totalTableMemory));
395
        
396
        // Check memory usage against limits
397
        if (totalTableMemory > getMemoryLimit()) {
398
            triggerMemoryAlert(totalTableMemory);
399
        }
400
    }
401
    
402
    private void triggerMemoryAlert(long memoryUsage) {
403
        System.err.println("MEMORY ALERT: Usage exceeds limit: " + formatBytes(memoryUsage));
404
        
405
        // Trigger data purging or scale-out
406
        triggerDataPurging();
407
    }
408
    
409
    private void triggerDataPurging() {
410
        // Enable purging to free memory
411
        runtime.setPurgingEnabled(true);
412
    }
413
}
414
```
415

416
## Integration Examples
417

418
### Metrics Registry Integration
419

420
```java
421
// Integration with Micrometer metrics registry
422
public class MicrometerStatisticsFactory implements StatisticsTrackerFactory {
423
    private final MeterRegistry meterRegistry;
424
    
425
    public MicrometerStatisticsFactory(MeterRegistry meterRegistry) {
426
        this.meterRegistry = meterRegistry;
427
    }
428
    
429
    @Override
430
    public ThroughputTracker createThroughputTracker(String name, StatisticsManager manager) {
431
        return new MicrometerThroughputTracker(name, meterRegistry);
432
    }
433
    
434
    private static class MicrometerThroughputTracker implements ThroughputTracker {
435
        private final Counter counter;
436
        private final Gauge throughputGauge;
437
        
438
        public MicrometerThroughputTracker(String name, MeterRegistry registry) {
439
            this.counter = Counter.builder(name + ".events")
440
                    .description("Total events processed")
441
                    .register(registry);
442
            
443
            this.throughputGauge = Gauge.builder(name + ".throughput")
444
                    .description("Events per second")
445
                    .register(registry, this, MicrometerThroughputTracker::calculateThroughput);
446
        }
447
        
448
        @Override
449
        public void eventIn() {
450
            counter.increment();
451
        }
452
        
453
        @Override
454
        public double getThroughput() {
455
            return calculateThroughput();
456
        }
457
        
458
        private double calculateThroughput() {
459
            // Calculate throughput based on counter and time
460
            return counter.count() / getUptimeSeconds();
461
        }
462
    }
463
}
464
```
465

466
## Types
467

468
```java { .api }
469
public interface StatisticsReporter {
470
    void report(Map<String, Object> metrics);
471
    void start();
472
    void stop();
473
}
474

475
public interface StatisticsManager {
476
    void registerTracker(String name, Object tracker);
477
    void unregisterTracker(String name);
478
    Map<String, Object> getAllMetrics();
479
}
480
```