001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.microservice.management;
018
019import org.apache.juneau.rest.server.*;
020import org.apache.juneau.rest.server.health.*;
021import org.apache.juneau.rest.server.management.*;
022import org.apache.juneau.rest.server.servlet.*;
023
024/**
025 * Convenience assembly of the Actuator-style management surface under a single configurable path prefix.
026 *
027 * <p>
028 * Mounts the management endpoints by composing their {@code *Mixin} flavors via
029 * {@link Rest#mixins() @Rest(mixins=...)} on top of {@link BasicRestServletGroup}:
030 * <ul>
031 *    <li>{@code /healthz}, {@code /readyz}, {@code /livez} &mdash; {@link HealthMixin} (read-through health view)
032 *    <li>{@code /threaddump}, {@code /heapdump} &mdash; {@link DumpsMixin} (deny-by-default diagnostics)
033 * </ul>
034 *
035 * <p>
036 * <b>{@code /info} and {@code /loggers} are off by default</b> &mdash; unlike health, they are not mounted
037 * on the bare group, since {@link InfoMixin} discloses the full manifest and {@link LoggersMixin}'s read side
038 * discloses logger topology, neither behind any auth. Turn either back on (either approach suffices):
039 * <ul>
040 *    <li><b>A-la-carte (recommended):</b> mount {@link InfoMixin} / {@link LoggersMixin} on a resource you
041 *       control, e.g. a {@code BasicActuatorGroup} subclass with
042 *       {@code @Rest(mixins={InfoMixin.class, LoggersMixin.class})} &mdash; mixins declared on a subclass are
043 *       additive to the mixins inherited from this class, so {@code HealthMixin}/{@code DumpsMixin} stay mounted
044 *       too.
045 *    <li><b>Zero-code:</b> not currently supported &mdash; {@code @Rest(mixins=...)} is a compile-time class
046 *       list, and the {@code RestContext.Builder} injection point that would have let a system property add a
047 *       mixin at init time was removed prior to 10.0.0 (see {@link RestInit}).  Use the a-la-carte subclass above.
048 * </ul>
049 *
050 * <p>
051 * <b>Path prefix:</b> defaults to {@code /actuator} and is configurable via the {@code juneau.actuator.path}
052 * system property (resolved through the standard {@code $S{...}} SVL var).  Mount the group at a custom prefix
053 * either by setting that property or by subclassing with your own {@link Rest#path() @Rest(path=...)}.
054 *
055 * <p>
056 * <b>Composition is convenience, not the only way in:</b> every endpoint remains independently mountable
057 * a-la-carte via its standalone {@code *Mixin}/{@code *Resource} flavor.  The {@code /metrics} endpoint is
058 * <b>not</b> assembled here &mdash; it lives in the {@code juneau-rest-server-metrics-micrometer} module
059 * (which this module does not depend on), so add {@code MetricsMixin} a-la-carte when that module is present.
060 *
061 * <p>
062 * <b>Exposure policy:</b> of the mounted endpoints, health is on; the mutating/sensitive ones
063 * ({@code /threaddump}, {@code /heapdump}) are deny-by-default via {@link DumpsSettings}.  No auth provider is
064 * auto-wired (explicit-over-magic).
065 *
066 * <h5 class='section'>See Also:</h5><ul>
067 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/ManagementSurface">Management Surface (Actuator-style endpoints)</a>
068 * </ul>
069 *
070 * @serial exclude
071 * @since 10.0.0
072 */
073@Rest(
074   path="$S{juneau.actuator.path,/actuator}",
075   title="Management",
076   description="Actuator-style management surface.",
077   mixins={
078      HealthMixin.class,
079      DumpsMixin.class
080   }
081)
082@SuppressWarnings({
083   "java:S110" // Inheritance depth acceptable for microservice hierarchy.
084})
085public class BasicActuatorGroup extends BasicRestServletGroup {
086   private static final long serialVersionUID = 1L;
087}