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      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 }