Status API: services endpoint

The /services endpoints provide machine-consumable information about running services. They are intended for scripting and integration with other services.

GET /status/v1/services

Use the /services endpoint to retrieve the statuses of PE services on a specified port.

The content type for this endpoint is application/json; charset=utf-8.

Request format

The request accepts the following parameters:

Parameter Value
level How thorough of a check to run. Set to critical, debug, or info (default).
timeout Specified in seconds; defaults to 30.

The Status API endpoints return the status of services based on the port. Services available on each port are as follows:

Port Service(s)
4433
  • RBAC
  • Activity Service
  • Classifier
8140
  • Code Manager
  • file sync client
  • file sync storage
  • Puppet Server
8143
  • orchestrator
  • pcp broker
  • pcp broker v2
8081
  • PuppetDB
For example, this request fetches the info status of all the console services running on port 4433, which are RBAC, the Activity Service, and the Classifier. 
curl --insecure -H "X-Authentication: ALmWRLko6nJhi7bRQX4Qe-hOp07d4ZqDvHcferiK8lK8" \
--header "Content-Type: application/json" \
--request GET -G "https://puppet.status.example:4433/status/v1/services" \
--data-urlencode '{"level": "info", "timeout": "30"}'

Response format

The response is a JSON object that lists details about the services, using the following keys:

Key Definition
service_version Package version of the JAR file containing a given service.
service_status_version The version of the API used to report the status of the service.
detail_level The level of detail shown. One of critical, debug, or info.
state The current state of the service. One of running, error, or unknown.
status An object with the service’s status details. Usually only relevant for error and unknown states.
active_alerts An array of objects containing severity and a message about your replication from pglogical if you have replication enabled; otherwise, it's an empty array.
For example, the response for a request to console services on port 4433 returns information about RBAC, the Activity Service, and the Classifier:
{
  "activity-service": {
    "service_version": "2019.8.0.0",
    "service_status_version": 1,
    "detail_level": "info",
    "state": "running",
    "status": {
      "db_up": true,
      "db_pool": {
        "state": "ready"
      },
      "replication": {
        "mode": "none",
        "status": "none"
      }
    },
    "active_alerts": []
  },
  "classifier-service": {
    "service_version": "2019.8.0.0",
    "service_status_version": 1,
    "detail_level": "info",
    "state": "running",
    "status": {
      "db_up": true,
      "db_pool": {
        "state": "ready"
      },
      "rbac_up": true,
      "activity_up": true,
      "replication": {
        "mode": "none",
        "status": "none"
      }
    },
    "active_alerts": []
  },
  "rbac-service": {
    "service_version": "2019.8.0.0",
    "service_status_version": 1,
    "detail_level": "info",
    "state": "running",
    "status": {
      "db_up": true,
      "db_pool": {
        "state": "ready"
      },
      "activity_up": true,
      "replication": {
        "mode": "none",
        "status": "none"
      }
    },
    "active_alerts": []
  },
  "status-service": {
    "service_version": "1.1.0",
    "service_status_version": 1,
    "detail_level": "info",
    "state": "running",
    "status": {},
    "active_alerts": []
  }
}

Response codes

The server uses the following response codes:
  • 200 if and only if all services report a status of running
  • 503 if any service’s status i unknown or error
  • 400 if a level parameter is set but is invalid (not critical, debug, or info)

GET /status/v1/services/<SERVICE NAME>

Use the /services/<SERVICE NAME> endpoint to retrieve the status of one particular PE service.

The content type for this endpoint is application/json; charset=utf-8.

Request format

This endpoint fetches the status for any one of the following services:
  • activity-service (4433)
  • classifier-service (4433)
  • code-manager-service (8140)
  • orchestrator-service (8143)
  • server (8140)
  • puppetdb-service (8081)

You must also specify the service's port in the request.

The request accepts the following parameters:

Parameter Value
level How thorough of a check to run. Set to critical, debug, or info (default).
timeout Specified in seconds; defaults to 30.
For example, this request fetches info level status information about RBAC:
curl --insecure -H "X-Authentication: ALmWRLko6nJhi7bRQX4Qe-hOp07d4ZqDvHcferiK8lK8" \
--header "Content-Type: application/json" \
--request GET -G "https://puppet.example.com:4433/status/v1/services/rbac-service"
--data-url-encode '{"level": "info", "timeout": "30"}'

Response format

The response is a JSON object that lists details about the service, using the following keys:

Key Definition
service_version Package version of the JAR file containing a given service.
service_status_version The version of the API used to report the status of the service.
detail_level The level of detail shown. One of critical, debug, or info.
state The current state of the service. One of running, error, or unknown.
status An object with the service’s status details. Usually only relevant for error and unknown states.
active_alerts An array of objects containing severity and a message about your replication from pglogical if you have replication enabled; otherwise, it's an empty array.

For example, this response returned information about the RBAC service. 

{"rbac-service": {"service_version": "1.8.11-SNAPSHOT",
                  "service_status_version": 1,
                  "detail_level": "info",
                  "state": "running",
                  "status": {
                    "activity_up": true,
                    "db_up": true,
                    "db_pool": { "state": "ready" },
                    "replication": { "mode": "none", "status": "none" }
                  },
                  "active_alerts": [],
                  }

Response codes

The server uses the following response codes:
  • 200 if and only if all services report a status of running
  • 503 if any service’s status i unknown or error
  • 400 if a level parameter is set but is invalid (not critical, debug, or info)

  • 404 if no service named <SERVICE NAME> is found