Customize System X-Ray Metrics

You can customize the display of metrics on System X-Ray by sending the information you want to be displayed. You can use this feature to display anything you find useful, such as static information, when a metric crosses different threshold boundaries, or when an event occurs.

Note: See System X-Ray for an overview of System X-Ray, including how to show the Developer Tool Options menu and read the metrics displayed on the overlay.

This sample uses the Context class to get the necessary resources and classes for the environment.

Initialize the Intent with the action com.amazon.ssm.METRICS_UPDATE and add the package name of your app as an extra. The package name is required because System X-Ray will only display the App section when your app is in the foreground. If you put this code in an Activity, you can call the getPackageName() helper method.

The metric name must be Metrics1, Metrics2, or Metrics3. Any other name will be ignored. You can set a metric’s value to any String you want, but keep in mind that it may be truncated. System X-Ray displays each metric in the following format: [name]:[value].

A metric’s default color is gray. If you choose to change the color, you will need to add an extra to the Intent. The name of the extra must be Color1, Color2, or Color3. The value can be red, yellow, green, or blue. The metric name and color name must have the same number in order for the color to apply. For example, Metrics1 will get Color1. The color values are independent of each other — you can have more than one metric with the same color.

Now that the Intent is set up, you can call the sendBroadcast(Intent) method. If System X-Ray is enabled, it will add a section called App and display the metrics defined in the Intent. If you want to change the value or color of a metric, you must recreate the Intent with the new value or color and send it again.

If you are tracking multiple metrics in System X-Ray, you must resend the status of all of them, even if they don’t all change, as System X-Ray does not cache a metric’s state. Otherwise, the metrics you don’t send will be removed from System X-Ray.

Examples of Custom Metrics

Let’s walk through a few examples of ways you can use this feature.

Static Information

If you test your app on multiple Amazon Fire TV devices or use different WiFi networks, you might want to see which Fire TV model you are testing, or the SSID of the WiFi network the Fire TV is using. As your app starts up, you could get this information and send it to System X-Ray. The following code shows a sample of how to show static information:

The following image is an example display from the above input. In this image, System X-Ray shows that the Amazon Fire TV device model is AFTS, which is the 2nd generation Amazon Fire TV box. It also shows that Fire TV is connected to the Guest network.

Thresholds

You might want to track a metric that can cross different thresholds. For example, let’s say your app has video content and you want to track dropped frames during video playback. You might consider less than 5 drops to be green, 5-9 to be yellow, and 10 and higher to be red.

As you update the number of dropped frames, you change the color to match the threshold. The following code sample shows how show a threshold:

Events

Event logging is useful, but you might want a visual way to track when an event last occurred. For example, perhaps testing reveals that an intermittent Exception is thrown after 3 hours of video playback. Here's a sample of how to configure an event: