Guides and Sample Code

Developer

Instruments User Guide

On This Page

Measure Energy Impact

Even small inefficiencies in apps add up across the system, significantly affecting battery life, performance, responsiveness, and temperature. As an app developer, you have an obligation to make sure your app runs as efficiently as possible. Use Instruments to monitor the impact of your app in order to understand how it utilizes resources and identify times when energy usage is high. Use best practices to improve efficiency in these areas, and strive for your app to be absolutely idle when not responding to user input. By adhering to the recommended guidelines in Energy Efficiency Guide for Mac Apps, you can make big contributions to the overall energy efficiency of the system and the satisfaction of your users.

Debug Energy During Development

The debug navigator in Xcode includes an Energy Impact gauge (see Figure 23-1), which provides a high-level overview of energy usage as you test your app. Consult this gauge regularly throughout your app’s testing cycle to assess your app’s energy impact and identify potential problem areas up-front. If necessary, dive into Instruments for more in-depth analysis.

Figure 23-1The Energy Impact gauge in Xcode image: ../Art/xcode_debug_navigator_energyimpact_gauge_2x.png

Measure the Energy Impact of an iOS App

Use the Energy Log profiling template to monitor a variety of factors that affect energy usage on an iOS device, including CPU activity, network activity, screen brightness, and more. Identify the areas where usage is highest, and see if you can reduce impact in those areas. For example, you might find opportunities to defer discretionary or network tasks until more energy efficient times, such as when the device is plugged in or on Wi-Fi.

To monitor the energy impact of an iOS app
  1. Launch Instruments, and create a new trace document that targets your device and app with the Energy Log profiling template.

    image: ../Art/instruments_energydiagnosticsprofilingtemplateandtarget_2x.png
  2. Click the Record button (image: ../Art/inline_record_button_2x.png), or press Command-R, to begin recording a trace.

  3. Use the app normally on the device, while allowing energy data to be collected.

  4. Click the Stop button (image: ../Art/inline_stop_button_2x.png), or press Command-R again, when complete.

  5. Go through the collected data and look for spikes or areas of otherwise unusual or unexpected activity. Then, review the code in these areas to determine whether improvements can be made.

    image: ../Art/instruments_energydiagnostics_data_2x.png

Log Energy Usage Directly on an iOS Device

Without tethering your device to Instruments (either wirelessly or wired), you can log energy-related data under normal use in order to take realistic measurements. With energy logging enabled, your iOS device records energy-related data unobtrusively while the device is used. Because logging is efficient, you can log all day. Logging continues even while the device is in sleep mode. However, if the device’s battery drains completely or the iOS device is powered off, the log data is lost.

To log energy data in iOS
  1. Go to Settings > Developer > Logging on your device.

    image: ../Art/ios_settings_2x.png
    image: ../Art/ios_developer_2x.png
  2. Enable energy logging.

    image: ../Art/ios_logging_2x.png
  3. Tap Start Recording.

    image: ../Art/ios_logging_startrecording_2x.png
  4. Use your device normally.

  5. When you’re done, return to Settings > Developer > Logging and tap Stop Recording.

    image: ../Art/ios_logging_stoprecording_2x.png
To import logged energy data from an iOS device
  1. Launch Instruments, and create a new trace document that targets your device and app with the Energy Log profiling template.

    image: ../Art/instruments_energydiagnostics_profilingtemplate_2x.png
  2. Choose File > Import Logged Data from Device.

    image: ../Art/instruments_file_menu_importloggeddatafromdevice_menuitem_2x.png

    The logged data is imported and displayed in the timeline and detail panes.

    image: ../Art/instruments_trace_document_energyusageimported_2x.png

Measure the Energy Impact of an OS X App

Like iOS, a variety of factors affect the energy impact of an app in OS X. Although the Energy Log profiling template is designed for use with iOS, you can use other profiling templates to examine and assess your app’s energy impact in OS X.

image: ../Art/templateActivityMonitor_48_2x.png

Activity Monitor. Use this profiling template to monitor overall CPU, disk I/O, and network usage.

image: ../Art/templateFileActivity_48_2x.png

File Activity. Use this profiling template to track disk I/O activity, including file opens, closes, reads, and writes.

image: ../Art/templateTimeProfiler_48_2x.png

Time Profiler. Use this profiling template to monitor your app’s activity over time. Time Profiler watches the running threads in your app and takes samples at regular intervals. A complete backtrace is collected for each sample, allowing you to drill down into a sample to find exactly where in your code large amounts of time are being spent.

image: ../Art/templateBlank_48_2x.png

Your Custom Template Here. The templates above provide high value by analyzing multiple aspects of your app, which may affect energy. If you prefer to focus in on a more specific area, however, you can add individual instruments to the Blank profiling template. If you think you might need to perform the same type of analysis again, be sure and save your configuration as a template. See Save a Trace Document as a Profiling Template.

Again, monitor for spikes or areas of high or unexpected activity, and see whether you can improve those areas to reduce CPU and other resource utilization.