Metadata endpoints (#3100)
All apps have some fairly common metadata endpoints. We should standardize these endpoints to make it easier to monitor and manage our apps.
openAPI spec
The recommended libraries to use for these endpoints are:
Base path
The base path for these endpoints should be /health.
However, there are cases where the base path can be different but all metadata endpoints must share the same base path.
Metrics endpoint
Metrics should be exposed at /metrics.
This endpoint is required for all apps.
This endpoint should return a list of metrics in the Prometheus exposition format v0.0.4 or above.
If further format is supported this should be done with subpaths, for example /metrics/json.
Up endpoint
The up endpoint should be exposed at /up and return a json with some information about the app.
This endpoint is required for all apps.
For example:
{
"status": "up",
"version": "1.0.0",
"commit": "a1b2c3d4",
"build_date": "2025-03-05T14:00:00Z",
"region": "us"
}
Here's the standard information currently used for Konnect:
{
"server_timestamp": "2025-03-05T14:00:00Z",
"service_info": {
"foo": "bar"
},
"env": "prod",
"geo": "us",
"region": "us-west",
"service_name": "my-service",
"service_version": "1.0.0"
}
Probes endpoints
In line with Kubernetes we support 3 probes:
/probes/liveness - This endpoint should return a 200 status code if the app is healthy./probes/readiness - This endpoint should return a 200 status code if the app is ready to receive traffic./probes/startup - This endpoint should return a 200 status code if the app is ready to start receiving traffic.
/probes/liveness and /probes/readiness is strongly recommended for all apps.
/probes/startup only is to be used for apps that have a long startup time and need to separate this from liveness.
For more details on how to implement these probes, please refer to the Kubernetes documentation linked previously.
It is highly recommended for apps to start returning non 200 status code on /probes/readiness immediately after initiating shutdown and to leave a short grace period to allow systems to propagate the change of state.
In the absence of probes endpoints, users should fall back to the /up endpoint to determine app health.
Dependencies endpoint
/dependencies This endpoint should return a list of dependencies and their status.
It's optional for all apps.
If the endpoint exists it should return a json with the following format:
{
"status": "up",
"dependencies": {
"postgres": {
"name": "postgres",
"type": "soft",
"status": "up"
},
"redis": {
"name": "redis",
"type": "hard",
"status": "down"
}
}
}
Status can be up, down, degraded, unknown.
unknown should be used when the app doesn't determine the status of the dependency.
degraded should be used when a "soft" dependency is down.
Type can be hard or soft. Hard dependencies are required for the app to function, soft dependencies are not.
It is strongly discouraged to use this endpoint for health checks. Because computing this status may be expensive and slow.