Introduction 

Nowadays the UI will only get the first 100 runs of the program no matter how many program runs there are. Our current run API does not have a way to retrieve the total run count unless we do a full table scan. Additionally, it is hard to use the current API to get the previous and next runs given a run id.

Goals

Introduce a new count API which will return the count of a program, modify the existing runs API to accept the cursor to support pagination, figure out the upgrade step which is needed for program runs prior to 5.1.

User Stories 

• As a CDAP user, I want to be able to know the total run count of a program.
• As a CDAP user, I want to be able to get the previous or next runs given a program run.
• As a CDAP user, I want to be able to know the status of each program run.

Design

Current API and restrictions

We currently have the following API to retrieve the run record information:

@GET
@Path("/apps/{app-name}/{program-type}/{program-name}/runs")
public void programHistory(HttpRequest request, HttpResponder responder,
                           @PathParam("namespace-id") String namespaceId,
                           @PathParam("app-name") String appName,
                           @PathParam("program-type") String type,
                           @PathParam("program-name") String programName,
                           @QueryParam("status") String status,
                           @QueryParam("start") String startTs,
                           @QueryParam("end") String endTs,
                           @QueryParam("limit") @DefaultValue("100") final int resultLimit) {
...
}

Currently it only supports query based on the start timestamp and end timestamp with a limit. And the only way to get the run count is to specify the limit to be Long.MAX_VALUE, which will do a full table scan on the AppMetadataStore and might cause tx timeout if there are too many run records. With this it will be hard to do pagination just with the timestamp range. Since it is impossible for the caller to know how many runs are there between two timestamps. 

Also, specifying start ts and end ts with a limit actually will return the run records which is closer to the end timestamp now because we have the row key of our run record like following: 

runRecordStarting|namespace|app|version|programtype|program|runid
runRecordStarted|namespace|app|version|programtype|program|runid
runRecordSuspended|namespace|app|version|programtype|program|runid
runRecordCompleted|namespace|app|version|programtype|program|inverted start time|runid

The current running program does not have a timestamp in their row key so their order is random in the response(and current they are always in the response no matter what timestamp is specified). For completed programs, we store them use the inverted start time which is Long.MAX_VALUE - startTime, so when we scan the table, we will get the most recent ones. There is no way to get the runs around the start time first according to the current API. We should also consider modifying the row keys to make them consistent because the current row key is adding unnecessary complexity to the store. 

Refactoring the existing store

We should have our run records ordered based on 1). State(Program run active > completed) 2). Start time(the latest run should come first). The current API guarantees order of the state and the time order for completed runs. However, the time order is not guaranteed for active runs. All the active run records are returned in random order. Without this, it is also difficult for us to find the prev/next run record since we will have to scan all the three formats of row keys and decide. 

To refactor, we can add the inverted start time also as part of the row key like what we have for the completed runs. Upon some investigation, it seems unnecessary to have 3 different row key formats for the active program runs. So we can refactor the row key to the following: 

runRecordActive|namespace|app|version|programtype|program|inverted start time|runid
runRecordCompleted|namespace|app|version|programtype|program|inverted start time|runid

Strictly speaking, we will need a upgrade step after this change. But since we require user to stop all the programs before they do the upgrade, these active row keys should not exist before the upgrade. So we might be able to skip the upgrade step.

Navigate to prev/next run record

To be able to navigate between run records, we will introduce two new query params: cursor and order, where each cursor is a run id, order will be going prev or next. We can scan through the table to get the results we want. Since we store the start time in a inverted order, it will be easy if we scan from the latest run to the older runs(this means getting prev runs will be easier). However, it is difficult from us to get the newer runs starting from an old run since we currently do not support reverse scan. We will have to start from the first, and keep scanning until we reach the run we want. 

To fix this, we will have to add a not inverted time row key to each run record, which will basically doubles the number of row key, and it requires a complex upgrade step, we need to decide if it is worth to make this effort:

runRecordActive|namespace|app|version|programtype|program|inverted start time|runid
runRecordCompleted|namespace|app|version|programtype|program|inverted start time|runid
runRecordActive|namespace|app|version|programtype|program|start time|runid
runRecordCompleted|namespace|app|version|programtype|program|start time|runid

Run record count

In order to get the total count without scanning the whole table, we will introduce some new row which records the count like following: 

runCount|namespace|app|version|programtype|program

Every time we add a new run record, basically when it is provisioning, we will increment this value. This change should be straightforward but the upgrade step will be messy.

Upgrade of the old run records

Approach #1

We need to scan all the run records in the app meta table  and update the count for the upgrade step. We will basically have two steps in the upgrade. 1. Scan the old run records and get the old count, 2. Merge this count to the newly introduced count row. However, there are several things to take care of: 

• The program can get started by either the user or the scheduler when we do the upgrade step, therefore, when we count, we need to find a way to distinguish the old run records from the new run records
  • To solve this, we will store a first-time startup time for 5.1 CDAP, and we will only count the run records only if the run record is older than this first-time 
  • Store this count into another row which is different from the count row
  • Merge this count to the new count row after we have done the scan of a program run record
• The application can get deleted when we do the scan, and that will wipe out all the run records of the program:
  • Have a marker which tells the program get deleted.
  • Ignore the old count row if there is a marker indicating the app is getting deleted when we merge
• Avoid duplicate count if CDAP stops or restarts during the upgrade step
  • Need to mark for each program whether the upgrade is done - if not done, which run record have it scanned.
  • If CDAP restarts, use these markers to find out which row to scan next
• Known issue:
  • Though we require user to stop all the programs before they upgrade, but if they do not and if there are active runs, these runs will remain in the app meta table. We will not count these run records since they can get transitioned any time due to program completion, which means it is super hard to count it precisely.

Pros:

1. Everything happen in the background, the results will eventually become correct.
2. We will know when the entire table upgrade is done
3. Easy to remove the code in the future

Cons:

1. Very complex upgrade - need to add many additional rows to the app meta table
2. User will see incorrect results if the upgrade step is not done.

Approach #2

Approach 2 is similar to approach 1 but does not require upgrade step. We will do the scan for the program run record by the first time the count api is getting called. This means the first time query will take some time. 

Pros:

1. User will not see incorrect result 
2. No need to worry about CDAP restarts or stops
3. Less complexity in code, since we explicitly deal with run records for a program

Cons:

1. First time count API get called it will take some time to get the result - might hang the REST call if there are huge number of run records.
2. Not able to tell if the entire app meta table is upgraded, only know about whether a program is upgraded.

Approach

Approach #1

Approach #2

API changes

New Programmatic APIs

New Java APIs introduced (both user facing and internal)

Deprecated Programmatic APIs

New REST APIs

/apps/{app-name}/{program-type}/{program-name}/count

/apps/{app-name}/versions/{app-version}/{program-type}/{program-name}/count

Deprecated REST API

CLI Impact or Changes

UI Impact or Changes

• UI will need to change the pipeline overview page to use the count REST endpoint to get the run count
• UI will need to change the query param on the pipeline detail page to correctly navigate to older/newer runs
• UI needs to think about how to deal with the pipeline statistics page and the card page about how they want to show the run count and run records

Security Impact 

User will need at least one privilege(READ, WRITE, EXECUTE, ADMIN) on the program to get the total run count.

Test Scenarios

Releases

Release 5.1.0

Related Work

Future work