0
# Monitoring and Profiling
1

2
Comprehensive monitoring capabilities including Java Flight Recorder integration, performance event tracking, runtime listeners, and logging infrastructure.
3

4
## Capabilities
5

6
### GraalTruffleRuntimeListener
7

8
Event listener interface for monitoring runtime compilation and execution events.
9

10
```java { .api }
11
/**
12
 * Listener interface for Graal Truffle runtime events
13
 * Implement to monitor compilation, optimization, and performance events
14
 */
15
public interface GraalTruffleRuntimeListener {
16
    /**
17
     * Called when a call target is queued for compilation
18
     * @param callTarget The call target being queued
19
     */
20
    default void onCompilationQueued(OptimizedCallTarget callTarget) {}
21
    
22
    /**
23
     * Called when compilation starts for a call target
24
     * @param callTarget The call target being compiled
25
     */
26
    default void onCompilationStarted(OptimizedCallTarget callTarget) {}
27
    
28
    /**
29
     * Called when the Truffle tier compilation finishes
30
     * @param callTarget The compiled call target
31
     * @param context Compilation context information
32
     * @param graph Intermediate representation graph
33
     */
34
    default void onCompilationTruffleTierFinished(
35
        OptimizedCallTarget callTarget, 
36
        TruffleTierContext context, 
37
        GraphInfo graph) {}
38
    
39
    /**
40
     * Called when the Graal tier compilation finishes
41
     * @param callTarget The compiled call target
42
     * @param graph Final optimized graph
43
     */
44
    default void onCompilationGraalTierFinished(
45
        OptimizedCallTarget callTarget, 
46
        GraphInfo graph) {}
47
    
48
    /**
49
     * Called when compilation succeeds
50
     * @param callTarget The successfully compiled call target
51
     * @param context Compilation context
52
     * @param graph Final graph information
53
     * @param info Compilation result information
54
     * @param tier Compilation tier (1 or 2)
55
     */
56
    default void onCompilationSuccess(
57
        OptimizedCallTarget callTarget,
58
        TruffleTierContext context,
59
        GraphInfo graph,
60
        CompilationResultInfo info,
61
        int tier) {}
62
    
63
    /**
64
     * Called when compilation fails
65
     * @param callTarget The call target that failed to compile
66
     * @param reason Reason for compilation failure
67
     * @param bailout True if this was a bailout (not an error)
68
     * @param permanentBailout True if this is a permanent failure
69
     * @param tier Compilation tier that failed
70
     */
71
    default void onCompilationFailed(
72
        OptimizedCallTarget callTarget,
73
        String reason,
74
        boolean bailout,
75
        boolean permanentBailout,
76
        int tier) {}
77
    
78
    /**
79
     * Called when a call target is invalidated
80
     * @param callTarget The invalidated call target
81
     * @param source Source of invalidation
82
     * @param reason Reason for invalidation
83
     */
84
    default void onCompilationInvalidated(
85
        OptimizedCallTarget callTarget,
86
        Object source,
87
        CharSequence reason) {}
88
    
89
    /**
90
     * Called when a deoptimization occurs
91
     * @param callTarget The call target being deoptimized
92
     * @param frame Frame at deoptimization point
93
     * @param reason Reason for deoptimization
94
     */
95
    default void onCompilationDeoptimized(
96
        OptimizedCallTarget callTarget,
97
        Frame frame,
98
        String reason) {}
99
}
100
```
101

102
**Usage Examples:**
103

104
```java
105
public class MyRuntimeListener implements GraalTruffleRuntimeListener {
106
    
107
    @Override
108
    public void onCompilationQueued(OptimizedCallTarget callTarget) {
109
        System.out.println("Queued for compilation: " + callTarget.getName());
110
    }
111
    
112
    @Override
113
    public void onCompilationSuccess(
114
        OptimizedCallTarget callTarget,
115
        TruffleTierContext context,
116
        GraphInfo graph,
117
        CompilationResultInfo info,
118
        int tier) {
119
        System.out.printf("Compiled %s in %d ms (tier %d)%n", 
120
            callTarget.getName(), info.getCompilationTime(), tier);
121
    }
122
    
123
    @Override
124
    public void onCompilationFailed(
125
        OptimizedCallTarget callTarget,
126
        String reason,
127
        boolean bailout,
128
        boolean permanentBailout,
129
        int tier) {
130
        System.err.printf("Compilation failed for %s: %s%n", 
131
            callTarget.getName(), reason);
132
    }
133
}
134

135
// Register the listener
136
GraalTruffleRuntime runtime = GraalTruffleRuntime.getRuntime();
137
runtime.addListener(new MyRuntimeListener());
138
```
139

140
### Java Flight Recorder Integration
141

142
Built-in JFR events for comprehensive performance monitoring and profiling.
143

144
```java { .api }
145
/**
146
 * Factory for creating JFR events related to Truffle runtime
147
 */
148
public abstract class EventFactory {
149
    /** Returns the singleton event factory instance */
150
    public static EventFactory getInstance();
151
    
152
    /** Creates a compilation event */
153
    public abstract CompilationEvent createCompilationEvent();
154
    
155
    /** Creates a compilation failure event */
156
    public abstract CompilationFailureEvent createCompilationFailureEvent();
157
    
158
    /** Creates a deoptimization event */
159
    public abstract DeoptimizationEvent createDeoptimizationEvent();
160
    
161
    /** Creates an invalidation event */
162
    public abstract InvalidationEvent createInvalidationEvent();
163
    
164
    /**
165
     * Service provider interface for event factory implementations
166
     */
167
    public interface Provider {
168
        EventFactory create();
169
        int getPriority();
170
    }
171
}
172

173
/**
174
 * JFR event for compilation activities
175
 */
176
public abstract class CompilationEvent {
177
    /** Sets the compiled call target */
178
    public abstract void setTarget(OptimizedCallTarget target);
179
    
180
    /** Sets compilation time in nanoseconds */
181
    public abstract void setCompilationTime(long timeNanos);
182
    
183
    /** Sets the compilation tier */
184
    public abstract void setTier(int tier);
185
    
186
    /** Sets whether compilation was successful */
187
    public abstract void setSuccess(boolean success);
188
    
189
    /** Sets the number of nodes in compiled code */
190
    public abstract void setNodeCount(int nodeCount);
191
    
192
    /** Sets the size of generated code */
193
    public abstract void setCodeSize(int codeSize);
194
    
195
    /** Commits the event to the JFR recording */
196
    public abstract void commit();
197
}
198

199
/**
200
 * JFR event for compilation failures
201
 */
202
public abstract class CompilationFailureEvent {
203
    /** Sets the call target that failed to compile */
204
    public abstract void setTarget(OptimizedCallTarget target);
205
    
206
    /** Sets the failure reason */
207
    public abstract void setReason(String reason);
208
    
209
    /** Sets whether this was a bailout */
210
    public abstract void setBailout(boolean bailout);
211
    
212
    /** Sets whether this is a permanent failure */
213
    public abstract void setPermanentBailout(boolean permanent);
214
    
215
    /** Sets the compilation tier that failed */
216
    public abstract void setTier(int tier);
217
    
218
    /** Commits the event */
219
    public abstract void commit();
220
}
221

222
/**
223
 * JFR event for deoptimization occurrences
224
 */
225
public abstract class DeoptimizationEvent {
226
    /** Sets the deoptimized call target */
227
    public abstract void setTarget(OptimizedCallTarget target);
228
    
229
    /** Sets the deoptimization reason */
230
    public abstract void setReason(String reason);
231
    
232
    /** Sets the source location of deoptimization */
233
    public abstract void setSourceLocation(String location);
234
    
235
    /** Commits the event */
236
    public abstract void commit();
237
}
238
```
239

240
**Usage Examples:**
241

242
```java
243
// JFR events are automatically created by the runtime
244
// Enable JFR recording to capture these events:
245

246
// Command line:
247
// -XX:+FlightRecorder -XX:StartFlightRecording=duration=60s,filename=truffle.jfr
248

249
// Or programmatically:
250
import jdk.jfr.Recording;
251
import jdk.jfr.Configuration;
252

253
Recording recording = new Recording(Configuration.getConfiguration("profile"));
254
recording.enable("com.oracle.truffle.runtime.CompilationEvent");
255
recording.enable("com.oracle.truffle.runtime.DeoptimizationEvent");
256
recording.start();
257

258
// Run your Truffle application...
259

260
recording.stop();
261
recording.dump(Paths.get("truffle-profile.jfr"));
262
```
263

264
### TruffleLogger
265

266
High-performance logging infrastructure optimized for runtime environments.
267

268
```java { .api }
269
/**
270
 * High-performance logger for Truffle runtime
271
 * Designed to minimize overhead in performance-critical code
272
 */
273
public final class TruffleLogger {
274
    /** Creates a logger for the specified name */
275
    public static TruffleLogger getLogger(String name);
276
    
277
    /** Creates a logger for the specified class */
278
    public static TruffleLogger getLogger(Class<?> clazz);
279
    
280
    /** Logs a message at SEVERE level */
281
    public void severe(String message);
282
    
283
    /** Logs a message at WARNING level */
284
    public void warning(String message);
285
    
286
    /** Logs a message at INFO level */
287
    public void info(String message);
288
    
289
    /** Logs a message at CONFIG level */
290
    public void config(String message);
291
    
292
    /** Logs a message at FINE level */
293
    public void fine(String message);
294
    
295
    /** Logs a message at FINER level */
296
    public void finer(String message);
297
    
298
    /** Logs a message at FINEST level */
299
    public void finest(String message);
300
    
301
    /** Logs a message with specified level and parameters */
302
    public void log(Level level, String message, Object... parameters);
303
    
304
    /** Logs an exception with message */
305
    public void log(Level level, String message, Throwable thrown);
306
    
307
    /** Checks if a level is enabled (for performance) */
308
    public boolean isLoggable(Level level);
309
    
310
    /** Returns the logger name */
311
    public String getName();
312
    
313
    /** Sets the logger level */
314
    public void setLevel(Level level);
315
    
316
    /** Gets the current logger level */
317
    public Level getLevel();
318
}
319

320
/**
321
 * Provider for Truffle logger implementations
322
 */
323
public abstract class TruffleLoggerProvider {
324
    /** Creates a logger for the given name */
325
    public abstract TruffleLogger createLogger(String name);
326
    
327
    /** Returns provider priority (higher wins) */
328
    public int getPriority() {
329
        return 0;
330
    }
331
}
332
```
333

334
**Usage Examples:**
335

336
```java
337
public class MyLanguageNode extends Node {
338
    private static final TruffleLogger LOGGER = 
339
        TruffleLogger.getLogger(MyLanguageNode.class);
340
    
341
    public Object execute(VirtualFrame frame) {
342
        if (LOGGER.isLoggable(Level.FINE)) {
343
            LOGGER.fine("Executing node: " + getClass().getSimpleName());
344
        }
345
        
346
        try {
347
            return performExecution(frame);
348
        } catch (Exception e) {
349
            LOGGER.log(Level.SEVERE, "Execution failed", e);
350
            throw e;
351
        }
352
    }
353
}
354

355
// Configure logging levels through system properties:
356
// -Dcom.oracle.truffle.runtime.level=FINE
357
```
358

359
### Debug Utilities
360

361
Runtime debugging and diagnostic utilities.
362

363
```java { .api }
364
/**
365
 * Debug utilities for runtime diagnostics
366
 */
367
public final class Debug {
368
    /** Checks if debugging is enabled */
369
    public static boolean isEnabled();
370
    
371
    /** Prints debug information about a call target */
372
    public static void dump(OptimizedCallTarget callTarget);
373
    
374
    /** Prints compilation statistics */
375
    public static void printCompilationStatistics();
376
    
377
    /** Prints current runtime options */
378
    public static void printRuntimeOptions();
379
    
380
    /** Returns debug information as string */
381
    public static String getDebugInfo(OptimizedCallTarget callTarget);
382
    
383
    /** Forces garbage collection of optimized code */
384
    public static void clearCompiledCode();
385
    
386
    /** Returns memory usage statistics */
387
    public static MemoryStatistics getMemoryStatistics();
388
}
389

390
/**
391
 * Memory usage statistics
392
 */
393
public interface MemoryStatistics {
394
    /** Returns bytes used by compiled code */
395
    long getCompiledCodeSize();
396
    
397
    /** Returns number of compiled call targets */
398
    int getCompiledCallTargetCount();
399
    
400
    /** Returns bytes used by compilation metadata */
401
    long getCompilationMetadataSize();
402
    
403
    /** Returns total runtime memory usage */
404
    long getTotalRuntimeMemory();
405
}
406
```
407

408
**Usage Examples:**
409

410
```java
411
// Enable debug mode with system property:
412
// -Dtruffle.debug=true
413

414
if (Debug.isEnabled()) {
415
    Debug.dump(callTarget);
416
    Debug.printCompilationStatistics();
417
    
418
    MemoryStatistics stats = Debug.getMemoryStatistics();
419
    System.out.printf("Compiled code: %d bytes, %d targets%n",
420
        stats.getCompiledCodeSize(),
421
        stats.getCompiledCallTargetCount());
422
}
423
```
424

425
## Common Types
426

427
```java { .api }
428
public interface TruffleTierContext {
429
    /** Returns the call target being compiled */
430
    OptimizedCallTarget getCallTarget();
431
    
432
    /** Returns compilation options */
433
    Map<String, Object> getOptions();
434
    
435
    /** Returns compilation tier */
436
    int getTier();
437
}
438

439
public interface GraphInfo {
440
    /** Returns the number of nodes in the graph */
441
    int getNodeCount();
442
    
443
    /** Returns graph complexity metric */
444
    double getComplexity();
445
    
446
    /** Returns compilation time for this graph */
447
    long getCompilationTime();
448
}
449

450
public interface CompilationResultInfo {
451
    /** Returns the compilation time in nanoseconds */
452
    long getCompilationTime();
453
    
454
    /** Returns the size of generated code */
455
    int getCodeSize();
456
    
457
    /** Returns the number of inlined call sites */
458
    int getInlinedCallSites();
459
    
460
    /** Returns optimization statistics */
461
    Map<String, Integer> getOptimizationStatistics();
462
}
463

464
public enum Level {
465
    SEVERE(1000),
466
    WARNING(900),
467
    INFO(800),
468
    CONFIG(700),
469
    FINE(500),
470
    FINER(400),
471
    FINEST(300);
472
    
473
    /** Returns the numeric level value */
474
    public int intValue();
475
    
476
    /** Returns the level name */
477
    public String getName();
478
}
479
```