View Javadoc
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, &quot;*&quot;);
38       * Set&lt;ObjectName&gt; 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      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 }