Monitoring and Profiling

/**
 * Listener interface for Graal Truffle runtime events
 * Implement to monitor compilation, optimization, and performance events
 */
public interface GraalTruffleRuntimeListener {
    /**
     * Called when a call target is queued for compilation
     * @param callTarget The call target being queued
     */
    default void onCompilationQueued(OptimizedCallTarget callTarget) {}
    
    /**
     * Called when compilation starts for a call target
     * @param callTarget The call target being compiled
     */
    default void onCompilationStarted(OptimizedCallTarget callTarget) {}
    
    /**
     * Called when the Truffle tier compilation finishes
     * @param callTarget The compiled call target
     * @param context Compilation context information
     * @param graph Intermediate representation graph
     */
    default void onCompilationTruffleTierFinished(
        OptimizedCallTarget callTarget, 
        TruffleTierContext context, 
        GraphInfo graph) {}
    
    /**
     * Called when the Graal tier compilation finishes
     * @param callTarget The compiled call target
     * @param graph Final optimized graph
     */
    default void onCompilationGraalTierFinished(
        OptimizedCallTarget callTarget, 
        GraphInfo graph) {}
    
    /**
     * Called when compilation succeeds
     * @param callTarget The successfully compiled call target
     * @param context Compilation context
     * @param graph Final graph information
     * @param info Compilation result information
     * @param tier Compilation tier (1 or 2)
     */
    default void onCompilationSuccess(
        OptimizedCallTarget callTarget,
        TruffleTierContext context,
        GraphInfo graph,
        CompilationResultInfo info,
        int tier) {}
    
    /**
     * Called when compilation fails
     * @param callTarget The call target that failed to compile
     * @param reason Reason for compilation failure
     * @param bailout True if this was a bailout (not an error)
     * @param permanentBailout True if this is a permanent failure
     * @param tier Compilation tier that failed
     */
    default void onCompilationFailed(
        OptimizedCallTarget callTarget,
        String reason,
        boolean bailout,
        boolean permanentBailout,
        int tier) {}
    
    /**
     * Called when a call target is invalidated
     * @param callTarget The invalidated call target
     * @param source Source of invalidation
     * @param reason Reason for invalidation
     */
    default void onCompilationInvalidated(
        OptimizedCallTarget callTarget,
        Object source,
        CharSequence reason) {}
    
    /**
     * Called when a deoptimization occurs
     * @param callTarget The call target being deoptimized
     * @param frame Frame at deoptimization point
     * @param reason Reason for deoptimization
     */
    default void onCompilationDeoptimized(
        OptimizedCallTarget callTarget,
        Frame frame,
        String reason) {}
}

public class MyRuntimeListener implements GraalTruffleRuntimeListener {
    
    @Override
    public void onCompilationQueued(OptimizedCallTarget callTarget) {
        System.out.println("Queued for compilation: " + callTarget.getName());
    }
    
    @Override
    public void onCompilationSuccess(
        OptimizedCallTarget callTarget,
        TruffleTierContext context,
        GraphInfo graph,
        CompilationResultInfo info,
        int tier) {
        System.out.printf("Compiled %s in %d ms (tier %d)%n", 
            callTarget.getName(), info.getCompilationTime(), tier);
    }
    
    @Override
    public void onCompilationFailed(
        OptimizedCallTarget callTarget,
        String reason,
        boolean bailout,
        boolean permanentBailout,
        int tier) {
        System.err.printf("Compilation failed for %s: %s%n", 
            callTarget.getName(), reason);
    }
}

// Register the listener
GraalTruffleRuntime runtime = GraalTruffleRuntime.getRuntime();
runtime.addListener(new MyRuntimeListener());

/**
 * Factory for creating JFR events related to Truffle runtime
 */
public abstract class EventFactory {
    /** Returns the singleton event factory instance */
    public static EventFactory getInstance();
    
    /** Creates a compilation event */
    public abstract CompilationEvent createCompilationEvent();
    
    /** Creates a compilation failure event */
    public abstract CompilationFailureEvent createCompilationFailureEvent();
    
    /** Creates a deoptimization event */
    public abstract DeoptimizationEvent createDeoptimizationEvent();
    
    /** Creates an invalidation event */
    public abstract InvalidationEvent createInvalidationEvent();
    
    /**
     * Service provider interface for event factory implementations
     */
    public interface Provider {
        EventFactory create();
        int getPriority();
    }
}

/**
 * JFR event for compilation activities
 */
public abstract class CompilationEvent {
    /** Sets the compiled call target */
    public abstract void setTarget(OptimizedCallTarget target);
    
    /** Sets compilation time in nanoseconds */
    public abstract void setCompilationTime(long timeNanos);
    
    /** Sets the compilation tier */
    public abstract void setTier(int tier);
    
    /** Sets whether compilation was successful */
    public abstract void setSuccess(boolean success);
    
    /** Sets the number of nodes in compiled code */
    public abstract void setNodeCount(int nodeCount);
    
    /** Sets the size of generated code */
    public abstract void setCodeSize(int codeSize);
    
    /** Commits the event to the JFR recording */
    public abstract void commit();
}

/**
 * JFR event for compilation failures
 */
public abstract class CompilationFailureEvent {
    /** Sets the call target that failed to compile */
    public abstract void setTarget(OptimizedCallTarget target);
    
    /** Sets the failure reason */
    public abstract void setReason(String reason);
    
    /** Sets whether this was a bailout */
    public abstract void setBailout(boolean bailout);
    
    /** Sets whether this is a permanent failure */
    public abstract void setPermanentBailout(boolean permanent);
    
    /** Sets the compilation tier that failed */
    public abstract void setTier(int tier);
    
    /** Commits the event */
    public abstract void commit();
}

/**
 * JFR event for deoptimization occurrences
 */
public abstract class DeoptimizationEvent {
    /** Sets the deoptimized call target */
    public abstract void setTarget(OptimizedCallTarget target);
    
    /** Sets the deoptimization reason */
    public abstract void setReason(String reason);
    
    /** Sets the source location of deoptimization */
    public abstract void setSourceLocation(String location);
    
    /** Commits the event */
    public abstract void commit();
}

// JFR events are automatically created by the runtime
// Enable JFR recording to capture these events:

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

// Or programmatically:
import jdk.jfr.Recording;
import jdk.jfr.Configuration;

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

// Run your Truffle application...

recording.stop();
recording.dump(Paths.get("truffle-profile.jfr"));

/**
 * High-performance logger for Truffle runtime
 * Designed to minimize overhead in performance-critical code
 */
public final class TruffleLogger {
    /** Creates a logger for the specified name */
    public static TruffleLogger getLogger(String name);
    
    /** Creates a logger for the specified class */
    public static TruffleLogger getLogger(Class<?> clazz);
    
    /** Logs a message at SEVERE level */
    public void severe(String message);
    
    /** Logs a message at WARNING level */
    public void warning(String message);
    
    /** Logs a message at INFO level */
    public void info(String message);
    
    /** Logs a message at CONFIG level */
    public void config(String message);
    
    /** Logs a message at FINE level */
    public void fine(String message);
    
    /** Logs a message at FINER level */
    public void finer(String message);
    
    /** Logs a message at FINEST level */
    public void finest(String message);
    
    /** Logs a message with specified level and parameters */
    public void log(Level level, String message, Object... parameters);
    
    /** Logs an exception with message */
    public void log(Level level, String message, Throwable thrown);
    
    /** Checks if a level is enabled (for performance) */
    public boolean isLoggable(Level level);
    
    /** Returns the logger name */
    public String getName();
    
    /** Sets the logger level */
    public void setLevel(Level level);
    
    /** Gets the current logger level */
    public Level getLevel();
}

/**
 * Provider for Truffle logger implementations
 */
public abstract class TruffleLoggerProvider {
    /** Creates a logger for the given name */
    public abstract TruffleLogger createLogger(String name);
    
    /** Returns provider priority (higher wins) */
    public int getPriority() {
        return 0;
    }
}

public class MyLanguageNode extends Node {
    private static final TruffleLogger LOGGER = 
        TruffleLogger.getLogger(MyLanguageNode.class);
    
    public Object execute(VirtualFrame frame) {
        if (LOGGER.isLoggable(Level.FINE)) {
            LOGGER.fine("Executing node: " + getClass().getSimpleName());
        }
        
        try {
            return performExecution(frame);
        } catch (Exception e) {
            LOGGER.log(Level.SEVERE, "Execution failed", e);
            throw e;
        }
    }
}

// Configure logging levels through system properties:
// -Dcom.oracle.truffle.runtime.level=FINE

/**
 * Debug utilities for runtime diagnostics
 */
public final class Debug {
    /** Checks if debugging is enabled */
    public static boolean isEnabled();
    
    /** Prints debug information about a call target */
    public static void dump(OptimizedCallTarget callTarget);
    
    /** Prints compilation statistics */
    public static void printCompilationStatistics();
    
    /** Prints current runtime options */
    public static void printRuntimeOptions();
    
    /** Returns debug information as string */
    public static String getDebugInfo(OptimizedCallTarget callTarget);
    
    /** Forces garbage collection of optimized code */
    public static void clearCompiledCode();
    
    /** Returns memory usage statistics */
    public static MemoryStatistics getMemoryStatistics();
}

/**
 * Memory usage statistics
 */
public interface MemoryStatistics {
    /** Returns bytes used by compiled code */
    long getCompiledCodeSize();
    
    /** Returns number of compiled call targets */
    int getCompiledCallTargetCount();
    
    /** Returns bytes used by compilation metadata */
    long getCompilationMetadataSize();
    
    /** Returns total runtime memory usage */
    long getTotalRuntimeMemory();
}

// Enable debug mode with system property:
// -Dtruffle.debug=true

if (Debug.isEnabled()) {
    Debug.dump(callTarget);
    Debug.printCompilationStatistics();
    
    MemoryStatistics stats = Debug.getMemoryStatistics();
    System.out.printf("Compiled code: %d bytes, %d targets%n",
        stats.getCompiledCodeSize(),
        stats.getCompiledCallTargetCount());
}

public interface TruffleTierContext {
    /** Returns the call target being compiled */
    OptimizedCallTarget getCallTarget();
    
    /** Returns compilation options */
    Map<String, Object> getOptions();
    
    /** Returns compilation tier */
    int getTier();
}

public interface GraphInfo {
    /** Returns the number of nodes in the graph */
    int getNodeCount();
    
    /** Returns graph complexity metric */
    double getComplexity();
    
    /** Returns compilation time for this graph */
    long getCompilationTime();
}

public interface CompilationResultInfo {
    /** Returns the compilation time in nanoseconds */
    long getCompilationTime();
    
    /** Returns the size of generated code */
    int getCodeSize();
    
    /** Returns the number of inlined call sites */
    int getInlinedCallSites();
    
    /** Returns optimization statistics */
    Map<String, Integer> getOptimizationStatistics();
}

public enum Level {
    SEVERE(1000),
    WARNING(900),
    INFO(800),
    CONFIG(700),
    FINE(500),
    FINER(400),
    FINEST(300);
    
    /** Returns the numeric level value */
    public int intValue();
    
    /** Returns the level name */
    public String getName();
}