Extract metrics package from gerrit-server top-level directory

Change-Id: I7c21b82de289ebc24b530d6b37abf6c33b4dec2f
2017-08-22 23:02:19 +02:00
parent bd3f50e61b
commit 1f78f3efa1
58 changed files with 62 additions and 30 deletions
--- a/java/com/google/gerrit/metrics/Description.java
+++ b/java/com/google/gerrit/metrics/Description.java
@@ -0,0 +1,199 @@
+// Copyright (C) 2015 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 com.google.gerrit.metrics;
+
+import com.google.common.base.Strings;
+import com.google.common.collect.ImmutableMap;
+import com.google.common.collect.Maps;
+import java.util.Map;
+import java.util.concurrent.TimeUnit;
+
+/** Describes a metric created by {@link MetricMaker}. */
+public class Description {
+  public static final String DESCRIPTION = "DESCRIPTION";
+  public static final String UNIT = "UNIT";
+  public static final String CUMULATIVE = "CUMULATIVE";
+  public static final String RATE = "RATE";
+  public static final String GAUGE = "GAUGE";
+  public static final String CONSTANT = "CONSTANT";
+  public static final String FIELD_ORDERING = "FIELD_ORDERING";
+  public static final String TRUE_VALUE = "1";
+
+  public static class Units {
+    public static final String SECONDS = "seconds";
+    public static final String MILLISECONDS = "milliseconds";
+    public static final String MICROSECONDS = "microseconds";
+    public static final String NANOSECONDS = "nanoseconds";
+
+    public static final String BYTES = "bytes";
+
+    private Units() {}
+  }
+
+  public enum FieldOrdering {
+    /** Default ordering places fields at end of the parent metric name. */
+    AT_END,
+
+    /**
+     * Splits the metric name by inserting field values before the last '/' in the metric name. For
+     * example {@code "plugins/replication/push_latency"} with a {@code Field.ofString("remote")}
+     * will create submetrics named {@code "plugins/replication/some-server/push_latency"}.
+     */
+    PREFIX_FIELDS_BASENAME;
+  }
+
+  private final Map<String, String> annotations;
+
+  /**
+   * Describe a metric.
+   *
+   * @param helpText a short one-sentence string explaining the values captured by the metric. This
+   *     may be made available to administrators as documentation in the reporting tools.
+   */
+  public Description(String helpText) {
+    annotations = Maps.newLinkedHashMapWithExpectedSize(4);
+    annotations.put(DESCRIPTION, helpText);
+  }
+
+  /**
+   * Set unit used to describe the value.
+   *
+   * @param unitName name of the unit, e.g. "requests", "seconds", etc.
+   * @return this
+   */
+  public Description setUnit(String unitName) {
+    annotations.put(UNIT, unitName);
+    return this;
+  }
+
+  /**
+   * Mark the value as constant for the life of this process. Typically used for software versions,
+   * command line arguments, etc. that cannot change without a process restart.
+   *
+   * @return this
+   */
+  public Description setConstant() {
+    annotations.put(CONSTANT, TRUE_VALUE);
+    return this;
+  }
+
+  /**
+   * Indicates the metric may be usefully interpreted as a count over short periods of time, such as
+   * request arrival rate. May only be applied to a {@link Counter0}.
+   *
+   * @return this
+   */
+  public Description setRate() {
+    annotations.put(RATE, TRUE_VALUE);
+    return this;
+  }
+
+  /**
+   * Instantaneously sampled value that may increase or decrease at a later time. Memory allocated
+   * or open network connections are examples of gauges.
+   *
+   * @return this
+   */
+  public Description setGauge() {
+    annotations.put(GAUGE, TRUE_VALUE);
+    return this;
+  }
+
+  /**
+   * Indicates the metric accumulates over the lifespan of the process. A {@link Counter0} like
+   * total requests handled accumulates over the process and should be {@code setCumulative()}.
+   *
+   * @return this
+   */
+  public Description setCumulative() {
+    annotations.put(CUMULATIVE, TRUE_VALUE);
+    return this;
+  }
+
+  /**
+   * Configure how fields are ordered into submetric names.
+   *
+   * @param ordering field ordering
+   * @return this
+   */
+  public Description setFieldOrdering(FieldOrdering ordering) {
+    annotations.put(FIELD_ORDERING, ordering.name());
+    return this;
+  }
+
+  /** @return true if the metric value never changes after startup. */
+  public boolean isConstant() {
+    return TRUE_VALUE.equals(annotations.get(CONSTANT));
+  }
+
+  /** @return true if the metric may be interpreted as a rate over time. */
+  public boolean isRate() {
+    return TRUE_VALUE.equals(annotations.get(RATE));
+  }
+
+  /** @return true if the metric is an instantaneous sample. */
+  public boolean isGauge() {
+    return TRUE_VALUE.equals(annotations.get(GAUGE));
+  }
+
+  /** @return true if the metric accumulates over the lifespan of the process. */
+  public boolean isCumulative() {
+    return TRUE_VALUE.equals(annotations.get(CUMULATIVE));
+  }
+
+  /** @return the suggested field ordering. */
+  public FieldOrdering getFieldOrdering() {
+    String o = annotations.get(FIELD_ORDERING);
+    return o != null ? FieldOrdering.valueOf(o) : FieldOrdering.AT_END;
+  }
+
+  /**
+   * Decode the unit as a unit of time.
+   *
+   * @return valid time unit.
+   * @throws IllegalArgumentException if the unit is not a valid unit of time.
+   */
+  public TimeUnit getTimeUnit() {
+    return getTimeUnit(annotations.get(UNIT));
+  }
+
+  private static final ImmutableMap<String, TimeUnit> TIME_UNITS =
+      ImmutableMap.of(
+          Units.NANOSECONDS, TimeUnit.NANOSECONDS,
+          Units.MICROSECONDS, TimeUnit.MICROSECONDS,
+          Units.MILLISECONDS, TimeUnit.MILLISECONDS,
+          Units.SECONDS, TimeUnit.SECONDS);
+
+  public static TimeUnit getTimeUnit(String unit) {
+    if (Strings.isNullOrEmpty(unit)) {
+      throw new IllegalArgumentException("no unit configured");
+    }
+    TimeUnit u = TIME_UNITS.get(unit);
+    if (u == null) {
+      throw new IllegalArgumentException(String.format("unit %s not TimeUnit", unit));
+    }
+    return u;
+  }
+
+  /** @return immutable copy of all annotations (configurable properties). */
+  public ImmutableMap<String, String> getAnnotations() {
+    return ImmutableMap.copyOf(annotations);
+  }
+
+  @Override
+  public String toString() {
+    return annotations.toString();
+  }
+}