Custom Instrumentation

In the new Retrace for .NET v2 profiler, all settings are configured via a Stackify.json file that should be deployed with your application.

Retrace provides three types of custom instrumentation that you can add to your application.

1. Profile custom methods - Add any method you would like to profile and show in Retrace's tracing user interface
2. Custom transactions - Required for background services to define when a transaction starts (for non web apps)
3. Tracked functions - Specify methods you would like to track in Retrace. Learn about tracked functions

Custom instrumentation is added via an Instrumentation section in the Stackify.json file. Below are example Stackify.json files for each 3 instrumentation types.

Custom Methods

To create a Custom Method, you will need to specify Assembly, Class, and Method, where Assembly is the assembly name that contains the method to be profiled. This is usually the name of the DLL without the .dll extension:

{
	"AppName": "MyApp",
	"Environment": "MyEnvironment",
	"Instrumentation": [
		{
		  "Assembly": "MyLib",
		  "Class": "MyApp.MyLib.MyClass",
		  "Method": "MyMethod"
		}
	]
}

Custom Transactions

To create a Custom Transaction, you also need to add the property StartTrace and set its value to true. You should then set a name for the operation by providing the OperationName property:

{
   "AppName": "MyApp",
   "Environment": "MyEnvironment",
   "Instrumentation": [
   	 {
   	  "Assembly": "MyApp",
   	  "Class": "MyApp.Tasks",
   	  "Method": "StartTask",
   	  "StartTrace": true,
   	  "OperationName": "Starting Task Tasks.StartTask"
   	}
   ]
}

Tracked Functions

Finally, to create a Tracked Function, you will need to add the property EnableTrackedFunction and set its value to true. To set the name of the tracked function, set the TrackedFunctionName property.

{
	"AppName": "MyApp",
	"Environment": "MyEnvironment",
	"Instrumentation": [
		 {
		  "Assembly": "MyApp",
		  "Class": "MyApp.Tasks",
		  "Method": "GetConfiguration",
		  "EnableTrackedFunction": true,
		  "TrackedFunctionName": "Reading Config Tasks.GetConfiguration"
		}
	]
}

Wildcards for class and method name

If the Class or Method properties end in an asterisk (*), then they will match anything that starts with the string preceding the asterisk. This capability should be used carefully as capturing too much information will impact performance and memory usage of your application. If too many methods are instrumented in a single operation, the profiler will stop collecting information and discard the collected information to limit the impact the profiler can have on the application being profiled.

The properties OperationName and TrackedFunctionName can use the replacement tokens {{ClassName}} and {{MethodName}} which will be replaced by the instrumented class and method name and are useful in the case where the class or method names use wildcards.

{
	"AppName": "MyApp",
	"Environment": "MyEnvironment",
	"Instrumentation": [
		 {
		  "Assembly": "MyApp",
		  "Class": "MyApp.*",
		  "Method": "*",
		  "EnableTrackedFunction": true,
		  "TrackedFunctionName": "Reading Config {{ClassName}}.{{MethodName}}"
		}
	]
}