1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache license, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the license for the specific language governing permissions and 15 * limitations under the license. 16 */ 17 package org.apache.logging.log4j.core.jmx; 18 19 import java.util.List; 20 21 import javax.management.ObjectName; 22 23 import org.apache.logging.log4j.status.StatusData; 24 25 /** 26 * The MBean interface for monitoring and managing the {@code StatusLogger}. 27 */ 28 public interface StatusLoggerAdminMBean { 29 /** 30 * ObjectName pattern ({@value}) for StatusLoggerAdmin MBeans. 31 * This pattern contains a variable, which is the name of the logger context. 32 * <p> 33 * You can find all registered StatusLoggerAdmin MBeans like this: 34 * </p> 35 * <pre> 36 * MBeanServer mbs = ManagementFactory.getPlatformMBeanServer(); 37 * String pattern = String.format(StatusLoggerAdminMBean.PATTERN, "*"); 38 * Set<ObjectName> statusLoggerNames = mbs.queryNames(new ObjectName(pattern), null); 39 * </pre> 40 * <p> 41 * Some characters are not allowed in ObjectNames. The logger context name 42 * may be quoted. When StatusLoggerAdmin MBeans are 43 * registered, their ObjectNames are created using this pattern as follows: 44 * </p> 45 * <pre> 46 * String ctxName = Server.escape(loggerContext.getName()); 47 * String name = String.format(PATTERN, ctxName); 48 * ObjectName objectName = new ObjectName(name); 49 * </pre> 50 * @see Server#escape(String) 51 */ 52 String PATTERN = Server.DOMAIN + ":type=%s,component=StatusLogger"; 53 54 /** 55 * Notifications with this type have a {@code StatusData} userData object 56 * and a {@code null} message. 57 */ 58 String NOTIF_TYPE_DATA = "com.apache.logging.log4j.core.jmx.statuslogger.data"; 59 60 /** 61 * Notifications with this type have a formatted status data message string 62 * but no {@code StatusData} in their userData field. 63 */ 64 String NOTIF_TYPE_MESSAGE = "com.apache.logging.log4j.core.jmx.statuslogger.message"; 65 66 /** 67 * Returns the {@code ObjectName} that this status logger mbean is registered with. 68 * @return the ObjectName of this StatusLogger MBean 69 */ 70 public ObjectName getObjectName(); 71 72 /** 73 * Returns a list with the most recent {@code StatusData} objects in the 74 * status history. The list has up to 200 entries by default but the length 75 * can be configured with system property {@code "log4j2.status.entries"}. 76 * <p> 77 * Note that the returned objects may contain {@code Throwable}s from 78 * external libraries. 79 * </p> 80 * <p> 81 * JMX clients calling this method must be prepared to deal with the errors 82 * that occur if they do not have the class definition for such 83 * {@code Throwable}s in their classpath. 84 * </p> 85 * 86 * @return the most recent messages logged by the {@code StatusLogger}. 87 */ 88 List<StatusData> getStatusData(); 89 90 /** 91 * Returns a string array with the most recent messages in the status 92 * history. The list has up to 200 entries by default but the length can be 93 * configured with system property {@code "log4j2.status.entries"}. 94 * 95 * @return the most recent messages logged by the {@code StatusLogger}. 96 */ 97 String[] getStatusDataHistory(); 98 99 /** 100 * Returns the {@code StatusLogger} level as a String. 101 * 102 * @return the {@code StatusLogger} level. 103 */ 104 String getLevel(); 105 106 /** 107 * Sets the {@code StatusLogger} level to the specified value. 108 * 109 * @param level the new {@code StatusLogger} level. 110 * @throws IllegalArgumentException if the specified level is not one of 111 * "OFF", "FATAL", "ERROR", "WARN", "INFO", "DEBUG", "TRACE", 112 * "ALL" 113 */ 114 void setLevel(String level); 115 116 /** 117 * Returns the name of the LoggerContext that the {@code StatusLogger} is associated with. 118 * @return logger context name 119 */ 120 String getContextName(); 121 }