github.com/outbrain/consul@v1.4.5/website/source/api/health.html.md (about)

     1  ---
     2  layout: api
     3  page_title: Health - HTTP API
     4  sidebar_current: api-health
     5  description: |-
     6    The /health endpoints query health-related information for services and checks
     7    in Consul.
     8  ---
     9  
    10  # Health HTTP Endpoint
    11  
    12  The `/health` endpoints query health-related information. They are provided
    13  separately from the `/catalog` endpoints since users may prefer not to use the
    14  optional health checking mechanisms. Additionally, some of the query results
    15  from the health endpoints are filtered while the catalog endpoints provide the
    16  raw entries.
    17  
    18  ## List Checks for Node
    19  
    20  This endpoint returns the checks specific to the node provided on the path.
    21  
    22  | Method | Path                         | Produces                   |
    23  | ------ | ---------------------------- | -------------------------- |
    24  | `GET`  | `/health/node/:node`         | `application/json`         |
    25  
    26  The table below shows this endpoint's support for
    27  [blocking queries](/api/index.html#blocking-queries),
    28  [consistency modes](/api/index.html#consistency-modes),
    29  [agent caching](/api/index.html#agent-caching), and
    30  [required ACLs](/api/index.html#acls).
    31  
    32  | Blocking Queries | Consistency Modes | Agent Caching | ACL Required             |
    33  | ---------------- | ----------------- | ------------- | ------------------------ |
    34  | `YES`            | `all`             | `none`        | `node:read,service:read` |
    35  
    36  ### Parameters
    37  
    38  - `node` `(string: <required>)` - Specifies the name or ID of the node to query.
    39    This is specified as part of the URL
    40  
    41  - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
    42    the datacenter of the agent being queried. This is specified as part of the
    43    URL as a query parameter.
    44  
    45  ### Sample Request
    46  
    47  ```text
    48  $ curl \
    49      http://127.0.0.1:8500/v1/health/node/my-node
    50  ```
    51  
    52  ### Sample Response
    53  
    54  ```json
    55  [
    56    {
    57      "ID": "40e4a748-2192-161a-0510-9bf59fe950b5",
    58      "Node": "foobar",
    59      "CheckID": "serfHealth",
    60      "Name": "Serf Health Status",
    61      "Status": "passing",
    62      "Notes": "",
    63      "Output": "",
    64      "ServiceID": "",
    65      "ServiceName": "",
    66      "ServiceTags": []
    67    },
    68    {
    69      "ID": "40e4a748-2192-161a-0510-9bf59fe950b5",
    70      "Node": "foobar",
    71      "CheckID": "service:redis",
    72      "Name": "Service 'redis' check",
    73      "Status": "passing",
    74      "Notes": "",
    75      "Output": "",
    76      "ServiceID": "redis",
    77      "ServiceName": "redis",
    78      "ServiceTags": ["primary"]
    79    }
    80  ]
    81  ```
    82  
    83  ## List Checks for Service
    84  
    85  This endpoint returns the checks associated with the service provided on the
    86  path.
    87  
    88  | Method | Path                         | Produces                   |
    89  | ------ | ---------------------------- | -------------------------- |
    90  | `GET`  | `/health/checks/:service`    | `application/json`         |
    91  
    92  The table below shows this endpoint's support for
    93  [blocking queries](/api/index.html#blocking-queries),
    94  [consistency modes](/api/index.html#consistency-modes),
    95  [agent caching](/api/index.html#agent-caching), and
    96  [required ACLs](/api/index.html#acls).
    97  
    98  | Blocking Queries | Consistency Modes | Agent Caching | ACL Required             |
    99  | ---------------- | ----------------- | ------------- | ------------------------ |
   100  | `YES`            | `all`             | `none`        | `node:read,service:read` |
   101  
   102  ### Parameters
   103  
   104  - `service` `(string: <required>)` - Specifies the service to list checks for.
   105    This is provided as part of the URL.
   106  
   107  - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
   108    the datacenter of the agent being queried. This is specified as part of the
   109    URL as a query parameter.
   110  
   111  - `near` `(string: "")` - Specifies a node name to sort the node list in
   112    ascending order based on the estimated round trip time from that node. Passing
   113    `?near=_agent` will use the agent's node for the sort. This is specified as
   114    part of the URL as a query parameter.
   115  
   116  - `node-meta` `(string: "")` - Specifies a desired node metadata key/value pair
   117    of the form `key:value`. This parameter can be specified multiple times, and
   118    will filter the results to nodes with the specified key/value pairs. This is
   119    specified as part of the URL as a query parameter.
   120  
   121  ### Sample Request
   122  
   123  ```text
   124  $ curl \
   125      http://127.0.0.1:8500/v1/health/checks/my-service
   126  ```
   127  
   128  ### Sample Response
   129  
   130  ```json
   131  [
   132    {
   133      "Node": "foobar",
   134      "CheckID": "service:redis",
   135      "Name": "Service 'redis' check",
   136      "Status": "passing",
   137      "Notes": "",
   138      "Output": "",
   139      "ServiceID": "redis",
   140      "ServiceName": "redis",
   141  	"ServiceTags": ["primary"]
   142    }
   143  ]
   144  ```
   145  
   146  ## List Nodes for Service
   147  
   148  This endpoint returns the nodes providing the service indicated on the path.
   149  Users can also build in support for dynamic load balancing and other features by
   150  incorporating the use of health checks.
   151  
   152  | Method | Path                         | Produces                   |
   153  | ------ | ---------------------------- | -------------------------- |
   154  | `GET`  | `/health/service/:service`   | `application/json`         |
   155  
   156  The table below shows this endpoint's support for
   157  [blocking queries](/api/index.html#blocking-queries),
   158  [consistency modes](/api/index.html#consistency-modes),
   159  [agent caching](/api/index.html#agent-caching), and
   160  [required ACLs](/api/index.html#acls).
   161  
   162  | Blocking Queries | Consistency Modes | Agent Caching        | ACL Required             |
   163  | ---------------- | ----------------- | -------------------- | ------------------------ |
   164  | `YES`            | `all`             | `background refresh` | `node:read,service:read` |
   165  
   166  ### Parameters
   167  
   168  - `service` `(string: <required>)` - Specifies the service to list services for.
   169    This is provided as part of the URL.
   170  
   171  - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
   172    the datacenter of the agent being queried. This is specified as part of the
   173    URL as a query parameter.
   174  
   175  - `near` `(string: "")` - Specifies a node name to sort the node list in
   176    ascending order based on the estimated round trip time from that node. Passing
   177    `?near=_agent` will use the agent's node for the sort. This is specified as
   178    part of the URL as a query parameter.
   179  
   180  - `tag` `(string: "")` - Specifies the tag to filter the list. This is
   181    specified as part of the URL as a query parameter. Can be used multiple times 
   182    for additional filtering, returning only the results that include all of the tag 
   183    values provided.
   184  
   185  - `node-meta` `(string: "")` - Specifies a desired node metadata key/value pair
   186    of the form `key:value`. This parameter can be specified multiple times, and
   187    will filter the results to nodes with the specified key/value pairs. This is
   188    specified as part of the URL as a query parameter.
   189  
   190  - `passing` `(bool: false)` - Specifies that the server should return only nodes
   191    with all checks in the `passing` state. This can be used to avoid additional
   192    filtering on the client side.
   193  
   194  ### Sample Request
   195  
   196  ```text
   197  $ curl \
   198      http://127.0.0.1:8500/v1/health/service/my-service
   199  ```
   200  
   201  ### Sample Response
   202  
   203  ```json
   204  [
   205    {
   206      "Node": {
   207        "ID": "40e4a748-2192-161a-0510-9bf59fe950b5",
   208        "Node": "foobar",
   209        "Address": "10.1.10.12",
   210        "Datacenter": "dc1",
   211        "TaggedAddresses": {
   212          "lan": "10.1.10.12",
   213          "wan": "10.1.10.12"
   214        },
   215        "Meta": {
   216          "instance_type": "t2.medium"
   217        }
   218      },
   219      "Service": {
   220        "ID": "redis",
   221        "Service": "redis",
   222        "Tags": ["primary"],
   223        "Address": "10.1.10.12",
   224        "Meta": {
   225          "redis_version": "4.0"
   226        },
   227        "Port": 8000,
   228        "Weights": {
   229          "Passing": 10,
   230          "Warning": 1
   231        }
   232      },
   233      "Checks": [
   234        {
   235          "Node": "foobar",
   236          "CheckID": "service:redis",
   237          "Name": "Service 'redis' check",
   238          "Status": "passing",
   239          "Notes": "",
   240          "Output": "",
   241          "ServiceID": "redis",
   242          "ServiceName": "redis",
   243  		"ServiceTags": ["primary"]
   244        },
   245        {
   246          "Node": "foobar",
   247          "CheckID": "serfHealth",
   248          "Name": "Serf Health Status",
   249          "Status": "passing",
   250          "Notes": "",
   251          "Output": "",
   252          "ServiceID": "",
   253          "ServiceName": "",
   254          "ServiceTags": []
   255        }
   256      ]
   257    }
   258  ]
   259  ```
   260  
   261  ## List Nodes for Connect-capable Service
   262  
   263  This endpoint returns the nodes providing a
   264  [Connect-capable](/docs/connect/index.html) service in a given datacenter.
   265  This will include both proxies and native integrations. A service may
   266  register both Connect-capable and incapable services at the same time,
   267  so this endpoint may be used to filter only the Connect-capable endpoints.
   268  
   269  | Method | Path                         | Produces                   |
   270  | ------ | ---------------------------- | -------------------------- |
   271  | `GET`  | `/health/connect/:service`   | `application/json`         |
   272  
   273  Parameters and response format are the same as
   274  [`/health/service/:service`](/api/health.html#list-nodes-for-service).
   275  
   276  ## List Checks in State
   277  
   278  This endpoint returns the checks in the state provided on the path.
   279  
   280  | Method | Path                         | Produces                   |
   281  | ------ | ---------------------------- | -------------------------- |
   282  | `GET`  | `/health/state/:state`       | `application/json`         |
   283  
   284  The table below shows this endpoint's support for
   285  [blocking queries](/api/index.html#blocking-queries),
   286  [consistency modes](/api/index.html#consistency-modes),
   287  [agent caching](/api/index.html#agent-caching), and
   288  [required ACLs](/api/index.html#acls).
   289  
   290  | Blocking Queries | Consistency Modes | Agent Caching | ACL Required             |
   291  | ---------------- | ----------------- | ------------- | ------------------------ |
   292  | `YES`            | `all`             | `none`        | `node:read,service:read` |
   293  
   294  ### Parameters
   295  
   296  - `state` `(string: <required>)` - Specifies the state to query. Supported states
   297    are `any`, `passing`, `warning`, or `critical`. The `any` state is a wildcard
   298    that can be used to return all checks.
   299  
   300  - `dc` `(string: "")` - Specifies the datacenter to query. This will default to
   301    the datacenter of the agent being queried. This is specified as part of the
   302    URL as a query parameter.
   303  
   304  - `near` `(string: "")` - Specifies a node name to sort the node list in
   305    ascending order based on the estimated round trip time from that node. Passing
   306    `?near=_agent` will use the agent's node for the sort. This is specified as
   307    part of the URL as a query parameter.
   308  
   309  - `node-meta` `(string: "")` - Specifies a desired node metadata key/value pair
   310    of the form `key:value`. This parameter can be specified multiple times, and
   311    will filter the results to nodes with the specified key/value pairs. This is
   312    specified as part of the URL as a query parameter.
   313  
   314  ### Sample Request
   315  
   316  ```text
   317  $ curl \
   318      http://127.0.0.1:8500/v1/health/state/passing
   319  ```
   320  
   321  ### Sample Response
   322  
   323  ```json
   324  [
   325    {
   326      "Node": "foobar",
   327      "CheckID": "serfHealth",
   328      "Name": "Serf Health Status",
   329      "Status": "passing",
   330      "Notes": "",
   331      "Output": "",
   332      "ServiceID": "",
   333      "ServiceName": "",
   334      "ServiceTags": []
   335    },
   336    {
   337      "Node": "foobar",
   338      "CheckID": "service:redis",
   339      "Name": "Service 'redis' check",
   340      "Status": "passing",
   341      "Notes": "",
   342      "Output": "",
   343      "ServiceID": "redis",
   344      "ServiceName": "redis",
   345  	  "ServiceTags": ["primary"]
   346    }
   347  ]
   348  ```