Add related evaluations to API

[mikenomitch]

Proposal

In the Nomad UI, it would be helpful to show a list of related evaluations for a specific evaluation. Not just the Next, Previous, and Blocked eval IDs, but multiple evaluations in the linked list and their ID's + statuses.

Currently, the only way to surface this information is to make a sequence of API calls based on the Next/Prev ID values.

Ideally, we could get this infomation in a single call.

Since the chain of evals might be very long, it probably makes sense to limit the chain size via some param.

I currently can think of two ways to accomplish this:

• A new API endpoint. Something like /v1/evaluation/:id/related
• An (default false) param that can be added to the eval show/details endpoint. related_count=5 that would include a new field or fields that should the chain of related params. So instead of just NextEval/PreviousEval, it might include NextEvals (plural) and PreviousEvals (plural) and include their IDs, statuses.

The latter might be preferable from the UI's standpoint, just to cut down on necessary calls, but I think both would work well.

Use-cases

This would allow users to have a simple way to trace an Evaluation back to its source, jump to related evaluations, and figure out the latest status in a chain of evals.

This could support a UI that allows for that. Something like this:

Attempted Solutions

As mentioned above, we could make multiple API calls or try to get a subset of the chain based on the evals index. Neither of which is a great option.

[mikenomitch]

Feedback from UI sync - could we also return a value to show if there are more evals beyond the requested chain?

I get the 10 previous and I am told there are 10+ with a bool.

[mikenomitch]

Also, I think from the UI's perspective, adding this information to the standard GET command is preferable to a new endpoint.

[ChaiWithJai]

Can we make the evaluations endpoint queryable?

Example: /v1/evaluations?related_to=${evaluationId}&limit=10.

Some challenges we foresee at the moment are:

• How do we know when there are no more related evaluations? There is an unexpected user behavior where we display a next button, however, the user can click the next button even though there are no more evaluations. This could be resolved with pagination where we know that we are in page 2 of 5. I believe @tgross explained to me earlier that pagination like this is not possible, so unsure how we can remedy this. Maybe the API response can just tell us if there is a next page. Its worthwhile to have a conversation about if this is possible, and if not we can see if we should just handle the related behavior client-side.
• The user might not click on the head of the linked list of evaluations, should we have the ability to go get the previous evaluations. This is the core part of the user story for debugging the evaluations trail.

[tgross]

Can we make the evaluations endpoint queryable?

I think I'd prefer that to making a new endpoint entirely. That way it's just another field to filter on in the state store query and we can filter on multiple dimensions at once. That'll cut down on implementation work but also let us optimize by using all the same filters that we could on the "parent" eval like it's namespace.

How do we know when there are no more related evaluations? There is an unexpected user behavior where we display a next button, however, the user can click the next button even though there are no more evaluations. This could be resolved with pagination where we know that we are in page 2 of 5. I believe @tgross explained to me earlier that pagination like this is not possible, so unsure how we can remedy this. Maybe the API response can just tell us if there is a next page.

It already should; if there's no X-Nomad-NextToken header then there's no next page.

[github-actions]

I'm going to lock this issue because it has been closed for 120 days ⏳. This helps our maintainers find and focus on the active issues.
If you have found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.