android/metrics/LogMaker.java

/*
 * Copyright (C) 2017 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package android.metrics;

import android.annotation.SystemApi;
import android.annotation.TestApi;
import android.content.ComponentName;
import android.util.Log;
import android.util.SparseArray;

import com.android.internal.annotations.VisibleForTesting;
import com.android.internal.logging.nano.MetricsProto.MetricsEvent;


/**
 * Helper class to assemble more complex logs.
 *
 * @hide
 */
@SystemApi
@TestApi
public class LogMaker {
    private static final String TAG = "LogBuilder";

    /**
     * Min required eventlog line length.
     * See: android/util/cts/EventLogTest.java
     * Size checks enforced here are intended only as sanity checks;
     * your logs may be truncated earlier. Please log responsibly.
     *
     * @hide
     */
    @VisibleForTesting
    public static final int MAX_SERIALIZED_SIZE = 4000;

    private SparseArray<Object> entries = new SparseArray();

    /** @param category for the new LogMaker. */
    public LogMaker(int category) {
        setCategory(category);
    }

    /* Deserialize from the eventlog */
    public LogMaker(Object[] items) {
        if (items != null) {
            deserialize(items);
        } else {
            setCategory(MetricsEvent.VIEW_UNKNOWN);
        }
    }

    /** @param category to replace the existing setting. */
    public LogMaker setCategory(int category) {
        entries.put(MetricsEvent.RESERVED_FOR_LOGBUILDER_CATEGORY, category);
        return this;
    }

    /** Set the category to unknown. */
    public LogMaker clearCategory() {
        entries.remove(MetricsEvent.RESERVED_FOR_LOGBUILDER_CATEGORY);
        return this;
    }

    /** @param type to replace the existing setting. */
    public LogMaker setType(int type) {
        entries.put(MetricsEvent.RESERVED_FOR_LOGBUILDER_TYPE, type);
        return this;
    }

    /** Set the type to unknown. */
    public LogMaker clearType() {
        entries.remove(MetricsEvent.RESERVED_FOR_LOGBUILDER_TYPE);
        return this;
    }

    /** @param subtype to replace the existing setting. */
    public LogMaker setSubtype(int subtype) {
        entries.put(MetricsEvent.RESERVED_FOR_LOGBUILDER_SUBTYPE, subtype);
        return this;
    }

    /** Set the subtype to 0. */
    public LogMaker clearSubtype() {
        entries.remove(MetricsEvent.RESERVED_FOR_LOGBUILDER_SUBTYPE);
        return this;
    }

    /**
     * Set event latency.
     *
     * @hide // TODO Expose in the future?  Too late for O.
     */
    public LogMaker setLatency(long milliseconds) {
        entries.put(MetricsEvent.RESERVED_FOR_LOGBUILDER_LATENCY_MILLIS, milliseconds);
        return this;
    }

    /**
     * This will be set by the system when the log is persisted.
     * Client-supplied values will be ignored.
     *
     * @param timestamp to replace the existing settings.
     * @hide
     */
    public LogMaker setTimestamp(long timestamp) {
        entries.put(MetricsEvent.RESERVED_FOR_LOGBUILDER_TIMESTAMP, timestamp);
        return this;
    }

    /** Remove the timestamp property.
     * @hide
     */
    public LogMaker clearTimestamp() {
        entries.remove(MetricsEvent.RESERVED_FOR_LOGBUILDER_TIMESTAMP);
        return this;
    }

    /** @param packageName to replace the existing setting. */
    public LogMaker setPackageName(String packageName) {
        entries.put(MetricsEvent.RESERVED_FOR_LOGBUILDER_PACKAGENAME, packageName);
        return this;
    }

    /**
     * @param component to replace the existing setting.
     * @hide
     */
    public LogMaker setComponentName(ComponentName component) {
        entries.put(MetricsEvent.RESERVED_FOR_LOGBUILDER_PACKAGENAME, component.getPackageName());
        entries.put(MetricsEvent.FIELD_CLASS_NAME, component.getClassName());
        return this;
    }

    /** Remove the package name property. */
    public LogMaker clearPackageName() {
        entries.remove(MetricsEvent.RESERVED_FOR_LOGBUILDER_PACKAGENAME);
        return this;
    }

    /**
     * This will be set by the system when the log is persisted.
     * Client-supplied values will be ignored.
     *
     * @param pid to replace the existing setting.
     * @hide
     */
    public LogMaker setProcessId(int pid) {
        entries.put(MetricsEvent.RESERVED_FOR_LOGBUILDER_PID, pid);
        return this;
    }

    /** Remove the process ID property.
     * @hide
     */
    public LogMaker clearProcessId() {
        entries.remove(MetricsEvent.RESERVED_FOR_LOGBUILDER_PID);
        return this;
    }

    /**
     * This will be set by the system when the log is persisted.
     * Client-supplied values will be ignored.
     *
     * @param uid to replace the existing setting.
     * @hide
     */
    public LogMaker setUid(int uid) {
        entries.put(MetricsEvent.RESERVED_FOR_LOGBUILDER_UID, uid);
        return this;
    }

    /**
     * Remove the UID property.
     * @hide
     */
    public LogMaker clearUid() {
        entries.remove(MetricsEvent.RESERVED_FOR_LOGBUILDER_UID);
        return this;
    }

    /**
     * The name of the counter or histogram.
     * Only useful for counter or histogram category objects.
     * @param name to replace the existing setting.
     * @hide
     */
    public LogMaker setCounterName(String name) {
        entries.put(MetricsEvent.RESERVED_FOR_LOGBUILDER_NAME, name);
        return this;
    }

    /**
     * The bucket label, expressed as an integer.
     * Only useful for histogram category objects.
     * @param bucket to replace the existing setting.
     * @hide
     */
    public LogMaker setCounterBucket(int bucket) {
        entries.put(MetricsEvent.RESERVED_FOR_LOGBUILDER_BUCKET, bucket);
        return this;
    }

    /**
     * The bucket label, expressed as a long integer.
     * Only useful for histogram category objects.
     * @param bucket to replace the existing setting.
     * @hide
     */
    public LogMaker setCounterBucket(long bucket) {
        entries.put(MetricsEvent.RESERVED_FOR_LOGBUILDER_BUCKET, bucket);
        return this;
    }

    /**
     * The value to increment the counter or bucket by.
     * Only useful for counter and histogram category objects.
     * @param value to replace the existing setting.
     * @hide
     */
    public LogMaker setCounterValue(int value) {
        entries.put(MetricsEvent.RESERVED_FOR_LOGBUILDER_VALUE, value);
        return this;
    }

    /**
     * @param tag From your MetricsEvent enum.
     * @param value One of Integer, Long, Float, or String; or null to clear the tag.
     * @return modified LogMaker
     */
    public LogMaker addTaggedData(int tag, Object value) {
        if (value == null) {
            return clearTaggedData(tag);
        }
        if (!isValidValue(value)) {
            throw new IllegalArgumentException(
                    "Value must be loggable type - int, long, float, String");
        }
        if (value.toString().getBytes().length > MAX_SERIALIZED_SIZE) {
            Log.i(TAG, "Log value too long, omitted: " + value.toString());
        } else {
            entries.put(tag, value);
        }
        return this;
    }

    /**
     * Remove a value from the LogMaker.
     *
     * @param tag From your MetricsEvent enum.
     * @return modified LogMaker
     */
    public LogMaker clearTaggedData(int tag) {
        entries.delete(tag);
        return this;
    }

    /**
     * @return true if this object may be added to a LogMaker as a value.
     */
    public boolean isValidValue(Object value) {
        return value instanceof Integer ||
            value instanceof String ||
            value instanceof Long ||
            value instanceof Float;
    }

    public Object getTaggedData(int tag) {
        return entries.get(tag);
    }

    /** @return the category of the log, or unknown. */
    public int getCategory() {
        Object obj = entries.get(MetricsEvent.RESERVED_FOR_LOGBUILDER_CATEGORY);
        if (obj instanceof Integer) {
            return (Integer) obj;
        } else {
            return MetricsEvent.VIEW_UNKNOWN;
        }
    }

    /** @return the type of the log, or unknwon. */
    public int getType() {
        Object obj = entries.get(MetricsEvent.RESERVED_FOR_LOGBUILDER_TYPE);
        if (obj instanceof Integer) {
            return (Integer) obj;
        } else {
            return MetricsEvent.TYPE_UNKNOWN;
        }
    }

    /** @return the subtype of the log, or 0. */
    public int getSubtype() {
        Object obj = entries.get(MetricsEvent.RESERVED_FOR_LOGBUILDER_SUBTYPE);
        if (obj instanceof Integer) {
            return (Integer) obj;
        } else {
            return 0;
        }
    }

    /** @return the timestamp of the log.or 0 */
    public long getTimestamp() {
        Object obj = entries.get(MetricsEvent.RESERVED_FOR_LOGBUILDER_TIMESTAMP);
        if (obj instanceof Long) {
            return (Long) obj;
        } else {
            return 0;
        }
    }

    /** @return the package name of the log, or null. */
    public String getPackageName() {
        Object obj = entries.get(MetricsEvent.RESERVED_FOR_LOGBUILDER_PACKAGENAME);
        if (obj instanceof String) {
            return (String) obj;
        } else {
            return null;
        }
    }

    /** @return the process ID of the log, or -1. */
    public int getProcessId() {
        Object obj = entries.get(MetricsEvent.RESERVED_FOR_LOGBUILDER_PID);
        if (obj instanceof Integer) {
            return (Integer) obj;
        } else {
            return -1;
        }
    }

    /** @return the UID of the log, or -1. */
    public int getUid() {
        Object obj = entries.get(MetricsEvent.RESERVED_FOR_LOGBUILDER_UID);
        if (obj instanceof Integer) {
            return (Integer) obj;
        } else {
            return -1;
        }
    }

    /** @return the name of the counter, or null. */
    public String getCounterName() {
        Object obj = entries.get(MetricsEvent.RESERVED_FOR_LOGBUILDER_NAME);
        if (obj instanceof String) {
            return (String) obj;
        } else {
            return null;
        }
    }

    /** @return the bucket label of the histogram\, or 0. */
    public long getCounterBucket() {
        Object obj = entries.get(MetricsEvent.RESERVED_FOR_LOGBUILDER_BUCKET);
        if (obj instanceof Number) {
            return ((Number) obj).longValue();
        } else {
            return 0L;
        }
    }

    /** @return true if the bucket label was specified as a long integer. */
    public boolean isLongCounterBucket() {
        Object obj = entries.get(MetricsEvent.RESERVED_FOR_LOGBUILDER_BUCKET);
        return obj instanceof Long;
    }

    /** @return the increment value of the counter, or 0. */
    public int getCounterValue() {
        Object obj = entries.get(MetricsEvent.RESERVED_FOR_LOGBUILDER_VALUE);
        if (obj instanceof Integer) {
            return (Integer) obj;
        } else {
            return 0;
        }
    }

    /**
     * @return a representation of the log suitable for EventLog.
     */
    public Object[] serialize() {
        Object[] out = new Object[entries.size() * 2];
        for (int i = 0; i < entries.size(); i++) {
            out[i * 2] = entries.keyAt(i);
            out[i * 2 + 1] = entries.valueAt(i);
        }
        int size = out.toString().getBytes().length;
        if (size > MAX_SERIALIZED_SIZE) {
            Log.i(TAG, "Log line too long, did not emit: " + size + " bytes.");
            throw new RuntimeException();
        }
        return out;
    }

    /**
     * Reconstitute an object from the output of {@link #serialize()}.
     */
    public void deserialize(Object[] items) {
        int i = 0;
        while (items != null && i < items.length) {
            Object key = items[i++];
            Object value = i < items.length ? items[i++] : null;
            if (key instanceof Integer) {
                entries.put((Integer) key, value);
            } else {
                Log.i(TAG, "Invalid key " + (key == null ? "null" : key.toString()));
            }
        }
    }

    /**
     * @param that the object to compare to.
     * @return true if values in that equal values in this, for tags that exist in this.
     */
    public boolean isSubsetOf(LogMaker that) {
        if (that == null) {
            return false;
        }
        for (int i = 0; i < entries.size(); i++) {
            int key = this.entries.keyAt(i);
            Object thisValue = this.entries.valueAt(i);
            Object thatValue = that.entries.get(key);
            if ((thisValue == null && thatValue != null) || !thisValue.equals(thatValue))
                return false;
        }
        return true;
    }

    /**
     * @return entries containing key value pairs.
     * @hide
     */
    public SparseArray<Object> getEntries() {
        return entries;
    }
}