Developer

Timer

The Timer object allows you to measure the duration of an application operation. The duration is logged with the timestamp of the event and a key value that can be used for filtering analytics.

There are two ways developers can handle the Timer object:
  • Call timeStart(String key) and timeEnd(String key) APIs. The library stores the Timer object, which is invisible to the application developer. The library keeps the Timer in memory and persists it in the database when timeEnd(String key) is called. The key is mandatory and must be unique for each timer. To store additional information, other than the automatically reported data, the developer can call timeEnd(String key, Map<String, String> info) or timeEnd(String key, Map<String, String> info, String type). The content of the info and type arguments are stored in the record, to allow more specific queries.
  • Call makeTimer(String key) and stopTimer(Timer timer) methods. makeTimer(String key) creates a Timer instance and returns to the application layer. The application stores the timer; the library does not keep references to it. When the application wants to stop and persist the Timer, it calls stopTimer(Timer timer). To store additional information, other than the automatically reported data, the developer can call stopTimer(Timer timer, Map<String, String> info) or stopTimer(Timer timer, Map<String, String> info, String type). The content of the info and type arguments are stored in the record, to allow more specific queries.

The API timer is an object with a timestamp and a method to stop the timer, which sets the timer interval to the current time and saves the duration. After the timer stops, the Timer object is saved in the database.

Because the Timer object is handled in memory, it is well suited for passing into blocks or through delegate patterns. For example, the duration of an asynchronous sequence can be measured by creating a timer outside of a block, then calling the void stopTimer(Timer timer) method within the completion block created in the same context.

Example

A developer wants to know how long it takes for data to appear on a screen. A timer captures how long it takes to download and parse the set of business partners from the network. The developer is also interested in the details of which business partners the end user viewed.

The application consists of two activities: the first one displays a list of available business partners and the second shows additional details of the selected partner.

Create a timer, then call stop when the download is complete:

@Override
protected void onCreate(Bundle savedInstanceState) {
		

	super.onCreate(savedInstanceState);
	setContentView(R.layout.activity_main);

	// Get ListView object from xml
	listView = (ListView) findViewById(R.id.list);
	usage = InitUsage.getUsage(this);
	Timer timer = usage.startTimer("Download Business Partners");

	// Download available business partners
	String[] businessPartners = downloadBusinessPartners();
	usage.stopTimer(timer);
	ArrayAdapter<String> adapter = new ArrayAdapter<String>(this, android.R.layout.simple_list_item_1, android.R.id.text1, businessPartners);

	// Assign adapter to ListView
	listView.setAdapter(adapter);

	// ListView Item Click Listener
	listView.setOnItemClickListener(new OnItemClickListener() {

		@Override
		public void onItemClick(AdapterView<?> parent, View view, int position, long id) {
			Intent intent = new Intent(parent.getContext(), DetailsActivity.class);
			intent.putExtra("DETAIL",businessPartners[position]);
			Map<String, String> descriptionInfo = new HashMap<String, String>();
			descriptionInfo.put("Business Partner Name", businessPartners[position]);
			usage.log("Details View Called", descriptionInfo, "Business Partner");
			startActivity(intent);
		}

	});
}

The library generates two records that POSTs to the server:

{
    "timestamp" : "2014-10-02T14:23:53.841-0700",
    "key" : " Download Business Partners ",
    "info" : {
        "start" : "2014-10-02T14:23:53.841-0700",
        "duration" : 790.3379797935486
        },
    "type" : "timer",
    "userSessionId" : "1"
} 

{
    "timestamp" : "2014-10-02T14:23:59.567-0700",
    "key" : " Details View Called",
    "info" : {
        "Business Partner Name" : "John Smith"
        },
    "type" : "Business Partner",
    "userSessionId" : "1"
}