Configuring observability

Dependency-Track exposes health check and metrics endpoints via a dedicated management server, running on a separate port independently of the main app server.

Tip

All observability-related configuration properties are documented in the configuration reference, under the Observability category.

Configuring Kubernetes health probes

The management server exposes health check endpoints that follow the MicroProfile Health specification and map directly to Kubernetes probe types.

Add the following probes to your Deployment manifest, adjusting the port if you changed dt.management.port (default: 9000):

containers:
  - name: apiserver
    livenessProbe:
      httpGet:
        path: /health/live
        port: 9000
      initialDelaySeconds: 15
      periodSeconds: 10
    readinessProbe:
      httpGet:
        path: /health/ready
        port: 9000
      initialDelaySeconds: 15
      periodSeconds: 10
    startupProbe:
      httpGet:
        path: /health/started
        port: 9000
      initialDelaySeconds: 10
      failureThreshold: 30
      periodSeconds: 5

The startup probe at /health/started reports per-task progress while init tasks run, then turns healthy once the main server is ready. The aggregate endpoint /health returns the combined status of all checks.

Enabling Prometheus metrics scraping

Metrics are disabled by default. Enable them via dt.metrics.enabled:

dt.metrics.enabled=true

Once enabled, metrics are served at /metrics on the management port in the Prometheus text exposition format.

If you want to protect the endpoint with HTTP Basic authentication, set both dt.metrics.auth.username and dt.metrics.auth.password.

Add a scrape target to your Prometheus configuration:

scrape_configs:
  - job_name: dependency-track
    metrics_path: /metrics
    static_configs:
      - targets:
          - "apiserver:9000"
    # Uncomment if you enabled authentication:
    # basic_auth:
    #   username: "metrics"
    #   password: "changeme"

Visualizing metrics with Grafana

The project does not publish Grafana dashboards as supported artifacts. The dashboards the maintainers use for their own purposes live in the API server repository.

Warning

These dashboards are not supported and not guaranteed to be up-to-date with the metrics exposed by the current release. Panels may reference metrics that were renamed or removed.

Use them as a starting point. Build your own dashboards tailored to the metrics and alerting needs of your deployment.

Adjusting log levels

By default, Dependency-Track logs at INFO level for application loggers and WARN for all others. To troubleshoot a specific area, raise the log level for the relevant logger:

dt.logging.level."org.dependencytrack"=DEBUG

The special logger name ROOT applies to all loggers that are not explicitly configured:

dt.logging.level."ROOT"=ERROR

Refer to the environment variable mapping documentation for how to express these properties as environment variables.

Changing the logging configuration

Dependency-Track uses Logback for logging. The default configuration writes logs to stdout in a human-readable text format.

The container images also ship a JSON-formatted configuration at logback-json.xml, located in the app's working directory. JSON output is typically the better choice when shipping logs to a centralized log management system such as Splunk, Elasticsearch, or Loki. Activate it by pointing Logback at that file:

EXTRA_JAVA_OPTIONS="-Dlogback.configurationFile=logback-json.xml"

Set the flag via EXTRA_JAVA_OPTIONS so the container appends it to the JVM command line. See the JVM options reference for details.

To use a fully custom configuration, mount your own file into the container and reference it the same way, with either a relative path (resolved against the working directory) or an absolute path. The Logback configuration manual describes the file format.