# Using the run cache
<a name="workflow-cache-startrun"></a>

By default, runs don't use a run cache. To use a cache for the run, you specify the run cache and the run cache behavior when you start the run.

After a run completes, you can use the console, CloudWatch Logs, or API operations to track cache hits or troubleshoot cache issues. For details, see [Tracking call caching information](#workflow-cache-track) and [Troubleshooting call caching issues](troubleshooting.md#workflow-cache-troubleshooting).

If one or more tasks in a run generate non-deterministic outputs, we strongly recommend that you don’t use call caching for the run, or you opt out these specific tasks from caching. For more information, see [Shared responsibility model](how-run-cache.md#run-cache-srm).



**Note**  
You provide an IAM service role when you start a run. To use call caching, the service role needs permission to access the run cache Amazon S3 location. For more information, see [Service roles for AWS HealthOmics](permissions-service.md).

You can use [Kiro CLI](https://docs.aws.amazon.com/kiro/latest/userguide/what-is.html) to analyze and manage your run cache data. For more information, see [Example prompts for Kiro CLI](getting-started.md#omics-kiro-prompts) and the [HealthOmics Agentic generative AI tutorial](https://github.com/aws-samples/aws-healthomics-tutorials/tree/main/generative-ai) on GitHub.

**Topics**
+ [Configuring a run with run cache using the console](#workflow-cache-startrun-console)
+ [Configuring a run with run cache using the CLI](#workflow-cache-startrun-api)
+ [Error cases for run caches](#workflow-cache-errors)
+ [Tracking call caching information](#workflow-cache-track)

## Configuring a run with run cache using the console
<a name="workflow-cache-startrun-console"></a>

From the console, you configure the run cache for a run when you start the run.

1. Open the [HealthOmics console](https://console.aws.amazon.com/omics/).

1.  If required, open the left navigation pane (≡). Choose **Runs**.

1. On the **Runs** page, choose the run to start.

1. Choose **Start run** and complete steps 1 and 2 of **Start run** as described in [Starting a run using the console](starting-a-run.md#starting-a-run-console). 

1. In step 3 of **Start run**, choose **Select an existing run cache**. 

1. Select the cache from the **Run cache ID** drop-down list. 

1. To override the default run cache behavior, choose the **Cache behavior** for the run. For more information, see [Run cache behavior](how-run-cache.md#run-cache-behavior).

1. Continue to step 4 of **Start run**.

## Configuring a run with run cache using the CLI
<a name="workflow-cache-startrun-api"></a>

To start a run that uses a run cache, add the cache-id parameter to the **start-run** CLI command. Optionally, use the `cache-behavior` parameter to override the default behavior that you configured for the run cache. The following example shows only the cache fields for the command:

```
aws omics start-run \
        ...  
      --cache-id "xxxxxx"    \
      --cache-behavior  CACHE_ALWAYS
```

If the operation is successful, you receive a response with no data fields. 

## Error cases for run caches
<a name="workflow-cache-errors"></a>

For the following scenarios, HealthOmics may not cache task outputs, even for a run with cache behavior set to **Cache always**.
+ If the run encounters an error before the first task completes successfully, there are no cache outputs to export.
+ If the export process fails, HealthOmics doesn't save the task outputs to the Amazon S3 cache location.
+ If the run fails due to a **filesystem out of space** error, call caching doesn't save any task outputs.
+ If you cancel a run, call caching doesn't save any task outputs.
+ If the run experiences a run timeout, call caching doesn't save any task outputs, even if you configured the run to use cache on failure.

## Tracking call caching information
<a name="workflow-cache-track"></a>

You can track call caching events (such as run cache hits) using the console, the CLI, or CloudWatch Logs.

**Topics**
+ [Track cache hits using the console](#workflow-cache-track-console)
+ [Track call caching using the CLI](#workflow-cache-track-cli)
+ [Track call caching using CloudWatch Logs](#workflow-cache-track-cwl)

### Track cache hits using the console
<a name="workflow-cache-track-console"></a>

In the run details page for a run, the **Run tasks** table displays **Cache hit** information for each task. The table also includes a link to the associated cache entry. Use the following procedure to view cache hit information for a run.

1. Open the [HealthOmics console](https://console.aws.amazon.com/omics/).

1.  If required, open the left navigation pane (≡). Choose **Runs**.

1. On the **Runs** page, choose the run to inspect.

1. On the run details page, choose the **Run tasks** tab to display the tasks table.

1. If a task has a cache hit, the **Cache hit** column contains a link to the run cache entry location in Amazon S3.

1. Choose the link to inspect the run cache entry.

### Track call caching using the CLI
<a name="workflow-cache-track-cli"></a>

Use the **get-run** CLI command confirm whether the run used a call cache.

```
 aws omics get-run --id 1234567  
```

In the response, if the `cacheId` field is set, the run uses that cache.

Use the **list-run-tasks** CLI command to retrieve the cache data location for each cached task in the run.

```
 aws omics list-run-tasks --id 1234567  
```

In the response, if the cacheHit field for a task is true, the cacheS3Uri field provides the cache data location for that task.

You can also use the **get-run-task** CLI command to retrieve the cache data location for a specific task:

```
 aws omics get-run-task --id 1234567 --task-id <task_id> 
```

### Track call caching using CloudWatch Logs
<a name="workflow-cache-track-cwl"></a>

HealthOmics creates cache activity logs in the `/aws/omics/WorkflowLog` CloudWatch log group. There is a log stream for each run cache: **runCache/<cache\$1id>/<cache\$1uuid>**.

For runs that use call caching, HealthOmics generates CloudWatch Logs entries for these events: 
+  creating a cache entry (CACHE\$1ENTRY\$1CREATED)
+  matching a cache entry (CACHE\$1HIT) 
+  failing to match a cache entry (CACHE\$1MISS)

For more information about these logs, see [Logs in CloudWatch](monitoring-cloudwatch-logs.md#cloudwatch-logs).

Use the following CloudWatch Insights query on the `/aws/omics/WorkflowLog` log group to return the number of cache hits per run for this cache:

```
filter @logStream like 'runCache/<CACHE_ID>/'
 fields @timestamp, @message
 filter logMessage like 'CACHE_HIT'
 parse "run: *," as run
 stats count(*) as cacheHits by run
```

Use the following query to return the number of cache entries created by each run:

```
filter @logStream like 'runCache/<CACHE_ID>/'
 fields @timestamp, @message
 filter logMessage like 'CACHE_ENTRY_CREATED'
 parse "run: *," as run
 stats count(*) as cacheEntries by run
```