Home | History | Annotate | Download | only in utils 
      1 /*
      2  * Copyright 2018 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 
     17 package com.android.server.display.utils;
     18 
     19 
     20 import java.lang.StringBuilder;
     21 import java.lang.System;
     22 
     23 import android.util.Slog;
     24 
     25 /**
     26  * A utility to log multiple points and curves in a structured way so they can be easily consumed
     27  * by external tooling
     28  *
     29  * To start a plot, call {@link Plog.start} with the plot's title; to add a point to it, call
     30  * {@link Plog.logPoint} with the point name (that will appear in the legend) and coordinates; and
     31  * to log a curve, call {@link Plog.logCurve} with its name and points.
     32  */
     33 public abstract class Plog {
     34     // A unique identifier used to group points and curves that belong on the same plot.
     35     private long mId;
     36 
     37     /**
     38      * Returns a Plog instance that emits messages to the system log.
     39      *
     40      * @param tag The tag of the emitted messages in the system log.
     41      * @return A plog instance that emits messages to the system log.
     42      */
     43     public static Plog createSystemPlog(String tag) {
     44         return new SystemPlog(tag);
     45     }
     46 
     47     /**
     48      * Start a new plot.
     49      *
     50      * @param title The plot title.
     51      * @return The Plog instance (for chaining).
     52      */
     53     public Plog start(String title) {
     54         mId = System.currentTimeMillis();
     55         write(formatTitle(title));
     56         return this;
     57     }
     58 
     59     /**
     60      * Adds a point to the current plot.
     61      *
     62      * @param name The point name (that will appear in the legend).
     63      * @param x The point x coordinate.
     64      * @param y The point y coordinate.
     65      * @return The Plog instance (for chaining).
     66      */
     67     public Plog logPoint(String name, float x, float y) {
     68         write(formatPoint(name, x, y));
     69         return this;
     70     }
     71 
     72     /**
     73      * Adds a curve to the current plot.
     74      *
     75      * @param name The curve name (that will appear in the legend).
     76      * @param xs The curve x coordinates.
     77      * @param ys The curve y coordinates.
     78      * @return The Plog instance (for chaining).
     79      */
     80     public Plog logCurve(String name, float[] xs, float[] ys) {
     81         write(formatCurve(name, xs, ys));
     82         return this;
     83     }
     84 
     85     private String formatTitle(String title) {
     86         return "title: " + title;
     87     }
     88 
     89     private String formatPoint(String name, float x, float y) {
     90         return "point: " + name + ": (" + x + "," + y + ")";
     91     }
     92 
     93     private String formatCurve(String name, float[] xs, float[] ys) {
     94         StringBuilder sb = new StringBuilder();
     95         sb.append("curve: " + name + ": [");
     96         int n = xs.length <= ys.length ? xs.length : ys.length;
     97         for (int i = 0; i < n; i++) {
     98             sb.append("(" + xs[i] + "," + ys[i] + "),");
     99         }
    100         sb.append("]");
    101         return sb.toString();
    102     }
    103 
    104     private void write(String message) {
    105         emit("[PLOG " + mId + "] " + message);
    106     }
    107 
    108     /**
    109      * Emits a message (depending on the concrete Plog implementation).
    110      *
    111      * @param message The message.
    112      */
    113     protected abstract void emit(String message);
    114 
    115     /**
    116      * A Plog that emits messages to the system log.
    117      */
    118     public static class SystemPlog extends Plog {
    119         // The tag of the emitted messages in the system log.
    120         private final String mTag;
    121 
    122         /**
    123          * Returns a Plog instance that emits messages to the system log.
    124          *
    125          * @param tag The tag of the emitted messages in the system log.
    126          * @return A Plog instance that emits messages to the system log.
    127          */
    128         public SystemPlog(String tag) {
    129             mTag = tag;
    130         }
    131 
    132         /**
    133          * Emits a message to the system log.
    134          *
    135          * @param message The message.
    136          */
    137         protected void emit(String message) {
    138             Slog.d(mTag, message);
    139         }
    140     }
    141 }
    142