Go to: Synopsis. Return value. Keywords. Related. Flags. MEL examples.

Synopsis

profiler [-addCategory string] [-allCategories] [-bufferSize int] [-categoryIndex int] [-categoryIndexToName int] [-categoryInfo string] [-categoryName string] [-categoryNameToIndex string] [-categoryRecording boolean] [-clearAllMelInstrumentation] [-colorIndex int] [-eventCPUId] [-eventCategory] [-eventColor] [-eventCount] [-eventDescription] [-eventDuration] [-eventIndex int] [-eventName] [-eventStartTime] [-eventThreadId] [-instrumentMel boolean] [-load string] [-output string] [-procedureDescription string] [-procedureName string] [-removeCategory string] [-reset] [-sampling boolean] [-signalEvent] [-signalMelEvent boolean]

profiler is NOT undoable, queryable, and NOT editable.

The profiler is used to record timing information from key events within Maya, as an aid in tuning the performance of scenes, scripts and plug-ins. User written plug-ins and Python scripts can also generate profiling information for their own code through the MProfilingScope (C++), MProfilingContextManager (Python) and MProfiler classes in the API.

This command provides the ability to control the collection of profiling data and to query information about the recorded events. The recorded information can also be viewed graphically in the Profiler window.

The buffer size cannot be changed while sampling is active, it will return an error The reset flag cannot be called while sampling is active, it will return an error. Any changes to the buffer size will only be applied on start of the next recording. You can't save and load in the same command, save has priority, load would be ignored.

Return value

None

In query mode, return type is based on queried flag.

Keywords

timing, performance, profiling, optimize

Related

dgtimer

Flags

addCategory, allCategories, bufferSize, categoryIndex, categoryIndexToName, categoryInfo, categoryName, categoryNameToIndex, categoryRecording, clearAllMelInstrumentation, colorIndex, eventCPUId, eventCategory, eventColor, eventCount, eventDescription, eventDuration, eventIndex, eventName, eventStartTime, eventThreadId, instrumentMel, load, output, procedureDescription, procedureName, removeCategory, reset, sampling, signalEvent, signalMelEvent
Long name (short name) Argument types Properties
-addCategory(-a) string create
Add a new category for the profiler. Returns the index of the new category.
-allCategories(-ac) query
Query the names of all categories. If the categoryInfo flag is set then alternate the name of the category with the description of the category.
-bufferSize(-b) int createquery
Toggled : change the buffer size to fit the specified number of events (requires that sampling is off) Query : return the current buffer size The new buffer size will only take effect when next sampling starts. When the buffer is full, the recording stops.
-categoryIndex(-ci) int createquery
Used in conjunction with other flags, to indicate the index of the category.

In query mode, this flag needs a value.

-categoryIndexToName(-cin) int createquery
Returns the name of the category with a given index.

In query mode, this flag needs a value.

-categoryInfo(-cf) string createquery
When used with the addCategory flag set the description of the added profiler category. In query mode return the description of the category referenced by either the categoryIndex or categoryName flags.

In query mode, this flag can accept a value.

-categoryName(-cn) string query
Used in conjunction with other flags, to indicate the name of the category.

In query mode, this flag needs a value.

-categoryNameToIndex(-cni) string createquery
Returns the index of the category with a given name.

In query mode, this flag needs a value.

-categoryRecording(-cr) boolean createquery
Toggled : Enable/disable the recording of the category. Query : return if the recording of the category is On. Requires the -categoryIndex or -categoryName flag to specify the category to be queried.
-clearAllMelInstrumentation(-cam) create
Clear all MEL command or procedure instrumentation.
-colorIndex(-coi) int create
Used with "-instrumentMel true" to specify the color index to show the profiling result.
-eventCPUId(-eci) query
Query the CPU ID of the event at the given index. Requires the -eventIndex flag to specify the event to be queried.
-eventCategory(-eca) query
Query the category index the event at the given index belongs to. Requires the -eventIndex flag to specify the event to be queried.
-eventColor(-eco) query
Query the color of the event at the given index. Requires the -eventIndex flag to specify the event to be queried.
-eventCount(-ec) query
Query the number of events in the buffer
-eventDescription(-ed) query
Query the description of the event at the given index. Requires the -eventIndex flag to specify the event to be queried.
-eventDuration(-edu) query
Query the duration of the event at the given index, the time unit is microsecond. Note that a signal event has a 0 duration. Requires the -eventIndex flag to specify the event to be queried.
-eventIndex(-ei) int query
Used usually in conjunction with other flags, to indicate the index of the event.

In query mode, this flag needs a value.

-eventName(-en) query
Query the name of the event at the given index. Requires the -eventIndex flag to specify the event to be queried.
-eventStartTime(-et) query
Query the time of the event at the given index, the time unit is microsecond. Requires the -eventIndex flag to specify the event to be queried.
-eventThreadId(-eti) query
Query the thread ID of the event at the given index. Requires the -eventIndex flag to specify the event to be queried.
-instrumentMel(-in) boolean create
Enable/Diable the instrumentation of a MEL command or procedure. When the instrumentation is enabled, the execution of MEL command or procedure can be profiled and shown in the Profiler window. To enable the instrumentation requires the -procedureName, -colorIndex and -categoryIndex flags. To disable the instrumentation requires the -procedureName flag.
-load(-l) string createquery
Read the recorded events from the specified file
-output(-o) string createquery
Output the recorded events to the specified file
-procedureDescription(-pd) string create
Used with "-instrumentMel true" to provide a description of the MEL command or procedure being instrumented. This description can be viewed in the Profiler Tool window.
-procedureName(-pn) string create
Used with -instrumentMel to specify the name of the procedure to be enabled/disabled the instrumentation.
-removeCategory(-rc) string create
Remove an existing category for the profiler. Returns the index of the removed category.
-reset(-r) createquery
reset the profiler's data (requires that sampling is off)
-sampling(-s) boolean createquery
Toggled : Enable/disable the recording of events Query : return if the recording of events is On.
-signalEvent(-sig) query
Query if the event at the given index is a signal event. Requires the -eventIndex flag to specify the event to be queried. A Signal Event only remembers the start moment and has no knowledge about duration. It can be used in cases when the user does not care about the duration but only cares if this event does happen.
-signalMelEvent(-sim) boolean create
Used with "-instrumentMel true", inform profiler that this instrumented MEL command or procedure will be taken as a signal event during profiling. A Signal Event only remembers the start moment and has no knowledge about duration. It can be used in cases when the user does not care about the duration but only cares if this event does happen.

Flag can appear in Create mode of command Flag can appear in Edit mode of command
Flag can appear in Query mode of command Flag can be used more than once in a command.

MEL examples

// Start profiling
profiler -sampling true;

// Wait for events to be profiled
// Stop profiling
profiler -sampling false;

// Output the result to a file
profiler -output "test.txt";

// Load a recording from a file to the buffer
profiler -load "test.txt";

// Reset the tool
profiler -reset;

// Set the profiler's buffer size to fit 5 megaBytes
profiler -bufferSize 5;

// Query the profiler's buffer size
profiler -query -bufferSize;

// Add a new category
profiler -addCategory "Test Category" -categoryInfo "Events related to my special test";

// Remove an existing category
profiler -removeCategory "Test Category";

// Query the index of the category with the given name
profiler -query -categoryNameToIndex "Maya Qt" ;

// Query the info of the category with the given name
profiler -categoryNameToIndex "Maya Qt" -query -info;

// Query the info of the category at the given index
profiler -categoryIndexToName 5 -query -info;

// Query if it is enabled for the recording of the category at the given index
profiler -query -categoryRecording -categoryIndex 5;

// Query if it is enabled for the recording of the category with the given name
profiler -query -categoryRecording -categoryName "Maya Qt";

// Enable/Disable the recording of the category at the given index
profiler -categoryIndex 5 -categoryRecording false;
profiler -categoryIndex 5 -categoryRecording true;

// Query the number of the events in the buffer
profiler -query -eventCount;

// Query the time at which the event at the given index start
profiler -query -eventStartTime -eventIndex 100;

// Query the duration of the event at the given index
profiler -query -eventDuration -eventIndex 100;

// Query the name of the event at the given index
profiler -query -eventName -eventIndex 100;

// Query the description of the event at the given index
profiler -query -eventDescription -eventIndex 100;

// Query the category the the event at the given index belongs to
profiler -query -eventCategory -eventIndex 100;

// Query the color of the event at the given index
profiler -query -eventColor -eventIndex 100;

// Query the thread ID of the event at the given index
profiler -query -eventThreadId -eventIndex 100;
//
// Query the CPU ID of the event at the given index
profiler -query -eventCPUId -eventIndex 100;
//
// Query if the event at the given index is a signal event
profiler -query -signalEvent -eventIndex 100;

// Instrument a MEL command or procedure
// Given a MEL procedure which calculate factorial, it will be instrumented
// and profiled
proc int Factorial(int $limit)
{
    int $result = 1;
    for( $i=1; $i<=$limit; ++$i)
    {
        $result = $result * $i;
    }
    return $result;
}

// Add a new category for MEL Scripts
int $melCategoryIndex = `profiler -addCategory "MEL Scripts" -categoryInfo "Events triggered by MEL scripts"`;

// Instrument a MEL command
profiler -instrumentMel true -procedureName "deviceManager" -categoryIndex $melCategoryIndex -colorIndex 2 -procedureDescription "deviceManagerDesc";

// Instrument a MEL procedure as a signal event
profiler -instrumentMel true -procedureName "Factorial" -categoryIndex $melCategoryIndex -colorIndex 8 -procedureDescription "FactorialDesc" -signalMelEvent true;

// Profiler the MEL procedure and command.
profiler -s true;
Factorial(5);
deviceManager -query -numDevices;
profiler -s false;

// Remove the instrumentation of the MEL command and procedure
profiler -instrumentMel false -procedureName "deviceManager";
profiler -instrumentMel false -procedureName "Factorial";