DTrace Probes ↑

A list of DTrace probes and their functionality. “Module” and “Function” cannot be defined in user defined probes (known as USDT), so they will not be specified. Probe definitions are in the format of:

provider:module:function:name(arguments)

Since module and function cannot be specified, they will be blank. An example probe definition for Ruby would then be:

ruby:::method-entry(class name, method name, file name, line number)

Where “ruby” is the provider name, module and function names are blank, the probe name is “method-entry”, and the probe takes four arguments:

Probes List ↑

Stability ↑

Before we list the specific probes, let’s talk about stability. Probe stability is declared in the probes.d file at the bottom on the pragma D attributes lines. Here is a description of each of the stability declarations.

Provider name stability

The provider name of “ruby” has been declared as stable. It is unlikely that we will change the provider name from “ruby” to something else.

Module and Function stability

Since we are not allowed to provide values for the module and function name, the values we have provided (no value) is declared as stable.

Probe name stability

The probe names are likely to change in the future, so they are marked as “Evolving”. Consumers should not depend on these names to be stable.

Probe argument stability

The parameters passed to the probes are likely to change in the future, so they are marked as “Evolving”. Consumers should not depend on these to be stable.

Declared probes ↑

Probes are defined in the probes.d file. Here are the declared probes along with when they are fired and the arguments they take:

ruby:::method-entry(classname, methodname, filename, lineno);

This probe is fired just before a method is entered.

classname

name of the class (a string)

methodname

name of the method about to be executed (a string)

filename

the file name where the method is _being called_ (a string)

lineno

the line number where the method is _being called_ (an int)

NOTE: will only be fired if tracing is enabled, e.g. with: TracePoint.new{}.enable. See Feature#14104 for more details.

ruby:::method-return(classname, methodname, filename, lineno);

This probe is fired just after a method has returned. The arguments are the same as “ruby:::method-entry”.

NOTE: will only be fired if tracing is enabled, e.g. with: TracePoint.new{}.enable. See Feature#14104 for more details.

ruby:::cmethod-entry(classname, methodname, filename, lineno);

This probe is fired just before a C method is entered. The arguments are the same as “ruby:::method-entry”.

ruby:::cmethod-return(classname, methodname, filename, lineno);

This probe is fired just before a C method returns. The arguments are the same as “ruby:::method-entry”.

ruby:::require-entry(requiredfile, filename, lineno);

This probe is fired on calls to rb_require_safe (when a file is required).

requiredfile

the name of the file to be required (string).

filename

the file that called “require” (string).

lineno

the line number where the call to require was made (int).

ruby:::require-return(requiredfile, filename, lineno);

This probe is fired just before rb_require_safe (when a file is required) returns. The arguments are the same as “ruby:::require-entry”. This probe will not fire if there was an exception during file require.

ruby:::find-require-entry(requiredfile, filename, lineno);

This probe is fired right before search_required is called. search_required determines whether the file has already been required by searching loaded features ($"), and if not, figures out which file must be loaded.

requiredfile

the file to be required (string).

filename

the file that called “require” (string).

lineno

the line number where the call to require was made (int).

ruby:::find-require-return(requiredfile, filename, lineno);

This probe is fired right after search_required returns. See the documentation for “ruby:::find-require-entry” for more details. Arguments for this probe are the same as “ruby:::find-require-entry”.

ruby:::load-entry(loadedfile, filename, lineno);

This probe is fired when calls to “load” are made. The arguments are the same as “ruby:::require-entry”.

ruby:::load-return(loadedfile, filename, lineno);

This probe is fired when “load” returns. The arguments are the same as “ruby:::load-entry”.

ruby:::raise(classname, filename, lineno);

This probe is fired when an exception is raised.

classname

the class name of the raised exception (string)

filename

the name of the file where the exception was raised (string)

lineno

the line number in the file where the exception was raised (int)

ruby:::object-create(classname, filename, lineno);

This probe is fired when an object is about to be allocated.

classname

the class of the allocated object (string)

filename

the name of the file where the object is allocated (string)

lineno

the line number in the file where the object is allocated (int)

ruby:::array-create(length, filename, lineno);

This probe is fired when an Array is about to be allocated.

length

the size of the array (long)

filename

the name of the file where the array is allocated (string)

lineno

the line number in the file where the array is allocated (int)

ruby:::hash-create(length, filename, lineno);

This probe is fired when a Hash is about to be allocated.

length

the size of the hash (long)

filename

the name of the file where the hash is allocated (string)

lineno

the line number in the file where the hash is allocated (int)

ruby:::string-create(length, filename, lineno);

This probe is fired when a String is about to be allocated.

length

the size of the string (long)

filename

the name of the file where the string is allocated (string)

lineno

the line number in the file where the string is allocated (int)

ruby:::symbol-create(str, filename, lineno);

This probe is fired when a Symbol is about to be allocated.

str

the contents of the symbol (string)

filename

the name of the file where the string is allocated (string)

lineno

the line number in the file where the string is allocated (int)

ruby:::parse-begin(sourcefile, lineno);

Fired just before parsing and compiling a source file.

sourcefile

the file being parsed (string)

lineno

the line number where the source starts (int)

ruby:::parse-end(sourcefile, lineno);

Fired just after parsing and compiling a source file.

sourcefile

the file being parsed (string)

lineno

the line number where the source ended (int)

ruby:::gc-mark-begin();

Fired at the beginning of a mark phase.

ruby:::gc-mark-end();

Fired at the end of a mark phase.

ruby:::gc-sweep-begin();

Fired at the beginning of a sweep phase.

ruby:::gc-sweep-end();

Fired at the end of a sweep phase.

ruby:::method-cache-clear(class, sourcefile, lineno);

Fired when the method cache is cleared.

class

the classname being cleared, or “global” (string)

sourcefile

the file being parsed (string)

lineno

the line number where the source ended (int)