Azure-functions-durable-extension: Get all instances status enhancements

[markheath]

It's really great to see that Durable Functions now has a way to query the status of all instances

This type of higher-level management API will be very helpful for troubleshooting problems in production. However, I think it could do with some additional enhancements

• Paging - it looks like this API simply returns details of all orchestrations that have ever been started in the task hub? That could get unmanageable very quickly if you are using durable functions extensively. Perhaps it could return a HATEOAS style link to the next page of results in the payload. I know that the table storage query APIs support continuation tokens so this should be possible to implement.
• Filtering - I'd like to be able to filter by status (and possibly creation date) - it would be particularly useful to be able to find which orchestrations are still running, particularly if I'm about to perform an upgrade. I know that table storage querying doesn't perform particularly well, but it would still be preferable to client-side filtering.
• Purging - I think it could also be useful to have another API that lets us purge a specific orchestration from task hub history. This could be used to discard details of old completed/failed orchestrations, but also as a brute force way of killing an orchestration that for some reason has got stuck running indefinitely. In many scenarios it may also be necessary to comply with data retention regulations.

Obviously we can take a DIY approach by reaching directly into the task hub ourselves, but I think it would be nice if the Durable Functions API had built-in support for these scenarios.

[cgillum]

FYI @TsuyoshiUshio - Mark has some nice suggestions about how we can further improve this new API.

[TsuyoshiUshio]

Thank you very much @markheath and @cgillum These ideas are very good and worth considering. I'll come up with some idea to implement these.

[TsuyoshiUshio]

I create this feature for DevOps story, however now It can use for trouble shooting.

1. Paging -> No prblem
2. Filtering -> As you said, it could cause a performance issue however if we have 3. Purging it works
3. Purging -> I really love this idea. totally agree.

We can start with 3. then Filtering and Filtering.

For the 3. Originally I imagined to configure host.json to set the date which keep the record. (e.g. 7 days or something) However, having new HTTP API sounds good as well. I have no idea when to remove the record if we use the "host.json" storategy. However HTTP API is no problem of when to start.

@markheath , What do you mean "to comply with data retention regulation"? Do we need to move data when we purge it? Or just ok for remove the data?

Anyway, I'd happy to contribute this. @cgillum :)

[markheath]

@TsuyoshiUshio - it would be fine just to delete it for the purposes of this API.

And yes I was expecting an API rather than an automatic purge. You could always write your own scheduled Azure Function that ran at midnight every night and performed the purge. In that case it would be handy if it was also exposed as a method on a DurableOrchestrationClient.

[TsuyoshiUshio]

Thanks @markheath , I'd happy to contribute.
Hi @cgillum , Shall I contribute it?

I'd like to implement by this priority

1. Purging
2. Filtering (at least we can filter running process)
3. Paging

[cgillum]

I might swap the priorities of 1 and 2. @TsuyoshiUshio yes I'd be happy to have your contribution. :)

[TsuyoshiUshio]

@cgillum Ok. Let's start discussing with Filtering.

I have two questions for the spec.

1. Query target

   runtimeStatus, createdTime, and lastUpdatedTime can be a target of the query. Am I right?

2. Query REST API design

   We have two way to implement search API. one is simply implement with query with GET request. The other is POST. Microsoft uses both approach. Which would you prefer or does Microsoft have a guide to design REST API? In this case, we might want to filter from, to query. For the simple query, GET with parameter might be good. However, if it becomes complex or with a lot of parameters, POST might be good.

GET example
https://dev.applicationinsights.io/reference/get-query

POST example
https://docs.microsoft.com/en-us/rest/api/time-series-insights/time-series-insights-reference-queryapi#get-environment-metadata-api

[cgillum]

1. I think those query parameters are good.
2. I suggest a GET with query string parameters, which is more natural. I think POST should be used only for special cases. The time series insights feels like a special case since it supports complex queries based on user-defined types.

[cgillum]

Filtering has been checked in and is available now starting in the v1.6.0 release. I'm leaving this issue open to track paging, which would also be an important thing for us to include.

[cgillum]

History purge is currently being worked on (see the linked PR). After that, I think we just need paging.

[cgillum]

Paging is done! We're working on finishing the history purge work and then we'll be able to close this issue. :)

[cgillum]

I'm pleased to say that we've completed all the suggestions mentioned in this issue! They will be available in the next release (1.7.0).