From 84c803164657925b506145721380207856029642 Mon Sep 17 00:00:00 2001 From: nscuro Date: Fri, 4 Aug 2023 14:54:55 +0200 Subject: [PATCH] Add logging documentation Closes #2517 Signed-off-by: nscuro --- docs/_docs/getting-started/deploy-docker.md | 4 ++ docs/_docs/getting-started/monitoring.md | 65 +++++++++++++++++++++ src/main/docker/docker-compose.yml | 4 ++ 3 files changed, 73 insertions(+) diff --git a/docs/_docs/getting-started/deploy-docker.md b/docs/_docs/getting-started/deploy-docker.md index de90c1dfca..efeadcfaf9 100755 --- a/docs/_docs/getting-started/deploy-docker.md +++ b/docs/_docs/getting-started/deploy-docker.md @@ -148,6 +148,10 @@ services: # - ALPINE_CORS_ALLOW_CREDENTIALS=true # - ALPINE_CORS_MAX_AGE=3600 # + # Optional logging configuration + # - LOGGING_LEVEL=INFO + # - LOGGING_CONFIG_PATH=logback.xml + # # Optional metrics properties # - ALPINE_METRICS_ENABLED=true # - ALPINE_METRICS_AUTH_USERNAME= diff --git a/docs/_docs/getting-started/monitoring.md b/docs/_docs/getting-started/monitoring.md index 5873f575c5..84043ac8d4 100644 --- a/docs/_docs/getting-started/monitoring.md +++ b/docs/_docs/getting-started/monitoring.md @@ -30,6 +30,66 @@ acquired and used successfully. The check spans both connection pools (see [Conn } ``` +### Logging + +Logging of the API server is configured via [Logback]. All distributions of the API server ship with +a [default Logback configuration]. It defines the following behavior: + +1. Log messages from the embedded Jetty server to: + * `$HOME/.dependency-track/server..log` +2. Log messages from Dependency-Track and the underlying Alpine framework to: + * `$HOME/.dependency-track/dependency-track..log` + * Standard Output +3. Log security-related messages to: + * `$HOME/.dependency-track/dependency-track-audit..log` + * Standard Output +4. For log files: + * Create a new log file once the current one exceeds 10MB in size + * Retain a history of up to 9 files per log before overwriting them +5. Output logs in a human-friendly format + +> For containerized deployments, `$HOME` will refer to the `/data` directory. + +#### Custom Logging Configuration + +When operating Dependency-Track in container-centric environments, where logs are typically forwarded +from containers' standard output to a centralized log aggregator (e.g. ElasticSearch, OpenSearch, Splunk), +it is desirable to disable logging to disk, and even change the output to a more machine-readable format. + +Starting with Dependency-Track v4.9.0, it is possible to provide a custom Logback configuration, +and configure JSON as output format (powered by [logstash-logback-encoder]). + +An example configuration file for JSON logging to standard output ([`logback-json.xml`]) is included +in the API server container image, and can be enabled using the `LOGGING_CONFIG_PATH` environment variable: + +```shell +# (Other configuration options omitted for brevity) +docker run -it --rm \ + -e "LOGGING_CONFIG_PATH=logback-json.xml" \ + dependencytrack/apiserver:latest +``` + +Refer to the [logstash-logback-encoder documentation] for advanced customization details. + +In order to use a truly custom configuration file, it has to be mounted into the container, e.g.: + +```shell +# (Other configuration options omitted for brevity) +docker run -it --rm \ + -v "./path/to/logback-custom.xml:/etc/dtrack/logback-custom.xml:ro" \ + -e "LOGGING_CONFIG_PATH=/etc/dtrack/logback-custom.xml" \ + dependencytrack/apiserver:latest +``` + +For non-containerized distributions of the API server, a custom configuration file may be provided +via the `logback.configurationFile` JVM property: + +```shell +# (Other configuration options omitted for brevity) +java -Dlogback.configurationFile=/path/to/logback-custom.xml \ + -jar dependency-track-apiserver.jar +``` + ### Metrics The API server can be configured to expose system metrics via the Prometheus [text-based exposition format]. @@ -275,11 +335,16 @@ An [example dashboard] is provided as a quickstart. Refer to the [Grafana docume [community integrations]: {{ site.baseurl }}{% link _docs/integrations/community-integrations.md %} [Configuration]: {{ site.baseurl }}{% link _docs/getting-started/configuration.md %} [Connection Pooling]: {{ site.baseurl }}{% link _docs/getting-started/database-support.md %}#connection-pooling +[default Logback configuration]: https://github.com/DependencyTrack/dependency-track/blob/master/src/main/docker/logback.xml [dependency-track-exporter]: https://github.com/jetstack/dependency-track-exporter [example dashboard]: {{ site.baseurl }}/files/grafana-dashboard.json [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 +[Logback]: https://logback.qos.ch/ +[`logback-json.xml`]: https://github.com/DependencyTrack/dependency-track/blob/master/src/main/docker/logback-json.xml +[logstash-logback-encoder]: https://github.com/logfellow/logstash-logback-encoder +[logstash-logback-encoder documentation]: https://github.com/logfellow/logstash-logback-encoder/tree/logstash-logback-encoder-7.3#loggingevent-fields [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/ diff --git a/src/main/docker/docker-compose.yml b/src/main/docker/docker-compose.yml index 4fbff971c4..b1d298f266 100644 --- a/src/main/docker/docker-compose.yml +++ b/src/main/docker/docker-compose.yml @@ -77,6 +77,10 @@ services: # - ALPINE_CORS_ALLOW_CREDENTIALS=true # - ALPINE_CORS_MAX_AGE=3600 # + # Optional logging configuration + # - LOGGING_LEVEL=INFO + # - LOGGING_CONFIG_PATH=logback.xml + # # Optional metrics properties # - ALPINE_METRICS_ENABLED=true # - ALPINE_METRICS_AUTH_USERNAME=