Canary proposal

[Paul Eipper]

I am currently deploying canary health check endpoints that indicates baseline info of the systems, and would like to propose it as a simplified interface. Based on the open discussion regarding the details, I think there is value in having a simple output. Example:

Suggested interface:
GET /canary?key=API_KEY&details=true

Not sending details in the query parameter will omit the details from the output.

HTTP Response: 200 OK when topmost status is true, 503 Service Unavailable otherwise.

{
  "name": "api-1",
  "status": true,
  "metrics": {
    "uptime": "P4DT12H30M5.123456S"
  },
  "details": {
    "database": {
      "status": true,
      "metrics": {
        "connections": 25,
        "latency": "PT0.000456S"
      }
    },
    "api-2": {
      "status": false,
      "details": {
        "s3": {
          "status": true,
          "metrics": {
            "latency": "PT0.000123S"
          }
        }
      }
    },
    "redis": {
      "status": true
    },
    "email": {
      "status": false,
      "critical": false
    },
    "node-1": {
      "status": true,
      "metrics": {
        "DiskAvailable": {
          "value": 14,
          "unit": "Gb"
        },
        "DiskUse": {
          "value": 31,
          "unit": "%"
        },
        "MemoryAvailable": {
          "value": 536,
          "unit": "Mb"
        },
        "time": "2018-07-31T01:07:51+00:00"
      }
    }
  }
}

If any critical services respond with status false, the parent service must also be set to status false. Services are critical by default, unless "critical": false is defined.

Let me know your thoughts.

[Erik Wilde]

On 2018-08-03 08:00, Paul Eipper wrote: I am currently deploying canary health check endpoints that indicates baseline info of the systems, and would like to propose it as a simplified interface. Based on the open discussion regarding the details, I think there is value in having a simple output. Example: Suggested interface: |GET /canary?key=API_KEY&details=true| Not sending |details| in the query parameter will omit the details from the output.

you're free to do that. the format does not preclude you from defining query models into it, but personally, i don't think that such a query model should be part of the format definition.

[Irakli Nadareishvili]

Paul, I agree with Eric. Nothing in the spec implies that you have to always output full data. It's totally fine (and reasonable) to have different levels of output. You can customize the output with a query param, or you can use HTTP Prefer header: https://tools.ietf.org/html/rfc7240 with return preference.

I don't think the format standard should mandate how clients may hint on the level of detail they care about, however pointing-out this scenario in the spec, may indeed be a good idea.

[Irakli Nadareishvili]

Assuming this question was answered, closing the issue.