Skip to content

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):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
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.