Merge pull request #1145 from grafana/aws/document-blocking-behavior

Document AWS synchronous behavior and performance considerations

Author: oleiade

src/components/shared/blocking-aws-blockquote/blocking-aws-blockquote.view.js

@@ -0,0 +1,25 @@
+import Blockquote from 'components/shared/blockquote';
+import React from 'react';
+
+const BlockingAwsBlockquote = () => (
+  <Blockquote
+    mod="Attention"
+    title="Performance considerations and recommended practices"
+  >
+    The APIs provided by this jslib operate synchronously, which means k6 must
+    wait for operations that use the client classes to finish before proceeding
+    with the rest of the script.
+    <p>
+      In some cases, such as downloading large files from S3, this could affect
+      performance and test results. To minimize the impact on test performance,
+      we recommend using these operations in the
+      <span className="code-inline">setup</span> and{' '}
+      <span className="code-inline">teardown</span>{' '}
+      <a href="/using-k6/test-lifecycle/">lifecycle functions</a>. These
+      functions run before and after the test run and thus do not influence test
+      results.
+    </p>
+  </Blockquote>
+);
+
+export default BlockingAwsBlockquote;

src/components/shared/blocking-aws-blockquote/index.js

@@ -0,0 +1,3 @@
+import BlockingAwsBlockquote from './blocking-aws-blockquote.view';
+
+export default BlockingAwsBlockquote;

src/components/templates/doc-page/doc-page-content/doc-page-content.view.js

@@ -2,6 +2,7 @@ import classNames from 'classnames';
 import { HtmlContent } from 'components/blocks/html-content';
 import Glossary from 'components/pages/doc-page/glossary';
 import TableOfContents from 'components/pages/doc-page/table-of-contents';
+import BlockingAwsBlockquote from 'components/shared/blocking-aws-blockquote';
 import Blockquote from 'components/shared/blockquote';
 import BrowserClassList from 'components/shared/browser-class-list';
 import BrowserDocsWIP from 'components/shared/browser-docs-wip';
@@ -39,6 +40,7 @@ const componentsForNativeReplacement = {
   BrowserClassList,
   BrowserWIP,
   ExperimentalBlockquote,
+  BlockingAwsBlockquote,
   InstallationInstructions,
   Tooltip,
   BNIT,

src/data/markdown/docs/20 jslib/01 jslib/01 aws.md

@@ -33,9 +33,9 @@ This documentation is for the last version only. If you discover that some code
 
 | Library                                                                | Description                                                          |
 | :--------------------------------------------------------------------- | :------------------------------------------------------------------- |
+| [AWSConfig](/javascript-api/jslib/aws/awsconfig)                       | Class to configure AWS client classes.                               |
+| [KMSClient](/javascript-api/jslib/aws/kmsclient)                       | Client class to interact with AWS Key Management Service.            |
 | [S3Client](/javascript-api/jslib/aws/s3client)                         | Client class to interact with AWS S3 buckets and objects.            |
 | [SecretsManager](/javascript-api/jslib/aws/secretsmanagerclient)       | Client class to interact with AWS secrets stored in Secrets Manager. |
-| [KMSClient](/javascript-api/jslib/aws/kmsclient)                       | Client class to interact with AWS Key Management Service.            |
 | [SQSClient](/javascript-api/jslib/aws/sqsclient)                       | Client class to interact with AWS Simple Queue Service.              |
-| [SystemsManagerClient](/javascript-api/jslib/aws/systemsmanagerclient) | Client class to interact with AWS Systems Manager Service.           |
-| [AWSConfig](/javascript-api/jslib/aws/awsconfig)                       | Class to configure AWS client classes.                               |
+| [SystemsManagerClient](/javascript-api/jslib/aws/systemsmanagerclient) | Client class to interact with AWS Systems Manager Service.           |

src/data/markdown/docs/20 jslib/01 jslib/01 aws/00 KMSClient.md

@@ -5,6 +5,8 @@ description: 'KMSClient allows interacting with the AWS Key Management Service'
 excerpt: 'KMSClient allows interacting with the AWS Key Management Service'
 ---
 
+<BlockingAwsBlockquote />
+
 `KMSClient` interacts with the AWS Key Management Service.
 With it, the user can list all the Key Management Service keys in the caller's AWS account and region. They can also generate symmetric data keys to use outside of AWS Key Management Service. `KMSClient` operations are blocking. k6 recommends reserving their use to the [`setup`](/using-k6/test-lifecycle/) and [`teardown`](/using-k6/test-lifecycle/) stages as much as possible.
 

src/data/markdown/docs/20 jslib/01 jslib/01 aws/00 S3Client.md

@@ -5,6 +5,8 @@ description: 'S3Client allows interacting with AWS S3 buckets and objects'
 excerpt: 'S3Client class allows interacting with AWS S3 buckets and objects'
 ---
 
+<BlockingAwsBlockquote />
+
 S3Client allows interacting with AWS S3's buckets and objects. Namely, it allows the user to list buckets and the objects they contain, as well as download, uploading, and deleting objects. The S3Client operations are blocking, and we recommend reserving their usage to the [`setup`](/using-k6/test-lifecycle/) and [`teardown`](/using-k6/test-lifecycle/) functions as much as possible.
 
 S3Client is included in both the dedicated jslib `s3.js` bundle, and the `aws.js` one, containing all the services clients.

src/data/markdown/docs/20 jslib/01 jslib/01 aws/00 SQSClient.md

@@ -5,7 +5,9 @@ description: 'SQSClient enables interaction with the AWS Simple Queue Service (S
 excerpt: 'SQSClient allows interacting with the AWS Simple Queue Service (SQS)'
 ---
 
-`SQSClient` interacts with the AWS Simple Queue Service (SQS). With it, the user can send messages to specified queues and list available queues in the current region. `SQSClient` operations are blocking. k6 recommends reserving their use for the [`setup`](/using-k6/test-lifecycle/) and [`teardown`](/using-k6/test-lifecycle/) stages as much as possible.
+<BlockingAwsBlockquote />
+
+`SQSClient` interacts with the AWS Simple Queue Service (SQS). With it, the user can send messages to specified queues and list available queues in the current region. `SQSClient` operations are blocking.
 
 Both the dedicated `sqs.js` jslib bundle and the all-encompassing `aws.js` bundle include the `SQSClient`.
 

src/data/markdown/docs/20 jslib/01 jslib/01 aws/00 SecretsManagerClient.md

@@ -5,6 +5,8 @@ description: 'SecretsManagerClient allows interacting with AWS secrets stored in
 excerpt: 'SecretsManagerClient allows interacting with AWS secrets stored in Secrets Manager'
 ---
 
+<BlockingAwsBlockquote />
+
 SecretsManagerClient allows interacting with secrets stored in AWS's Secrets Manager. Namely, it allows the user to list, download, create, modify and delete secrets. Note that the SecretsManagerClient operations are blocking, and we recommend reserving their usage to the [`setup`](/using-k6/test-lifecycle/) and [`teardown`](/using-k6/test-lifecycle/) functions as much as possible.
 
 SecretsManagerClient is included in both the dedicated jslib `secrets-manager.js` bundle, and the `aws.js` one, containing all the services clients.

src/data/markdown/docs/20 jslib/01 jslib/01 aws/00 SystemsManagerClient.md

@@ -5,6 +5,8 @@ description: 'SystemsManagerClient allows interacting with the AWS Systems Manag
 excerpt: 'SystemsManagerClient allows interacting with the AWS Systems Manager Service'
 ---
 
+<BlockingAwsBlockquote />
+
 `SystemsManagerClient` interacts with the AWS Systems Manager Service.
 With it, the user can get parameters from the Systems Manager Service in the caller's AWS account and region. `SystemsManagerClient` operations are blocking. k6 recommends reserving their use to the [`setup`](/using-k6/test-lifecycle/) and [`teardown`](/using-k6/test-lifecycle/) stages as much as possible.