Monitor Server Health¶

The Carbon Health Check API can be used to check the health of WSO2 Identity Server. The sections below guide you through using this API.

Configure the API¶

This feature is disabled by default. To enable the API, add the following configurations to the deployment.toml file in <IS_HOME>/repository/conf.

[carbon_health_check]
enable= true

There are two health checkers that will be enabled when you enable health checkers using the above global configuration.

• DataSource Health Checker
• UserStore Health Checker

DataSource health checker¶

This health checker returns the status of the datasources available in the system. You can configure the datasources to be monitored by adding the following configuration to the deployment.toml file found in the <IS_HOME>/repository/conf folder.

[carbon_health_check.health_checker.data_source_health_checker.properties]
'monitored.datasources' = "jdbc/WSO2CarbonDB,jdbc/WSO2UM_DB,jdbc/SHARED_DB"

To provide an indication about the datasource connection pool usage, use the following configuration in thedeployment.toml file.

[carbon_health_check.health_checker.data_source_health_checker]
pool_usage_limit_percentage = "20"

Userstore health checker¶

This health checker returns the status of the userstores available in the system. You can configure the userstores to be monitored by adding the following configuration to the deployment.toml file found in the <IS_HOME>/repository/conf folder.

[carbon_health_check.health_checker.super_tenant_health_checker.properties]
'monitored.user.stores' = "primary" 

Invoke the API¶

This is an open API which should ideally be blocked at the load balancer level. To invoke it, start WSO2 Identity Server and send a GET request to the health check API. A sample cURL command is shown below.

curl -k -v https://{hostname}:{port}/api/health-check/v1.0/health

If the request is successful, you will recieve a 200 OK response (similar to the one shown below) with a list of health check results.

{  
   "health":[  
      {  
         "key":"jdbc/WSO2CarbonDB.active.connection.count",
         "value":"1"
      },
      {  
         "key":"bpsds.active.connection.count",
         "value":"1"
      },
      {  
         "key":"jdbc/WSO2MetricsDB.connectivityTime.ms",
         "value":"81"
      },
      {  
         "key":"jdbc/WSO2MetricsDB.active.connection.count",
         "value":"1"
      },
      {  
         "key":"jdbc/WSO2CarbonDB.connectivityTime.ms",
         "value":"0"
      },
      {  
         "key":"bpsds.connectivityTime.ms",
         "value":"0"
      }
   ]
}

• The active.connection.count parameter reflects the number of connections that are active.

• ConnectivityTime refers to the the duration of the connection.

Error responses¶

The following responses are possible error responses that you may receive.

The code block below shows a sample 503 Unavailable response with an array of errors.

{  
   "errors":[  
      {  
         "code":"HC_00001",
         "message":"Error while getting database connection for datasource: jdbc/DISCONNECTED",
         "description":"Network is unreachable (connect failed)"
      },
      {  
         "code":"HC_00003",
         "message":"Error while checking health of USM with domain: SEC",
         "description":"Access denied for user 'roott'@'localhost' (using password: YES)"
      }
   ]
}

• A health checker can be enabled or disabled using the enable attribute of each health checker.

  [carbon_health_check.health_checker.data_source_health_checker]
  enable =false
  
  [carbon_health_check.health_checker.super_tenant_health_checker]
  enable =false

• The execution order in which the health checkers are executed can be configured using the order attribute.

  [carbon_health_check.health_checker.data_source_health_checker]
  order = "97"
  
  [carbon_health_check.health_checker.super_tenant_health_checker]
  order = "98"

• The properties configured under each health checker will be available for each heath checker at runtime.

Add new health checkers¶

To add a new health checker, you can implement the HealthChecker API and register the health checker as an OSGI service.
To deploy it, copy the .jar file to the <IS_HOME>/repository/component/lib/ directory or the OSGI bundle and paste it in the <IS_HOME>/repository/component/dropins/ directory.

Then register the new health checker as shown below in the deployment.toml file if needed.

[[health_checker]]
name = "customChecker" 
order="87" 
[health_checker.properties] 
property1 = "property-1-value"
property2 = "property-2-value" 

[carbon_health_check] enable=
true

[carbon_health_check.health_checker.data_source_health_checker]
pool_usage_limit_percentage = "20"
enable = true
order = "99"

[carbon_health_check.health_checker.super_tenant_health_checker]
enable = true
order = "88"

[carbon_health_check.health_checker.data_source_health_checker.properties]
'monitored.datasources' = "jdbc/WSO2CarbonDB,jdbc/WSO2UM_DB,jdbc/SHARED_DB"

[carbon_health_check.health_checker.super_tenant_health_checker.properties]
'monitored.user.stores' = "primary"

[[health_checker]] 
name = "customChecker" 
order = "87"
[health_checker.properties] 
property1 = "property-1-value" 
property2 = "property-2-value"