1/*
2 * Copyright (C) 2016 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.os.health;
18
19import android.content.Context;
20import android.os.BatteryStats;
21import android.os.Process;
22import android.os.RemoteException;
23import android.os.ServiceManager;
24
25import com.android.internal.app.IBatteryStats;
26
27/**
28 * Provides access to data about how various system resources are used by applications.
29 * @more
30 * <p>
31 * If you are going to be using this class to log your application's resource usage,
32 * please consider the amount of resources (battery, network, etc) that will be used
33 * by the logging itself.  It can be substantial.
34 * <p>
35 * <b>Battery Usage</b><br>
36 * The statistics related to power (battery) usage are recorded since the device
37 * was last unplugged. It is expected that applications schedule more work to do
38 * while the device is plugged in (e.g. using {@link android.app.job.JobScheduler
39 * JobScheduler}), and while that can affect charging rates, it is still preferable
40 * to actually draining the battery.
41 */
42public class SystemHealthManager {
43    private final IBatteryStats mBatteryStats;
44
45    /**
46     * Construct a new SystemHealthManager object.
47     * @hide
48     */
49    public SystemHealthManager() {
50        mBatteryStats = IBatteryStats.Stub.asInterface(
51            ServiceManager.getService(BatteryStats.SERVICE_NAME));
52    }
53
54    /**
55     * Obtain a SystemHealthManager object for the supplied context.
56     *
57     * @hide
58     */
59    public static SystemHealthManager from(Context context) {
60        return (SystemHealthManager)context.getSystemService(Context.SYSTEM_HEALTH_SERVICE);
61    }
62
63    /**
64     * Return a {@link HealthStats} object containing a snapshot of system health
65     * metrics for the given uid (user-id, which in usually corresponds to application).
66     * @more
67     *
68     * An application must hold the {@link android.Manifest.permission#BATTERY_STATS
69     * android.permission.BATTERY_STATS} permission in order to retrieve any HealthStats
70     * other than its own.
71     *
72     * @param uid User ID for a given application.
73     * @return A {@link HealthStats} object containing the metrics for the requested
74     * application. The keys for this HealthStats object will be from the {@link UidHealthStats}
75     * class.
76     * @see Process#myUid() Process.myUid()
77     */
78    public HealthStats takeUidSnapshot(int uid) {
79        try {
80            final HealthStatsParceler parceler = mBatteryStats.takeUidSnapshot(uid);
81            return parceler.getHealthStats();
82        } catch (RemoteException ex) {
83            throw new RuntimeException(ex);
84        }
85    }
86
87    /**
88     * Return a {@link HealthStats} object containing a snapshot of system health
89     * metrics for the application calling this API. This method is the same as calling
90     * {@code takeUidSnapshot(Process.myUid())}.
91     *
92     * @return A {@link HealthStats} object containing the metrics for this application. The keys
93     * for this HealthStats object will be from the {@link UidHealthStats} class.
94     */
95    public HealthStats takeMyUidSnapshot() {
96        return takeUidSnapshot(Process.myUid());
97    }
98
99    /**
100     * Return a {@link HealthStats} object containing a snapshot of system health
101     * metrics for the given uids (user-id, which in usually corresponds to application).
102     * @more
103     *
104     * An application must hold the {@link android.Manifest.permission#BATTERY_STATS
105     * android.permission.BATTERY_STATS} permission in order to retrieve any HealthStats
106     * other than its own.
107     *
108     * @param uids An array of User IDs to retrieve.
109     * @return An array of {@link HealthStats} objects containing the metrics for each of
110     * the requested uids. The keys for this HealthStats object will be from the
111     * {@link UidHealthStats} class.
112     */
113    public HealthStats[] takeUidSnapshots(int[] uids) {
114        try {
115            final HealthStatsParceler[] parcelers = mBatteryStats.takeUidSnapshots(uids);
116            final HealthStats[] results = new HealthStats[uids.length];
117            final int N = uids.length;
118            for (int i=0; i<N; i++) {
119                results[i] = parcelers[i].getHealthStats();
120            }
121            return results;
122        } catch (RemoteException ex) {
123            throw new RuntimeException(ex);
124        }
125    }
126
127}
128
129