Supplying a Method Name to an Objective-C Custom Instrument

One of Instruments’ most powerful features is the ability to create your own instruments. Apple supplies an Objective-C provider to DTrace, which Instruments is built on. In the Objective-C provider, you can tell a probe to fire when you enter or exit an Objective-C method. Supplying the method name can be tricky, especially if the method takes multiple arguments. This post shows you how to supply a method name to an Objective-C custom instrument.

Create a new instrument in Instruments by choosing Instrument > Build New Instrument. If you choose the Objective-C provider, the top of the probe looks like the following:

As you can see in the screenshot, you can supply a class and a method name to limit when the probe fires. Suppose you want the probe to fire when you enter an Objective-C method. You would enter the following for a method that takes no arguments:

-MethodName  (Instance method)
+MethodName  (Class method)

If the method takes one argument, place a colon after the method name.

-MethodName:

Things become more complicated if the method takes multiple arguments. You can’t have multiple colons in the method name text field because DTrace interprets colons as provider field separators. Use question marks instead of colons to separate the method’s arguments. Let’s look at an example. Suppose you have the following Objective-C method in your application:

- (BOOL)readFromFileWrapper:(NSFileWrapper*)appFileWrapper ofType:(NSString*)typeName error:(NSError**)outError

You would enter the following as the method name:

-readFromFileWrapper?ofType?error?

Notice how you enter the argument name, which is the text to the left of the colon, and a question mark for each argument.