Doctor Service

The purpose of the doctor service is to do a complete check of the services status in the project in which is deployed.

To do this, the service will call a specific route, the /-/check-up one.

danger

NB. the Doctor service is the only one who can call the /-/check-up route of services.

NEVER call the /-/check-up route of a service from the checkUpHandler of another service, the risk is to start a /-/check-up calls loop.

Deploy

The Doctor Service is easily deployable on every project by using the Console. You just need to add the service and configure it's configuration file.

The Doctor Service is simply based on one file, the configurations file. With the configurations file it's easy to manage all services to check-up. Specifically, the Doctor allows the user to do two things:

1. check-up all services in the configurations file by simply call the root path (e.g. http://api.foobar.it/playground/check-up);
2. check-up a subgroup of services by specify the tag → all services can have a list of tags (optional) and the Doctor will expose a dedicated route for each tag, that will return the check-up of services with that tag.

danger

NB. all the services call by the Doctor MUST have the /-/check-up route.

Configuration

Following an overview of the steps that you have to do to integrate the Doctor Service in your project:

1. Build the configurations file of the Doctor Service
2. Create the service using the API Console
3. Configure the Advanced configurations
4. Check-up'em all

note

The following example is based on a Playground project.

1. Build the configurations file

As previously said, the Doctor Service just needs a configurations file that has to follow this schema:

{
  type: 'array',
  items: {
    type: 'object',
    required: ['hostname'],
    properties: {
      hostname: { type: 'string' },
      tags: {
        type: 'array',
        items: {
          type: 'string',
        },
      },
      options: {
        type: 'object',
        properties: {
          prefix: {
            type: 'string',
            pattern: '^(\\/.*[A-Za-z1-9])?$',
            default: '',
          },
          port: {
            type: 'number',
            default: 80,
          },
          protocol: {
            type: 'string',
            default: 'http',
            enum: ['http', 'https'],
          },
        },
        default: {},
        additionalProperties: false,
      },
    },
    additionalProperties: false,
  },
}

As specified into the schema, the tags property is optional → a Doctor Service can have all services without tags and it still works on the root path. Additionally, it is possible to specify an options object in order to manage further how the /-/check-up route is called.
The following options can be provided:

• prefix: to specify a prefix to append before /-/check-up route. Default is an empty string.
• protocol: to specify a different protocol. Only http or https can be specified. Default is http.
• port: to specify a different port. Default is 1.

In the following example we will set just one tag, the core tag, just for core services:

[
  { "hostname": "auth-service", "tags": ["core"] },
  { "hostname": "cms-backend", "tags": ["core"] },
  { "hostname": "crud-service", "tags": ["core"] },
  { "hostname": "microservice-gateway", "tags": ["core"] },
  { "hostname": "swagger-aggregator", "tags": ["core"] },
  { "hostname": "v1-adapter", "tags": ["core"], "options": { "prefix": "/api/v2", "port": 8888, "protocol": "https" } },
  { "hostname": "node-service" },
  { "hostname": "angular-service" },
  { "hostname": "react-service" },
  { "hostname": "java-service" },
]

This way, for swagger-aggregator service, doctor-service will call the /-/check-up route at https://swagger-aggregator/-/check-up, instead for v1-adapter service, doctor-service will call the /-/check-up route at https://v1-adapter:8888/api/v2/-/check-up.

In this way, we should have the following routes:

• baseUrl/check-up → should return the check-up response of all services
• baseUrl/check-up/core → should return the check-up response just of services with the core tag

The configurations file is ready, let's continue.

2. Doctor Service creation on the API Console

Now it's time to create the real service.

Following the steps to create the services:

1. Open the API Console and choose the project
2. Click, on the left, on Microservices
3. Click on the Create a Microservice button
4. Search for doctor service and click on the Doctor Service plugin button
5. Fill the form:
   • Name: the name of the service (in the example is doctor-service)
   • Description: the description of the service
6. Click on the Create button
7. Scroll down and click on Add a configuration
8. Edit the environment variable SERVICES_LIST_PATH and set /home/node/app/config/services.json
9. Fill the form:
   • Configuration name: The name of the configuration (e.g. doctor-service-config)
   • Runtime Mount Path: The folder path where will be created the configuration. Set to /home/node/app/config/
10. Click on Add file, fill Name with services.json and click on Create
11. Insert the previously created configurations file into the just created file
12. Save (Commit and generate button)

3. Check-up'em all

Now the /check-up route of the project is ready to be called like this:

• projectBaseUrl/check-up → for a check-up of all services
• projectBaseUrl/check-up/core → for a check-up of core services only (in this example)