AWS omics documentation change
Summary
Restructured documentation sections, added detailed tracking methods for call caching (console/CLI/CloudWatch), and expanded error case scenarios for cache failures
Security assessment
Changes focus on improving operational observability (tracking cache hits) and clarifying cache failure scenarios. No evidence of addressing vulnerabilities or security controls. Error cases describe operational limitations rather than security risks.
Diff
diff --git a/omics/latest/dev/workflow-cache-startrun.md b/omics/latest/dev/workflow-cache-startrun.md index e80ecc216..a38aa9d22 100644 --- a//omics/latest/dev/workflow-cache-startrun.md +++ b//omics/latest/dev/workflow-cache-startrun.md @@ -5 +5 @@ -Configuring a run with run cache using the consoleConfiguring a run with run cache using the CLITracking your run cache hitsError cases for run caches +Configuring a run with run cache using the consoleConfiguring a run with run cache using the CLIError cases for run cachesTracking call caching information @@ -11 +11 @@ By default, runs don't use a run cache. To use a cache for the run, you specify -After a run completes, you can invoke the GetRunTask and ListRunTask API operations to inspect the cacheHit response. +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 and [Troubleshooting call caching issues](./troubleshooting.html#workflow-cache-troubleshooting). @@ -25,2 +24,0 @@ You provide an IAM service role when you start a run. To use call caching, the s - * Tracking your run cache hits - @@ -28,0 +27,2 @@ You provide an IAM service role when you start a run. To use call caching, the s + * Tracking call caching information + @@ -36 +36 @@ 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/](https://console.aws.amazon.com/omics/). + 1. Open the [HealthOmics console](https://console.aws.amazon.com/omics/). @@ -68 +68 @@ If the operation is successful, you receive a response with no data fields. -## Tracking your run cache hits +## Error cases for run caches @@ -70 +70 @@ If the operation is successful, you receive a response with no data fields. -For runs that use call caching, HealthOmics creates a CloudWatch Logs entry when it: +For the following scenarios, HealthOmics may not cache task outputs, even for a run with cache behavior set to **Cache always**. @@ -72 +72 @@ For runs that use call caching, HealthOmics creates a CloudWatch Logs entry when - * creates a cache entry (CACHE_ENTRY_CREATED) + * If the run encounters an error before the first task completes successfully, there are no cache outputs to export. @@ -74 +74 @@ For runs that use call caching, HealthOmics creates a CloudWatch Logs entry when - * matches a cache entry (CACHE_HIT) + * If the export process fails, HealthOmics doesn't save the task outputs to the Amazon S3 cache location. @@ -76 +76 @@ For runs that use call caching, HealthOmics creates a CloudWatch Logs entry when - * fails to match a cache entry (CACHE_MISS) + * If the run fails due to a **filesystem out of space** error, call caching doesn't save any task outputs. @@ -77,0 +78 @@ For runs that use call caching, HealthOmics creates a CloudWatch Logs entry when + * If you cancel a run, call caching doesn't save any task outputs. @@ -78,0 +80 @@ For runs that use call caching, HealthOmics creates a CloudWatch Logs entry when + * 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. @@ -81 +82,0 @@ For runs that use call caching, HealthOmics creates a CloudWatch Logs entry when -For more information about these logs, see [Logs in CloudWatch ](./monitoring-cloudwatch-logs.html#cloudwatch-logs). @@ -83 +83,0 @@ For more information about these logs, see [Logs in CloudWatch ](./monitoring-cl -## Error cases for run caches @@ -85 +85 @@ For more information about these logs, see [Logs in CloudWatch ](./monitoring-cl -For the following scenarios, HealthOmics may not cache task outputs, even for a run with cache behavior set to **Cache always**. +## Tracking call caching information @@ -87 +87 @@ For the following scenarios, HealthOmics may not cache task outputs, even for a - * If the run encounters an error before the first task completes successfully, there are no cache outputs to export. +You can track call caching events (such as run cache hits) using the console, the CLI, or CloudWatch Logs. @@ -89 +89 @@ For the following scenarios, HealthOmics may not cache task outputs, even for a - * If the export process fails, HealthOmics doesn't save the task outputs to the Amazon S3 cache location. +###### Topics @@ -91 +91,67 @@ For the following scenarios, HealthOmics may not cache task outputs, even for a - * If the run fails due to a **filesystem out of space** error, call caching doesn't save any task outputs. + * Track cache hits using the console + + * Track call caching using the CLI + + * Track call caching using CloudWatch Logs + + + + +### Track cache hits using the console + +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/). + + 2. In the left navigation pane, choose **Runs**. + + 3. On the **Runs** page, choose the run to inspect. + + 4. On the run details page, choose the **Run tasks** tab to display the tasks table. + + 5. If a task has a cache hit, the **Cache hit** column contains a link to the run cache entry location in Amazon S3. + + 6. Choose the link to inspect the run cache entry. + + + + +### Track call caching using the CLI + +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 + +HealthOmics creates cache activity logs in the `/aws/omics/WorkflowLog` CloudWatch log group. There is a log stream for each run cache: **runCache/ <cache_id>/<cache_uuid>**. + +For runs that use call caching, HealthOmics generates CloudWatch Logs entries for these events: + + * creating a cache entry (CACHE_ENTRY_CREATED) + + * matching a cache entry (CACHE_HIT) + + * failing to match a cache entry (CACHE_MISS) + + + + +For more information about these logs, see [Logs in CloudWatch ](./monitoring-cloudwatch-logs.html#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: @@ -93 +158,0 @@ For the following scenarios, HealthOmics may not cache task outputs, even for a - * If you cancel a run, call caching doesn't save any task outputs. @@ -95 +160,5 @@ For the following scenarios, HealthOmics may not cache task outputs, even for a - * If your run fails because of a run timeout, call caching doesn't save any task outputs. + filter @logStream like 'runCache/<CACHE_ID>/' + fields @timestamp, @message + filter logMessage like 'CACHE_HIT' + parse "run: *," as run + stats count(*) as cacheHits by run @@ -96,0 +166 @@ For the following scenarios, HealthOmics may not cache task outputs, even for a +Use the following query to return the number of cache entries created by each run: @@ -98,0 +169,5 @@ For the following scenarios, HealthOmics may not cache task outputs, even for a + 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