001    /**
002     * Licensed to the Apache Software Foundation (ASF) under one
003     * or more contributor license agreements.  See the NOTICE file
004     * distributed with this work for additional information
005     * regarding copyright ownership.  The ASF licenses this file
006     * to you under the Apache License, Version 2.0 (the
007     * "License"); you may not use this file except in compliance
008     * with the License.  You may obtain a copy of the License at
009     *
010     *     http://www.apache.org/licenses/LICENSE-2.0
011     *
012     * Unless required by applicable law or agreed to in writing, software
013     * distributed under the License is distributed on an "AS IS" BASIS,
014     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015     * See the License for the specific language governing permissions and
016     * limitations under the License.
017     */
018    
019    package org.apache.hadoop.metrics2;
020    
021    import org.apache.hadoop.classification.InterfaceAudience;
022    import org.apache.hadoop.classification.InterfaceStability;
023    
024    /**
025     * The metrics record builder interface
026     */
027    @InterfaceAudience.Public
028    @InterfaceStability.Evolving
029    public abstract class MetricsRecordBuilder {
030      /**
031       * Add a metrics tag
032       * @param info  metadata of the tag
033       * @param value of the tag
034       * @return self
035       */
036      public abstract MetricsRecordBuilder tag(MetricsInfo info, String value);
037    
038      /**
039       * Add an immutable metrics tag object
040       * @param tag a pre-made tag object (potentially save an object construction)
041       * @return self
042       */
043      public abstract MetricsRecordBuilder add(MetricsTag tag);
044    
045      /**
046       * Add a pre-made immutable metric object
047       * @param metric  the pre-made metric to save an object construction
048       * @return self
049       */
050      public abstract MetricsRecordBuilder add(AbstractMetric metric);
051    
052      /**
053       * Set the context tag
054       * @param value of the context
055       * @return self
056       */
057      public abstract MetricsRecordBuilder setContext(String value);
058    
059      /**
060       * Add an integer metric
061       * @param info  metadata of the metric
062       * @param value of the metric
063       * @return self
064       */
065      public abstract MetricsRecordBuilder addCounter(MetricsInfo info, int value);
066    
067      /**
068       * Add an long metric
069       * @param info  metadata of the metric
070       * @param value of the metric
071       * @return self
072       */
073      public abstract MetricsRecordBuilder addCounter(MetricsInfo info, long value);
074    
075      /**
076       * Add a integer gauge metric
077       * @param info  metadata of the metric
078       * @param value of the metric
079       * @return self
080       */
081      public abstract MetricsRecordBuilder addGauge(MetricsInfo info, int value);
082    
083      /**
084       * Add a long gauge metric
085       * @param info  metadata of the metric
086       * @param value of the metric
087       * @return self
088       */
089      public abstract MetricsRecordBuilder addGauge(MetricsInfo info, long value);
090    
091      /**
092       * Add a float gauge metric
093       * @param info  metadata of the metric
094       * @param value of the metric
095       * @return self
096       */
097      public abstract MetricsRecordBuilder addGauge(MetricsInfo info, float value);
098    
099      /**
100       * Add a double gauge metric
101       * @param info  metadata of the metric
102       * @param value of the metric
103       * @return self
104       */
105      public abstract MetricsRecordBuilder addGauge(MetricsInfo info, double value);
106    
107      /**
108       * @return the parent metrics collector object
109       */
110      public abstract MetricsCollector parent();
111    
112      /**
113       * Syntactic sugar to add multiple records in a collector in a one liner.
114       * @return the parent metrics collector object
115       */
116      public MetricsCollector endRecord() { return parent(); }
117    }