From 9c9cb4ccc2f6cf1d325f6b18ac412abc0b24ed7e Mon Sep 17 00:00:00 2001 From: nscuro Date: Fri, 31 Mar 2023 21:18:33 +0200 Subject: [PATCH 1/2] Add health endpoint Also reduce default health check interval in Dockerfile from 5m to 30s Signed-off-by: nscuro --- src/main/docker/Dockerfile | 2 +- .../health/HealthCheckInitializer.java | 38 +++++++++++++++++++ src/main/webapp/WEB-INF/web.xml | 17 ++++++++- 3 files changed, 54 insertions(+), 3 deletions(-) create mode 100644 src/main/java/org/dependencytrack/health/HealthCheckInitializer.java diff --git a/src/main/docker/Dockerfile b/src/main/docker/Dockerfile index faae4311d9..76274a8f4a 100644 --- a/src/main/docker/Dockerfile +++ b/src/main/docker/Dockerfile @@ -67,7 +67,7 @@ CMD java ${JAVA_OPTIONS} ${EXTRA_JAVA_OPTIONS} --add-opens java.base/java.util.c EXPOSE 8080 # Add a healthcheck using the Dependency-Track version API -HEALTHCHECK --interval=5m --timeout=3s CMD wget --no-proxy -q -O /dev/null http://127.0.0.1:8080${CONTEXT}api/version || exit 1 +HEALTHCHECK --interval=30s --timeout=3s CMD wget --no-proxy -q -O /dev/null http://127.0.0.1:8080${CONTEXT}health || exit 1 # metadata labels LABEL \ diff --git a/src/main/java/org/dependencytrack/health/HealthCheckInitializer.java b/src/main/java/org/dependencytrack/health/HealthCheckInitializer.java new file mode 100644 index 0000000000..7848313090 --- /dev/null +++ b/src/main/java/org/dependencytrack/health/HealthCheckInitializer.java @@ -0,0 +1,38 @@ +/* + * This file is part of Dependency-Track. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + * SPDX-License-Identifier: Apache-2.0 + * Copyright (c) Steve Springett. All Rights Reserved. + */ +package org.dependencytrack.health; + +import alpine.common.logging.Logger; +import alpine.server.health.HealthCheckRegistry; +import alpine.server.health.checks.DatabaseHealthCheck; + +import javax.servlet.ServletContextEvent; +import javax.servlet.ServletContextListener; + +public class HealthCheckInitializer implements ServletContextListener { + + private static final Logger LOGGER = Logger.getLogger(HealthCheckInitializer.class); + + @Override + public void contextInitialized(final ServletContextEvent event) { + LOGGER.info("Registering health checks"); + HealthCheckRegistry.getInstance().register("database", new DatabaseHealthCheck()); + } + +} diff --git a/src/main/webapp/WEB-INF/web.xml b/src/main/webapp/WEB-INF/web.xml index 2c451d7218..a023661edf 100644 --- a/src/main/webapp/WEB-INF/web.xml +++ b/src/main/webapp/WEB-INF/web.xml @@ -38,6 +38,9 @@ alpine.server.persistence.PersistenceManagerFactory + + org.dependencytrack.health.HealthCheckInitializer + org.dependencytrack.persistence.DefaultObjectGenerator @@ -59,7 +62,7 @@ alpine.server.filters.WhitelistUrlFilter allowUrls - /index.html,/css,/fonts,/img,/js,/static,/favicon.ico,/api,/metrics,/mirror,/.well-known + /index.html,/css,/fonts,/img,/js,/static,/favicon.ico,/api,/health,/metrics,/mirror,/.well-known forwardTo @@ -67,7 +70,7 @@ forwardExcludes - /api,/metrics,/mirror + /api,/health,/metrics,/mirror @@ -131,6 +134,16 @@ /api/* + + Health + alpine.server.servlets.HealthServlet + 1 + + + Health + /health/* + + Metrics alpine.server.servlets.MetricsServlet From e867283382bdd89b324d455b3077b0775cf4e333 Mon Sep 17 00:00:00 2001 From: nscuro Date: Sat, 1 Apr 2023 16:21:19 +0200 Subject: [PATCH 2/2] Add health check documentation Signed-off-by: nscuro --- docs/_docs/getting-started/monitoring.md | 40 +++++++++++++++++++++--- 1 file changed, 35 insertions(+), 5 deletions(-) diff --git a/docs/_docs/getting-started/monitoring.md b/docs/_docs/getting-started/monitoring.md index 03a119f76c..5873f575c5 100644 --- a/docs/_docs/getting-started/monitoring.md +++ b/docs/_docs/getting-started/monitoring.md @@ -5,6 +5,33 @@ chapter: 1 order: 12 --- + +### Health + +Starting with v4.8.0, Dependency-Track exposes health information according to the [MicroProfile Health] specification. +Refer to the specification for details on how the exposed endpoints behave (i.e. [MicroProfile Health REST interfaces specifications]). + +Currently, only a single [readiness check] is included. The *database* check verifies that database connections can be +acquired and used successfully. The check spans both connection pools (see [Connection Pooling]). + +```json +{ + "status": "UP", + "checks": [ + { + "name": "database", + "status": "UP", + "data": { + "nontx_connection_pool": "UP", + "tx_connection_pool": "UP" + } + } + ] +} +``` + +### Metrics + The API server can be configured to expose system metrics via the Prometheus [text-based exposition format]. They can then be collected and visualized using tools like [Prometheus] and [Grafana]. Especially for containerized deployments where directly attaching to the underlying Java Virtual Machine (JVM) is not possible, monitoring @@ -19,13 +46,13 @@ To enable metrics exposition, set the `alpine.metrics.enabled` property to `true Metrics will be exposed in the `/metrics` endpoint, and can optionally be protected using basic authentication via `alpine.metrics.auth.username` and `alpine.metrics.auth.password`. -### Exposed Metrics +#### Exposed Metrics Exposed metrics include various general purpose system and JVM statistics (CPU and Heap usage, thread states, garbage collector activity etc.), but also some related to Dependency-Track's internal event and notification system. More metrics covering other areas of Dependency-Track will be added in future versions. -#### Database +##### Database Metrics of the ORM used by the Dependency-Track API server are exposed under the `datanucleus` namespace. They provide a high-level overview of how many, and which kind of persistence operations are performend: @@ -145,7 +172,7 @@ hikaricp_connections_acquire_seconds_max{pool="non-transactional",} 1.41889E-4 hikaricp_connections_acquire_seconds_max{pool="transactional",} 1.77837E-4 ``` -#### Event and Notification System +##### Event and Notification System Event and notification metrics include the following: @@ -216,7 +243,7 @@ doing keeping up with the work it's being exposed to. For example, a constantly value combined with a high number of `executor_queued_tasks` may indicate that the configured `alpine.worker.pool.size` is too small for the workload at hand. -#### Retries +##### Retries Dependency-Track will occasionally retry requests to external services. Metrics about this behavior are exposed in the following format: @@ -230,7 +257,7 @@ resilience4j_retry_calls_total{kind="successful_without_retry",name="snyk-api",} Where `name` describes the remote endpoint that Dependency-Track uses retries for. -### Grafana Dashboard +#### Grafana Dashboard Because [Micrometer](https://micrometer.io/) is used to collect and expose metrics, common Grafana dashboards for Micrometer should just work. @@ -253,7 +280,10 @@ An [example dashboard] is provided as a quickstart. Refer to the [Grafana docume [executors]: https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/concurrent/ThreadPoolExecutor.html [Grafana]: https://grafana.com/ [Grafana documentation]: https://grafana.com/docs/grafana/latest/dashboards/export-import/#import-dashboard +[MicroProfile Health]: https://download.eclipse.org/microprofile/microprofile-health-3.1/microprofile-health-spec-3.1.html +[MicroProfile Health REST interfaces specifications]: https://download.eclipse.org/microprofile/microprofile-health-3.1/microprofile-health-spec-3.1.html#_appendix_a_rest_interfaces_specifications [Prometheus]: https://prometheus.io/ +[readiness check]: https://download.eclipse.org/microprofile/microprofile-health-3.1/microprofile-health-spec-3.1.html#_readiness_check [Snyk]: {{ site.baseurl }}{% link _docs/datasources/snyk.md %} [text-based exposition format]: https://prometheus.io/docs/instrumenting/exposition_formats/#text-based-format [thread states]: https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/lang/Thread.State.html