Add documentation for gRPC message and memory limits delphix#390

jeffngo · Sep 9, 2021 · d671c44 · d671c44
1 parent 82dd1a3
commit d671c44
Show file tree

Hide file tree

Showing 3 changed files with 32 additions and 3 deletions.
diff --git a/docs/docs/Best_Practices/.pages b/docs/docs/Best_Practices/.pages
@@ -7,3 +7,4 @@ arrange:
   - Unicode_Data.md
   - Working_with_Powershell.md
   - Scratch_Paths.md
+  - Metadata_and_Message_Limits.md
diff --git a/docs/docs/Best_Practices/Metadata_and_Message_Limits.md b/docs/docs/Best_Practices/Metadata_and_Message_Limits.md
@@ -0,0 +1,28 @@
+# Metadata and Message Limits
+Operations that exceed their internal metadata and/or message limits will be terminated.
+
+## Maximum size for metadata
+The maximum size for metadata is 32 megabytes (`32MB`).
+
+The following fields within [User Visible Errors](/Best_Practices/User_Visible_Errors.md) will all count towards used internal metadata:
+1. `message`
+2. `action`
+3. `output`
+
+### How to tell if the maximum metadata size was exceeded
+When an operation should fail with a `UserError`, but fails with a `RpcError` instead.
+
+## Maximum size for messages
+The maximum size for messages is 128 kibibytes (`128 KiB`).
+
+The following items will count towards the size of the message.
+1. [Platform library](/References/Platform_Libraries.md) arguments
+    - The sum of all arguments passed into a platform library callback will be included in the internal message size.
+2. [Logging](/References/Logging.md)
+    - The message provided to the logging function will be included in the internal message size.
+
+### How to tell if the maximum message size was exceeded
+When a platform library or log callback fails with a `RpcError`.
+
+## What to do if the maximum metadata or message size is exceeded
+Please reach out to us via the [Virtualization SDK GitHub repository](https://github.com/delphix/virtualization-sdk/) for guidance.
diff --git a/docs/docs/References/Platform_Libraries.md b/docs/docs/References/Platform_Libraries.md
@@ -15,7 +15,7 @@ Argument | Type | Description
 -------- | ---- | -----------
 remote_connection | [RemoteConnection](Classes.md#remoteconnection) | Connection associated with the remote host to run the command on.
 command | String | Command to run on the host.
-variables | dict[String, String] | **Optional**. Environement variables to set when running the command.
+variables | dict[String, String] | **Optional**. Environment variables to set when running the command.
 use_login_shell | boolean | **Optional**. Whether to use a login shell.
 check | boolean | **Optional**. Whether or not to raise an exception if the `exit_code` in the `RunBashResponse` is non-zero.
 
@@ -85,7 +85,7 @@ Argument | Type | Description
 -------- | ---- | -----------
 remote_connection | [RemoteConnection](Classes.md#remoteconnection) | Connection associated with the remote host to run the command on.
 command | String | Expect(Tcl) command to run.
-variables | dict[String, String] | **Optional**. Environement variables to set when running the command.
+variables | dict[String, String] | **Optional**. Environment variables to set when running the command.
 
 ### Returns
 An object of `RunExpectResponse`
@@ -127,7 +127,7 @@ Argument | Type | Description
 -------- | ---- | -----------
 remote_connection | [RemoteConnection](Classes.md#remoteconnection) | Connection associated with the remote host to run the command on.
 command | String | Command to run to the remote host.
-variables | dict[String, String] | **Optional**. Environement variables to set when running the command.
+variables | dict[String, String] | **Optional**. Environment variables to set when running the command.
 check | boolean | **Optional**. Whether or not to raise an exception if the `exit_code` in the `RunPowershellResponse` is non-zero.
 
 ### Returns