Database health checks

The GraphDB health check endpoint is at http://localhost:7200/repositories/<repo_name>/health.

Possible responses:

  • HTTP status 200: the repository is healthy

  • HTTP status 206: the repository needs attention but it is not something critical

  • HTTP status 500: the repository is inconsistent, i.e., some checks failed

Possible values for health checks and their meaning

Value

Description

repository-state

Checks the state of the repository. Returns message RUNNING, STARTING, or INACTIVE. RUNNING and INACTIVE result in green health, and all other states result in yellow health.

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.

plugins

Provides aggregated health checks for the individual 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 cURL command:

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

Running passive health checks

In passive check mode, the repository state will be compared to determine if it is safe to do an active check.

  • Immediate passive: Activated by passing ?passive to the health endpoint.

    • If the state is RUNNING, do an active check.

    • If the state is something else (e.g., INACTIVE or STARTING), return immediately with a simple check that only lists the state.

  • Delayed passive (if needed): Tries to get the repository for up to N seconds. Activated by passing ?passive=N to the endpoint, where N is a timeout in seconds.

    • If successful: Runs an active check.

    • If timeout: Return with a simple check that only lists the state.

Example health from a passive check (repo has never requested since GraphDB restart):

{
   "status" : "green",
   "components" : [
      {
         "status" : "green",
         "name" : "repository-state",
         "message" : "INACTIVE"
      }
   ],
   "name" : "test"
}

Example health from a passive check (repo is currently initializing):

{
   "status" : "yellow",
   "components" : [
      {
         "status" : "yellow",
         "name" : "repository-state",
         "message" : "STARTING"
      }
   ],
   "name" : "test"
}

Note

From GraphDB 9.7.x onwards, legacy health checks are no longer supported.