How to measure energy usage in Xcode 13 / iOS15?

Question

I'd like to confirm the battery usage of an app I am developing on iOS, specifically on Xcode 13 and iOS 15. (Note: This app previously showed no issues with battery usage on previous versions of iOS.)

Previously, it seems that there were two ways to gather energy usage information:

#1. On the device under Settings > Developer > Logging

• As per Apple's documentation described in the section titled "Log Energy Usage Directly on an iOS Device".
• However, on iOS15, I can't find any options for logging under Developer or anywhere under settings even when searching.

#2. Profiling via Instruments using the "Energy Log" template

• As per the same documentation from Apple described in the section "Use the Energy Diagnostics Profiling Template".
• While it is still available in Xcode 12, this template is missing in Xcode 13. Naturally, it's also not possible to profile an iOS15 device with Xcode 12.

Digging through the Xcode 13 release notes, I found the following:

Instruments no longer includes the Energy template; use metrics reporting in the Xcode Organizer instead. (74161279)

When I access the Organizer in Xcode (12 or 13), select an app and click "Energy" for all versions of the app, it shows the following:

Apple's documentation for "Analyzing the Performance of Your Shipping App" says:

"In some cases the pane shows “Insufficient usage data available,” because there may not be enough anonymized data reported by participating user devices. When this happens, try checking back in a few days."

Well over a year into production and having sufficient install numbers, I have a feeling that waiting a few days might not do much.

I would like to determine if this is a bug in my app or a bug in iOS15. How can energy usage data be gathered using Xcode 13 on iOS 15?

Vlad

Answer 1

After contacting Apple Developer Technical Support (DTS) regarding this issue, they provided me with the following guidance:

Regarding "insufficient usage data available" for energy logs (or reports) accessible via the Xcode Energy Organizer:

DTS indicated that they do not publish the thresholds for active users, and usage logs would be expected to be present if you consistently have more than a few thousand active users on each app version. If your app meets this criteria and still does not show energy logs, DTS recommends opening a bug report with them.

Note the "Energy Organizer" is accessed in Xcode via the Window toolbar → Organizer → Reports → Energy.

Regarding how to collect energy log data for your app:

DTS recommended using MetricKit to get daily metric payloads. Payloads are delivered to your app every 24 hours, and it is then possible to consume them and send them off the device.

The instantiation of this is:

import MetricKit

...

// Somewhere in your application startup sequence:
MXMetricManager.shared.add(someObjectYouWantToHaveThisResponsibility)

...

extension SomeObjectYouWantToHaveThisResponsibility: MXMetricManagerSubscriber {
   func didReceive(_ payloads: [MXMetricPayload]) {
       for payload in payloads {
           // Parse the payload here
       }
   }
}

For a full list of metrics, see the MXMetricPayload class.

Regarding the two documentation links that I included above:

Apple asked me to open feedback tickets to get them updated. I opened both tickets (FB9665186, FB9665194) on September 30, 2021 and they are both still in an "Open" status as of today.

In the case of my app and the problem I had encountered, it turns out that battery drain was just a symptom and not the actual problem, so it wouldn't be helpful to include any of those details here.

Apple Documentation (as of Jan 2024)

• About Energy organizer
• How are reports created? (Thanks to @NickMorhun!)

Vlad

But in my Xcode organiser, it always show Insufficient Metrics Data - No Metrics data found for the latest app versions with sufficient usage. Does this mean there is a restriction for number of usage? – Neutrino

@Neutrino As mentioned in the answer above, the answer I received from Apple DTS directly was that they "do not publish the thresholds for active users," and that "usage logs would be expected to be present if you have more than a few thousand active users consistently on each version of your app". If you do not have more than a few thousand users on each version of your app, then I wouldn't expect you to see any data here. Your best bet is likely to implement MetricKit and gather the relevant data yourself, or you may want to follow up with Apple DTS to see if they can assist. – Vlad

It looks to me MXMetricPayload does not provide energy consumption metrics, is it? – Belike

It makes no sense to remove "Energy profiling" from Instrument. If we can only rely on Metrics api, that means we can't do the energy consumption measurement before we have a few thousands of users. That's ridiculous. – Neutrino

Does the same apply to the "Energy" Organizer tool? – Scarbrough

@NickMorhun Yes, the "Energy Organizer" tool is the tool that provides energy log data and is what my question and answer are referring to. So if you are seeing "No Energy Logs" it is likely due to insufficient data as per Apple's provided guidance shared in my answer. – Vlad

@DerekLee thank you for the quick answer. After some more digging, I found the documentation at help.apple.com/xcode/mac/current/#/dev675635e70, which says, "For energy reports, a log is generated when an app exceeds a reasonable CPU threshold in the foreground or background, and causes excessive battery usage." – Scarbrough

Answer 2

It's worth noting that Xcode does have an Energy Impact section in the Debug navigator.

There's also some "hidden" instruments available once you start, say "Time Profiler." Click the top right + button to see the available options.

Verbify