Database health checks

The GraphDB health check endpoint is at http://localhost:7200/repositories/myrepo/health.

Possible responses: HTTP status 200 (the repository is healthy), 206 (the repository needs attention but it is not something critical), 500 (the repository is inconsistent, i.e. some checks failed).

Possible values for health checks and their meaning

Value

Description

read-availability

Checks whether the repository is readable.

storage-folder

Checks if there are at least 20 megabytes writable left for the storage folder. The amount can be controlled with the system parameter health.minimal.free.storage.

long-running-queries

Checks if there are queries running longer than 20 seconds. The time can be controlled with the system parameter health.max.query.time.seconds. If a query is running for more than 20 seconds, it is either a slow one, or there is a problem with the database.

predicates-statistics

Checks if the predicate statistics contain correct values.

master-status

Checks whether the master is up and running, can access its workers, and the peers are not lagging. If there are non-readable workers, the status will be yellow. If there are workers that are off, the status will be red.

plugins

Provides aggregated health checks for the individual plugins.

Default health checks for the different GraphDB editions

Name

Free

SE

EE / Worker

EE / Master

read-availability

storage-folder

long-running-queries

predicates-statistics

master-status

plugins

Aggregated health checks

The aggregated GraphDB health checks include checks for dependent services and components as plugins and connectors.

Each connector plugin is reported independently as part of the composite “plugins” check in the repository health check. Each connector’s check is also a composite where each component is an individual connector instance.

The output may look like this:

{
    "name":"wine",
    "status":"green",
    "components":[
        {
            "name":"read-availability",
            "status":"green"
        },
        {
            "name":"storage-folder",
            "status":"green"
        },
        {
            "name":"long-running-queries",
            "status":"green"
        },
        {
            "name":"predicates-statistics",
            "status":"green"
        },
        {
        "name":"plugins",
        "status":"yellow",
        "components":[
            {
            "name":"elasticsearch-connector",
            "status":"green",
            "components":[

            ]
            },
            {
            "name":"lucene-connector",
            "status":"yellow",
            "components":[
                {
                    "name":"my_index",
                    "status":"green",
                    "message":"query took 0 ms, 5 hits"
                },
                {
                    "name":"my_index2",
                    "status":"yellow",
                    "message":"query took 0 ms, 0 hits"
                }
            ]
            },
            {
            "name":"solr-connector",
            "status":"yellow",
            "components":[
                {
                    "name":"my_index",
                    "status":"green",
                    "message":"query took 7 ms, 5 hits"
                },
                {
                    "name":"my_index2",
                    "status":"yellow",
                    "message":"query took 5 ms, 0 hits"
                }
            ]
            }
        ]
    }
    ]
}

An individual check run involves sending a query for all documents to the connector instance, and the result is:

  • green - more than zero hits

  • yellow - zero hits or failing shards (shards check only for Elasticsearch)

  • red - unable to execute query

In all of these cases, including the green status, there is also a message providing details, e.g., “query took 15 ms, 5 hits, 0 failing shards”.

Running health checks

To run the health checks for a particular repository, in the example myrepo, execute the following command:

curl 'http://localhost:7200/repositories/myrepo/health?'

Running legacy health checks

If you have been relying on the health check format from a version of GraphDB prior to 9.0, you can add the old parameter to get results in the old health check format:

curl 'http://localhost:7200/repositories/myrepo/health?old'
Parameter: checks (By default all checks are run)
Behavior: Run only the specified checks.
Accepts multiple values: True.
Values: read-availability, storage-folder, long-running-queries, predicates-statistics, master-status.
curl 'http://localhost:7200/repositories/myrepo/health?old&checks=<value1>&checks=<value2>'
  • an example output for a healthy repository with HTTP status 200:

{
    "predicates-statistics": "OK",
    "long-running-queries": "OK",
    "read-availability": "OK",
    "status": "green",
    "storage-folder": "OK"
}
  • an example output for an unhealthy repository with HTTP status 500:

{
    predicates-statistics: "OK",
    long-running-queries: "OK",
    read-availability: "OK",
    storage-folder: "UNHEALTHY: Permission denied java.io.IOException: Permission denied",
    status: "red"
}

The status field in the output means the following:

  • green - all is good;

  • yellow - the repository needs attention;

  • red - the repository is inconsistent in some way.