Add API endpoint warnings#47841
Conversation
| | exclude_software | boolean | query | If `true`, the response will not include a list of installed software for the host. | | ||
| | exclude_fleet_maintained_policies | boolean | query | If `true`, will omit Fleet-maintained policies from the policies list. | | ||
|
|
||
| > If you're hitting this endpoint often (e.g. every hour) for a large number of hosts (e.g. 1k+) the best practice is to set the `exclude_software` to `true` to prevent overloading the Fleet server. |
There was a problem hiding this comment.
@spalmesano0 I think let's move this to the top of this section, right below the "Get host" header. That way we're consistent w/ the "Get host by Fleet Desktop token":
|
|
||
| > `populate_software` returns a lot of data per host when set, and drastically more data when set to `true` on Fleet Premium. If you need vulnerability details for a large number of hosts, consider setting `populate_software` to `without_vulnerability_details` and pulling vulnerability details from the [Get vulnerability](#get-vulnerability) endpoint, as this returns details once per vulnerability rather than once per vulnerability per host. | ||
|
|
||
| > Searching with `query` and setting `device_mapping=true` are each expensive, and combining them is more so. If you're hitting this endpoint often the best practice is to reduce how frequently you call it to prevent overloading the Fleet server. |
There was a problem hiding this comment.
| > Searching with `query` and setting `device_mapping=true` are each expensive, and combining them is more so. If you're hitting this endpoint often the best practice is to reduce how frequently you call it to prevent overloading the Fleet server. | |
| > Searching with `query` and setting `device_mapping=true` are each expensive, and combining them is more so. If you're running a scheduled job that hits this endpoint, the best practice is to run it no more than once per hour to avoid overloading the Fleet server. |
@spalmesano0 I tweaked the language to add a specific suggestion but totally guessed on once per hour...is it right? Can we give a faster best practice? 30 minutes?
Also, I think let's move this performance warning to the top of the section: https://github.com/fleetdm/fleet/pull/47841/changes#r3437435430
There was a problem hiding this comment.
@rfairburn said this was originally triggered after hitting it with ~10 req/sec. I'd defer to him on the infrastructure recommendation, though I imagine once every few minutes wouldn't be bad.
@noahtalerman I think the placement of the Get host by Fleet Desktop token warning right under the endpoint title may have been a mistake (probably made by me!), as the warnings for List hosts and List software versions were already under parameters.
With that in mind, do you still want me to move the warnings for the four endpoints here and List software versions near the title?
2 participants
Discussed on Slack.
@rfairburn Can you give this a quick look? Mainly the line about using
queryand settingdevice_mapping=true.