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 019package org.apache.hadoop.metrics2; 020 021import org.apache.hadoop.classification.InterfaceAudience; 022import org.apache.hadoop.classification.InterfaceStability; 023 024/** 025 * The metrics system interface 026 */ 027@InterfaceAudience.Public 028@InterfaceStability.Evolving 029public abstract class MetricsSystem implements MetricsSystemMXBean { 030 031 @InterfaceAudience.Private 032 public abstract MetricsSystem init(String prefix); 033 034 /** 035 * Register a metrics source 036 * @param <T> the actual type of the source object 037 * @param source object to register 038 * @param name of the source. Must be unique or null (then extracted from 039 * the annotations of the source object.) 040 * @param desc the description of the source (or null. See above.) 041 * @return the source object 042 * @exception MetricsException 043 */ 044 public abstract <T> T register(String name, String desc, T source); 045 046 /** 047 * Unregister a metrics source 048 * @param name of the source. This is the name you use to call register() 049 */ 050 public abstract void unregisterSource(String name); 051 052 /** 053 * Register a metrics source (deriving name and description from the object) 054 * @param <T> the actual type of the source object 055 * @param source object to register 056 * @return the source object 057 * @exception MetricsException 058 */ 059 public <T> T register(T source) { 060 return register(null, null, source); 061 } 062 063 /** 064 * @param name of the metrics source 065 * @return the metrics source (potentially wrapped) object 066 */ 067 @InterfaceAudience.Private 068 public abstract MetricsSource getSource(String name); 069 070 /** 071 * Register a metrics sink 072 * @param <T> the type of the sink 073 * @param sink to register 074 * @param name of the sink. Must be unique. 075 * @param desc the description of the sink 076 * @return the sink 077 * @exception MetricsException 078 */ 079 public abstract <T extends MetricsSink> 080 T register(String name, String desc, T sink); 081 082 /** 083 * Register a callback interface for JMX events 084 * @param callback the callback object implementing the MBean interface. 085 */ 086 public abstract void register(Callback callback); 087 088 /** 089 * Requests an immediate publish of all metrics from sources to sinks. 090 * 091 * This is a "soft" request: the expectation is that a best effort will be 092 * done to synchronously snapshot the metrics from all the sources and put 093 * them in all the sinks (including flushing the sinks) before returning to 094 * the caller. If this can't be accomplished in reasonable time it's OK to 095 * return to the caller before everything is done. 096 */ 097 public abstract void publishMetricsNow(); 098 099 /** 100 * Shutdown the metrics system completely (usually during server shutdown.) 101 * The MetricsSystemMXBean will be unregistered. 102 * @return true if shutdown completed 103 */ 104 public abstract boolean shutdown(); 105 106 /** 107 * The metrics system callback interface (needed for proxies.) 108 */ 109 public interface Callback { 110 /** 111 * Called before start() 112 */ 113 void preStart(); 114 115 /** 116 * Called after start() 117 */ 118 void postStart(); 119 120 /** 121 * Called before stop() 122 */ 123 void preStop(); 124 125 /** 126 * Called after stop() 127 */ 128 void postStop(); 129 } 130 131 /** 132 * Convenient abstract class for implementing callback interface 133 */ 134 public static abstract class AbstractCallback implements Callback { 135 @Override public void preStart() {} 136 @Override public void postStart() {} 137 @Override public void preStop() {} 138 @Override public void postStop() {} 139 } 140}