System X-Ray is useful for displaying system metrics on Fire TV, but did you know you can display information of your own choosing? Your app can send information to System X-Ray which will be displayed while your app is in the foreground. There are several ways this feature can be used, such as displaying static information, when a metric crosses different threshold boundaries, or when an event occurs. Let’s walk through some examples.

Examples

Static Information

If you test your app on multiple Fire TVs, you may have wished you could tell at a glance which Fire TV model you are testing. If you connect your Fire TVs to different WiFi networks, it would be helpful to see which network a Fire TV is currently connected to. System X-Ray can help you solve these problems. You can collect this information as your app starts up, and send it to System X-Ray.

private void updateMetrics(Context context, String buildModel, String ssid) {
    // Initialize Intent
    Intent intent = new Intent("com.amazon.ssm.METRICS_UPDATE");
    intent.putExtra("com.amazon.ssm.PACKAGENAME", context.getPackageName());

    // Add metrics
    intent.putExtra("Metrics1", buildModel);
    intent.putExtra("Metrics2", ssid);

    // Send
    context.sendBroadcast(intent);
}

The output of this method look like this:

In the screenshot above, you can see that the Fire TV device model is AFTS, which is the 2^nd generation Fire TV box. You can also see that the Fire TV is connected to the Guest network.

Thresholds

You may 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 dropped frames to be green, 5-9 to be yellow, and 10 and higher to be red. Every time the number of dropped frames increases, you can assign the color of the threshold and update System X-Ray.

private void updateMetrics(Context context, int numFrameDrops, String frameDropStatus) {
    // Initialize Intent
    Intent intent = new Intent("com.amazon.ssm.METRICS_UPDATE");
    intent.putExtra("com.amazon.ssm.PACKAGENAME", context.getPackageName());

    // Add metrics
    intent.putExtra("Metrics1", "FrameDrops:"+numFrameDrops);
    intent.putExtra("Color1", frameDropStatus);

    // Send
    context.sendBroadcast(intent);
}

Here are screenshots of what the different thresholds look like:

Events

Event logging is useful, but you may want a visual way to track when a specific event occurs. For example, perhaps testing reveals that an intermittent Exception is thrown after 3 hours of video playback. You would like to be able to playback video for several hours and be able to to tell visually if the Exception has been thrown. You can achieve this by calling a method like the one below, where the Exception is caught in your code.

 private void updateMetrics(Context context, String message, String time) {
    // Initialize Intent
    Intent intent = new Intent("com.amazon.ssm.METRICS_UPDATE");
    intent.putExtra("com.amazon.ssm.PACKAGENAME", context.getPackageName());

    // Add metrics
    intent.putExtra("Metrics1", message);
    intent.putExtra("Color1", "Red");

    intent.putExtra("Metrics2", "Time:"+time);
    intent.putExtra("Color2", "Red");

    // Send
    context.sendBroadcast(intent);
}

Here is an example of what this message looks like:

Summary

These are just a few ways you can use System X-Ray’s custom metrics feature. I hope this inspires you to think of possibilities for using this feature in your own app. The information in this blog post has now been added to the documentation here.