Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Amazon IoT Greengrass Version 1 entered the extended life phase on June 30, 2023. For more information, see the Amazon IoT Greengrass V1 maintenance policy. After this date, Amazon IoT Greengrass V1 won't release updates that provide features, enhancements, bug fixes, or security patches. Devices that run on Amazon IoT Greengrass V1 won't be disrupted and will continue to operate and to connect to the cloud. We strongly recommend that you migrate to Amazon IoT Greengrass Version 2, which adds significant new features and support for additional platforms.

Calling the local health check API

Amazon IoT Greengrass contains a local HTTP API that provides a snapshot of the current state of local worker processes that were started by Amazon IoT Greengrass. This snapshot includes user-defined Lambda functions and system Lambda functions. System Lambda functions are part of the Amazon IoT Greengrass Core software. They run as local worker processes on the core device and manage operations such as message routing, local shadow sync, and automatic IP address detection.

The health check API supports the following requests:

Requests are sent locally on the device and don't require an internet connection.

Get health information for all workers

Send a GET request to get health information about all running workers.

GET http://localhost:port/2016-11-01/health/workers

Example request

The following example curl request gets health information for all workers.

curl http://localhost:8000/2016-11-01/health/workers

JSON Response

This request returns an array of worker health information objects.

Example response

The following example response lists health information objects for all worker processes that were started by Amazon IoT Greengrass.

[
    {
      "FuncArn": "arn:aws:lambda:::function:GGShadowService:1",
      "WorkerId" : "65515053-2f70-43dc-7cc0-1712bEXAMPLE",
      "ProcessId": "1234",
      "WorkerState": "Waiting"
    },
    {
      "FuncArn": "arn:aws:lambda:::function:GGSecretManager:1",
      "WorkerId": "a9916cc2-1b4d-4f0e-4b12-b1872EXAMPLE",
      "ProcessId": "9798",
      "WorkerState": "Waiting"
    },
    {
      "FuncArn": "arn:aws:lambda:us-west-2:123456789012:function:my-lambda-function:3",
      "WorkerId": "2e6f785e-66a5-42c9-67df-42073EXAMPLE",
      "ProcessId": "11837",
      "WorkerState": "Waiting"
    },
    ...
]

Get health information about specified workers

Send a POST request to get health information about specified workers. Replace port with the port number of the IPC. The default is 8000.

POST http://localhost:port/2016-11-01/health/workers

Example request

The following example curl request gets health information for specified workers.

curl --data "@body.json" http://localhost:8000/2016-11-01/health/workers

Here's an example body.json request body:

{
    "FuncArns": [
        "arn:aws:lambda:::function:GGShadowService:1",
        "arn:aws:lambda:us-west-2:123456789012:function:my-lambda-function:3"
    ]
}

The request body contains a FuncArns array.

JSON Response

This request returns a Workers array and an InvalidArns array.

Example response

The following example response lists health information objects for the specified workers.

{ 
    "Workers": [
        {
            "FuncArn": "arn:aws:lambda:::function:GGShadowService:1",
            "WorkerId" : "65515053-2f70-43dc-7cc0-1712bEXAMPLE",
            "ProcessId": "1234",
            "WorkerState": "Waiting"
        },
        {
            "FuncArn": "arn:aws:lambda:us-west-2:123456789012:function:my-lambda-function:3",
            "WorkerId": "2e6f785e-66a5-42c9-67df-42073ESAMPLE",
            "ProcessId": "11837",
            "WorkerState": "Waiting"
        }
    ],
    "InvalidArns" : [
        "some-malformed-arn", 
        "arn:aws:lambda:us-west-2:123456789012:function:some-unknown-function:1"
    ]
}

This request returns the following errors:

Worker health information

A health information object contains the following properties:

System Lambda functions

You can request health information for the following system Lambda functions: