Check health and follow a run

Goal

For platform teams. In this task you check that the control plane is up and ready. You set up probes for it. You send its traces, metrics and logs to a collector. You also find the trace of one run.

Before you start

• Know the address of the management port of the control plane. The health paths are on that port, and not on the port of the API. The default port of the API is 8080, and the default port of the management port is 8081. The settings are server.port and management.server.port.
• For the telemetry, you need a collector that accepts OTLP over HTTP. OTLP is the protocol of OpenTelemetry. Settings reference lists the settings.

Steps

Check the three health paths

The control plane answers GET /health, GET /health/liveness and GET /health/readiness. The paths need no token. The answer is one word in JSON. UP is HTTP status 200, and DOWN is HTTP status 503.

Set the variable JOOMIZ_MANAGEMENT_URL to the address of the management port of your control plane. Then call each path:

curl -s -w '\nHTTP %{http_code}\n' "$JOOMIZ_MANAGEMENT_URL/health"

{"status":"UP"}
HTTP 200

{"status":"UP"}
HTTP 200

{"status":"UP"}
HTTP 200

When the database stops, /health and /health/readiness answer DOWN with the status 503. The process still runs, so liveness stays UP. The control plane keeps the result of the check of the signing keys for 30 seconds. So a change at the identity provider shows after a short time:

{"status":"DOWN"}
HTTP 503

{"status":"UP"}
HTTP 200

{"status":"DOWN"}
HTTP 503

The answer holds the word and nothing else. It does not say which check failed. Read the log of the control plane for the cause.

The page Overview of the Platform dashboard shows the result of /health/readiness as Up, Down or Unknown. Use the Platform dashboard describes the page.

Set up probes

Use liveness to decide when to restart the process. Use readiness to decide when to send requests to it. This is a probe for a Kubernetes deployment, with the default management port:

livenessProbe:
  httpGet:
    path: /health/liveness
    port: 8081
readinessProbe:
  httpGet:
    path: /health/readiness
    port: 8081

Do not use /health as a liveness probe. A database that is down would then restart a process that is healthy.

Send traces, metrics and logs to a collector

The control plane sends nothing until you set an address. Set the base address of your collector:

export JOOMIZ_TELEMETRY_OTLP_ENDPOINT=https://otel-collector.example.com:4318

The address must be an absolute http or https address with a host. It must have no user name, no password, no query and no fragment. The control plane adds the paths /v1/traces, /v1/logs and /v1/metrics. An address that does not follow these rules stops the start of the control plane, and the error names the setting.

The setting joomiz.telemetry.sampling.probability is the share of traces that the control plane keeps, from 0 to 1. The default is 1, so every trace is kept. If the collector is slow or down, the control plane drops the data and keeps running. The service name is joomiz-control-plane.

What the control plane sends:

• Traces. One span for each request to the API, for example http post /apply. One span for each type of resource of a run, named group <kind>/<type>. One span for each call to a provisioner, named like provisioner plan managed-resource/postgres. Each check of a slow operation starts a trace of its own, with a span named like poll managed-resource/postgres.
• Metrics. The usual metrics of the Java process, of the HTTP requests and of the database connections. The control plane also sends the metrics in the next table. It sends them about once a minute.
• Logs. The log lines of the control plane. Each line has the ID of its trace and the ID of its span.

The spans of a run carry these attributes: joomiz.run.id, joomiz.run.kind, joomiz.application.id, joomiz.environment and joomiz.revision.id. The span of a type of resource adds joomiz.group.kind, joomiz.group.type, the first 20 resource IDs in joomiz.resource.ids, and joomiz.outcome. The span of a call to a provisioner adds joomiz.provisioner.kind, joomiz.provisioner.type, joomiz.provisioner.operation, joomiz.operation.id and the status of the answer.

Find the trace of one run

When the control plane sends traces, each run has a trace ID. joomiz runs show prints it on the line trace:

joomiz runs show 7bb5b27f-a1f9-49ae-9a5b-daaa715aedcf

run 7bb5b27f-a1f9-49ae-9a5b-daaa715aedcf
  kind:         apply
  application:  quick-start-shop (75c7e55d-aaa1-48ab-bc58-d7ca3b44b68c)
  environment:  test
  caller:       owner:finance-team
  status:       succeeded
  started:      2026-10-28T19:22:00.755Z
  finished:     2026-10-28T19:22:00.791Z
  duration:     36ms
  revision:     defd57f2-d868-4b99-81ae-f74c99fc1fa1
  plan:         66a4d0e7-7191-4f6a-96ee-cf3f0277a99c
  apply:        0a6dc56b-2f75-4936-bb99-a0d52edeb311
  trace:        8f67f129ad08209b1f8df29d75874a05
groups:
  managed-resource/postgres     succeeded  15ms  created 1, updated 0, removed 0
  target/cloud-foundry-space    succeeded  12ms  created 1, updated 0, removed 0
  deployment/cloud-foundry-app  succeeded  8ms  created 1, updated 0, removed 0

The line caller says which role started the run. This documentation says acted as. The page of the run in the dashboard shows the same ID as Trace id. The audit events of the apply carry it in the field traceId. Search your tracing tool for the ID, or for the attribute joomiz.run.id. The run ID is in joomiz runs, so you can go from a run to its trace and back.

The trace of a run shows the types of resources. It also shows the calls to each provisioner, with their time and status. So you see where a slow run spent its time.

A run on a control plane with no collector address has no trace ID. The line trace is not printed.

Check

• The three health paths answer {"status":"UP"} with the status 200.
• Your probes name the paths and the port that you checked.
• After you set JOOMIZ_TELEMETRY_OTLP_ENDPOINT and run an apply, your collector receives traces within seconds, and metrics within a few minutes.
• joomiz runs show of that apply prints a trace line.

Troubleshooting

Next

Look up every setting in the Settings reference.