addedInput schema / properties / recordingConfig
Added value: +{
+ "description": "What to record in this session. Every key is optional and omitted keys keep their defaults - set only the keys this analysis needs, such as recordMonitors for lock contention analysis, recordAllocations for allocation sites, triggers for automatic captures during the recording, or advanced.methodCallRecordingType instrumentation when invocation counts are needed.",
+ "properties": {
+ "advanced": {
+ "description": "Settings that are off by default. Only change them for a concrete reason, never speculatively - more data is not better, and a wrong value can silently lose data. Valid reasons are e.g. check_status reporting possibleInlineAsyncTypes, an application that hands work to thread pools, coroutines or event dispatch threads, an analysis that needs invocation counts, or a previous recording showing that the default filters hide relevant code. The keys without a description correspond to session configuration attributes (such as splittingCap for the call tree split cap mentioned in capped_split warnings) and are documented in the resource jprofiler://config/session.",
+ "properties": {
+ "allocTreeRecordingType": {
+ "enum": [
+ "live",
+ "liveAndGcNoClassResolution",
+ "liveAndGc"
+ ],
+ "type": "string"
+ },
+ "allocationSamplingInterval": {
+ "type": "integer"
+ },
+ "annotateCustomPayloads": {
+ "type": "boolean"
+ },
+ "asyncBufferPercentage": {
+ "type": "integer"
+ },
+ "asyncNativeSampling": {
+ "type": "boolean"
+ },
+ "asyncThreadResolution": {
+ "type": "boolean"
+ },
+ "complexityMethods": {
+ "description": "Measure how the invocation time of the given methods scales with an input size computed per invocation by a script: the complexity.methods dataset then holds the recorded (input size, time) points and curve fits, answering questions like 'is this method O(n^2) in the payload size'. This is the second step after performance.hotspots has identified a suspicious method whose inputs vary in size - re-record with this setting pointing at that method. Example: [{\"method\": \"com.example.Service.process(java.util.List)\", \"script\": \"return param0.size();\"}]. Works with any methodCallRecordingType. Recording starts with the session and stops before the snapshot is saved; bound the measurement window with startRecording/stopRecording actions (\"complexity\": true) in triggers or attached_action. The script API is documented in the jprofiler://api/method-scripts resource.",
+ "items": {
+ "properties": {
+ "method": {
+ "description": "The method whose scaling is measured, in the format com.foo.Bar.method(long, java.lang.String), with () for no parameters. The method does not have to match the package filter.",
+ "type": "string"
+ },
+ "script": {
+ "description": "Java code returning the input size of the invocation as a long, for example 'return param0.size();' for a collection parameter. Same environment as 'splitMethods' scripts (scriptContext, clazz, currentObject, param0, param1, ...).",
+ "type": "string"
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "descriptorCap": {
+ "type": "integer"
+ },
+ "exactSamplingMonitorCallStacks": {
+ "type": "boolean"
+ },
+ "exceptionalCap": {
+ "type": "integer"
+ },
+ "exceptionalMethods": {
+ "description": "Methods whose slowest invocations are kept as separate, individually expandable nodes in performance.callTree (marked with exceptionalRun) instead of being merged into the average. Use after performance.outliers shows a method whose maxMicros deviates strongly from its avgMicros. Format: com.foo.Bar.method(long, java.lang.String), exactly as printed in the method field of performance.outliers; the argument list is required, use () for no parameters. Requires methodCallRecordingType 'instrumentation'. Not recorded for virtual threads.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "exceptionalTimeType": {
+ "enum": [
+ "all",
+ "running",
+ "waiting",
+ "blocking",
+ "netio"
+ ],
+ "type": "string"
+ },
+ "filter": {
+ "description": "Comma-separated list of project packages to profile (e.g. 'com.example.app,org.service'). A wrong package silently excludes relevant code from the recording.",
+ "type": "string"
+ },
+ "hotspotPayloadCap": {
+ "type": "integer"
+ },
+ "inlineAsyncTypes": {
+ "description": "Record async request tracking for the given types, one or more of executor, kotlin_coroutines, awt, swt, virtual_thread, platform_thread. Async executions are then inlined under their call sites in the call tree and hotspot datasets. Off by default because tracking adds overhead - enable when analyzing applications that hand work to thread pools, coroutines or event dispatch threads, or when check_status reports possibleInlineAsyncTypes after a previous recording.",
+ "items": {
+ "enum": [
+ "executor",
+ "kotlin_coroutines",
+ "awt",
+ "swt",
+ "virtual_thread",
+ "platform_thread"
+ ],
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "instrumentNativeMethods": {
+ "type": "boolean"
+ },
+ "internalExcludes": {
+ "type": "boolean"
+ },
+ "libraryDebugParameters": {
+ "type": "string"
+ },
+ "lineNumbers": {
+ "type": "boolean"
+ },
+ "methodCallRecordingType": {
+ "description": "How CPU method calls are recorded. 'sampling' (default) takes periodic call stack samples: very low overhead that does not depend on the package filter, accurate times, but no invocation counts, and methods shorter than the sampling period or called rarely can be missed. 'instrumentation' modifies the bytecode of profiled classes to track method entry and exit: the only mode with exact invocation counts (the count field in the performance datasets) and reliable timing of small, frequently called methods, and it makes allocation stack traces exact; the cost is high overhead and distorted CPU times in CPU-bound code, so it requires a package filter (filter in this object) that restricts instrumentation to the relevant packages. 'async_sampling' samples asynchronously without safepoint bias: the most accurate CPU times for highly multithreaded CPU-bound code, but only on macOS and Linux with a HotSpot JVM (otherwise the agent falls back to sampling), no wall clock times (threadStatus all has no effect) and no invocation counts. Use instrumentation when the analysis needs call counts, otherwise keep the default.",
+ "enum": [
+ "instrumentation",
+ "sampling",
+ "async_sampling"
+ ],
+ "type": "string"
+ },
+ "payloadCap": {
+ "type": "integer"
+ },
+ "probeConfig": {
+ "additionalProperties": {
+ "type": "object"
+ },
+ "description": "Probe-specific settings: a map of subsystem name to a map of attribute name to value, applied to the probe configuration of the recording. Examples: {\"jdbc\": {\"preparedStatementParameters\": true}} records prepared statement parameters in the jdbc hotspots, {\"http_server\": {\"split\": false}} disables URL call tree splitting of the HTTP server probe, {\"http_server\": {\"splitType\": \"script\", \"requestResolvers\": [\"...\"]}} splits the call tree by script-computed request names. Custom probes of the profiled application use the key \"custom:<fully qualified probe class name>\" with the attributes \"events\" (record individual events for the probe.events dataset) and \"injected\" (prepare_profiling and attach pass the probe discovery VM parameter), e.g. {\"custom:com.example.MyProbe\": {\"events\": true, \"injected\": true}} - unknown attributes of custom probes are errors. Script probes defined in 'scriptProbes' use the key \"script:<name>\" with the attribute \"events\". Attribute names and values are those of the JProfiler session configuration, the reference with all attributes of all probes is the resource jprofiler://config/probes. Unknown attributes are silently ignored, the applied settings are reported as probeSettings in check_status.",
+ "type": "object"
+ },
+ "probeFileMBCap": {
+ "type": "integer"
+ },
+ "recordArrayAlloc": {
+ "type": "boolean"
+ },
+ "retainStackForHotspotConsolidation": {
+ "type": "boolean"
+ },
+ "sampleUnmountedVirtualThreads": {
+ "type": "boolean"
+ },
+ "samplingFrequency": {
+ "type": "integer"
+ },
+ "samplingNoFilters": {
+ "type": "boolean"
+ },
+ "samplingPayloadCallStacks": {
+ "type": "boolean"
+ },
+ "scriptClassPath": {
+ "description": "Additional compile classpath for all scripts in this object ('splitMethods', 'complexityMethods' and script properties in 'probeConfig'): absolute paths to JAR files, to directories containing JAR files, or wildcard patterns like /path/to/lib/*.jar. Only needed when a script references classes beyond the JDK and the JProfiler classes, typically application classes. Used for compilation on this machine only - at runtime the classes must be present in the profiled JVM, which is normally the case for application classes.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "scriptProbes": {
+ "description": "Define script probes: lightweight probes declared as scripts, compiled by this server and pushed to the profiled JVM - no code, build or deployment in the profiled application, works on attach. Each probe intercepts the given methods, the script computes the payload string per invocation. Defining a script probe records it: it appears as subsystem 'script:<name>' with payload hot spots in performance.hotspots/callTree; individual events are recorded with 'probeConfig': {\"script:<name>\": {\"events\": true}}. Example: [{\"name\": \"Order processing\", \"methods\": [{\"method\": \"com.example.Shop.processOrder(int)\", \"script\": \"return \\\"order \\\" + param0;\"}]}]. Script probes cannot split the call tree, access return values or create control objects, custom event types or telemetries - for those write a custom probe, see jprofiler://probes/custom. The script API is documented in the jprofiler://api/method-scripts resource.",
+ "items": {
+ "properties": {
+ "annotatePayloads": {
+ "description": "Optional: annotate the CPU call tree with the payload strings. Default false.",
+ "type": "boolean"
+ },
+ "description": {
+ "description": "Optional explanation of the probe's purpose.",
+ "type": "string"
+ },
+ "methods": {
+ "items": {
+ "properties": {
+ "method": {
+ "description": "The intercepted method, in the format com.foo.Bar.method(long, java.lang.String), with () for no parameters. The method does not have to match the package filter.",
+ "type": "string"
+ },
+ "script": {
+ "description": "Java code returning the payload string for the invocation, or null for no payload. Same environment as 'splitMethods' scripts (scriptContext, clazz, currentObject, param0, param1, ...).",
+ "type": "string"
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "name": {
+ "description": "The probe name. The probe is recorded as subsystem 'script:<name>'.",
+ "type": "string"
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "splitMethods": {
+ "description": "Split the call tree below the given methods by a script-computed key: each distinct returned string gets its own subtree (type method_split in performance.callTree), for example to analyze request handling per message type. Example: [{\"method\": \"com.example.Handler.onMessage(javax.jms.Message)\", \"script\": \"return param0.getJMSType();\"}]. Works with any methodCallRecordingType. The script runs on every invocation of the method, so do not split extremely hot methods. The number of distinct keys per split location is capped ('splittingCap', see jprofiler://config/session), further keys are merged into a capped_split node. The script API is documented in the jprofiler://api/method-scripts resource.",
+ "items": {
+ "properties": {
+ "method": {
+ "description": "The method below which the call tree is split, in the format com.foo.Bar.method(long, java.lang.String), with () for no parameters. The method does not have to match the package filter.",
+ "type": "string"
+ },
+ "script": {
+ "description": "Java code returning the split key string, or null to leave the invocation unsplit. Available parameters: scriptContext (com.jprofiler.api.agent.ScriptContext, stores per-script state with putObject/getObject and putLong/getLong), clazz (the Class of the declaring class), currentObject (the instance the method is invoked on, null for static methods), param0, param1, ... (the declared method parameters in order). Parameters are statically typed when their class is on the compile classpath and Object otherwise - add application JARs with 'scriptClassPath' to get static typing.",
+ "type": "string"
+ }
+ },
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "splittingCap": {
+ "type": "integer"
+ },
+ "utilConcurrentHandling": {
+ "type": "boolean"
+ }
+ },
+ "type": "object"
+ },
+ "blockingThresholdMicros": {
+ "description": "Optional minimum duration in microseconds for blocked monitor events when 'recordMonitors' is true, shorter events are discarded. Default 1000",
+ "type": "integer"
+ },
+ "recordAllocations": {
+ "description": "Record allocation data with call stacks instead of performance data. The two are exclusive because recording both distorts the results. Valuable on its own via the allocation datasets, and a heap dump taken in such a session additionally carries per-object allocation sites (heap.allocation* datasets). Allocation data is sampled, not exact. Default false",
+ "type": "boolean"
+ },
+ "recordMonitors": {
+ "description": "Also record monitor and lock events: threads blocked on monitors, waiting in Object.wait or parked, with stack traces. Composes with performance and allocation recording and enables the monitor.* datasets for contention, lock-order inversion and deadlock analysis. Default false",
+ "type": "boolean"
+ },
+ "subsystems": {
+ "description": "The subsystems to record in this session. Subsystems not listed are not recorded. Built-in values: cpu, jdbc, jpa, mongo_db, cassandra, http_server, http_client, ws, jndi, jms, kafka_consumer, rmi, grpc, ai, socket, file, process, gc. Custom probes of the profiled application (embedded or injected probe classes) are recorded as 'custom:<fully qualified probe class name>', e.g. custom:com.example.MyProbe. Script probes are not listed here, they are defined in 'advanced.scriptProbes' and recorded as 'script:<name>'. Default: cpu, jdbc, jpa, mongo_db, cassandra, http_server, http_client, ws, jndi, jms, kafka_consumer, rmi, grpc, ai, process, gc.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "triggers": {
+ "description": "Actions executed automatically when an event occurs during the recording. Use them for conditions that interactive tool calls cannot catch: recordings from JVM start, long-running sessions and transient states like heap spikes, or work scoped to a method with 'methodInvocation'. MBean snapshots and heap dumps captured by triggers become part of the session snapshot and are queried like manually captured ones. Example: {\"on\": \"timer\", \"intervalSeconds\": 60, \"actions\": [{\"type\": \"mbeanSnapshot\"}]}",
+ "items": {
+ "properties": {
+ "actions": {
+ "description": "The actions to run when the event fires, in order.",
+ "items": {
+ "properties": {
+ "allocations": {
+ "description": "Optional for 'startRecording'/'stopRecording': include allocation recording.",
+ "type": "boolean"
+ },
+ "complexity": {
+ "description": "Optional for 'startRecording'/'stopRecording': include complexity recording - requires recordingConfig.advanced.complexityMethods in the same session. Use it to bound the measurement window, for example scoped to a method with a methodInvocation trigger, or to exclude a warmup phase.",
+ "type": "boolean"
+ },
+ "cpu": {
+ "description": "Optional for 'startRecording'/'stopRecording': include CPU recording.",
+ "type": "boolean"
+ },
+ "filter": {
+ "description": "Optional for 'mbeanSnapshot': regular expression matched against the domain and each property value of the MBean object names: \"java.lang|com.mycompany.*\" captures all MBeans in those domains, \"Memory\" the java.lang:type=Memory MBean. Without a filter all MBeans are captured, the right choice for exploration.",
+ "type": "string"
+ },
+ "fullGc": {
+ "description": "Optional for 'heapDump': run a full GC before the dump so only live objects are captured. Default true.",
+ "type": "boolean"
+ },
+ "includeVirtualThreads": {
+ "description": "Optional for 'threadDump': take a virtual thread dump that includes all virtual threads and the thread container hierarchy in addition to the platform threads. Default false (platform threads only). Virtual threads require JDK 21+.",
+ "type": "boolean"
+ },
+ "label": {
+ "description": "Optional for 'mbeanSnapshot' and 'threadDump': label shown in the mbean.snapshots resp. threads.dumps dataset. In triggers the default is a name derived from the event.",
+ "type": "string"
+ },
+ "monitors": {
+ "description": "Optional for 'startRecording'/'stopRecording': include monitor recording.",
+ "type": "boolean"
+ },
+ "probes": {
+ "description": "Optional for 'startRecording'/'stopRecording': probe names to start or stop, e.g. [\"jdbc\"], \"custom:<fully qualified probe class name>\" for custom probes of the profiled application, or \"script:<name>\" for a script probe defined in recordingConfig.advanced.scriptProbes.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "seconds": {
+ "description": "Required for 'sleep': the wait time in seconds.",
+ "type": "integer"
+ },
+ "type": {
+ "description": "'mbeanSnapshot': capture the current JMX MBean attribute values into the session snapshot (mbean.snapshots dataset). 'heapDump': take a heap dump that becomes part of the session snapshot (heap.* datasets) - expensive, use it with rare events like 'stop' or a high 'heapThreshold', not with 'timer' or 'start'. 'threadDump': take a thread dump that becomes part of the session snapshot (threads.dumps dataset) - cheap, suitable for 'timer' and threshold triggers. 'monitorDump': capture the currently held and waited-on monitors with the involved threads and stack traces (monitor.current dataset) - only the latest dump is kept, repeated fires overwrite it, so prefer events like 'stop' or thresholds over 'timer'. 'markHeap': mark all current heap objects as old, so a heap dump taken later distinguishes objects allocated afterwards (generation 'new' in the heap.* datasets). 'startRecording'/'stopRecording': start or stop recording of subsystems, at least one of 'cpu', 'allocations', 'monitors', 'probes', 'complexity' is required. 'waitForFinish': only for 'methodInvocation', splits the actions into on-entry and on-exit. 'sleep': wait, delays the following actions.",
+ "enum": [
+ "mbeanSnapshot",
+ "heapDump",
+ "threadDump",
+ "monitorDump",
+ "markHeap",
+ "startRecording",
+ "stopRecording",
+ "waitForFinish",
+ "sleep"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "type"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "count": {
+ "description": "Optional for 'on': 'timer': fire at most this many times. Default unlimited.",
+ "type": "integer"
+ },
+ "intervalSeconds": {
+ "description": "Required for 'on': 'timer': the period in seconds.",
+ "type": "integer"
+ },
+ "method": {
+ "description": "Required for 'on': 'methodInvocation': the method in the format com.foo.Bar.method(long, java.lang.String) as printed by the performance.outliers dataset; the argument list is required, use () for no parameters. Method triggers instrument only the named method and work with any method call recording type, including the default sampling. Recursive calls fire only once per outermost invocation.",
+ "type": "string"
+ },
+ "offsetSeconds": {
+ "description": "Optional for 'on': 'timer': delay of the first fire in seconds. Default 0. With a 0 offset the first fire can land before the application has registered its MBeans or reached its working state, a small offset like 1 avoids a mostly empty first capture.",
+ "type": "integer"
+ },
+ "on": {
+ "description": "When the actions run: 'start' when the recording starts (after the optional delay for prepare_profiling, right after attaching for attach), 'stop' when the recording stops (JVM exit, maximumDuration or check_status with stopRecording for prepare_profiling, check_status with stopRecording for attach), 'timer' periodically, 'heapThreshold' when the used heap stays above 'percent' of the maximum heap, 'cpuThreshold' when the CPU usage stays above 'percent'. Threshold triggers fire at most about once a minute while the condition holds. 'methodInvocation' fires when the method given in 'method' is entered; with 'waitForFinish' in the actions, the actions before it run on method entry and the actions after it on method exit. A subsystem started by a method trigger is not started automatically at recording start, so the trigger defines the recording scope.",
+ "enum": [
+ "start",
+ "stop",
+ "timer",
+ "heapThreshold",
+ "cpuThreshold",
+ "methodInvocation"
+ ],
+ "type": "string"
+ },
+ "percent": {
+ "description": "Required for 'heapThreshold' and 'cpuThreshold': the threshold in percent. Choose a high value such as 80, the actions fire every time the condition holds.",
+ "type": "integer"
+ }
+ },
+ "required": [
+ "on",
+ "actions"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "waitingThresholdMicros": {
+ "description": "Optional minimum duration in microseconds for waiting and parked monitor events when 'recordMonitors' is true, shorter events are discarded. Default 100000",
+ "type": "integer"
+ }
+ },
+ "type": "object"
+}
