From 82e2654317278b17dd6f2a617f911f672a27342a Mon Sep 17 00:00:00 2001 From: jeff ngo Date: Wed, 8 Sep 2021 17:21:26 -0700 Subject: [PATCH] Add documentation for gRPC message and memory limits #390 --- .../Memory_and_Message_Limits.md | 22 +++++++++++++++++++ docs/docs/References/Platform_Libraries.md | 6 ++--- 2 files changed, 25 insertions(+), 3 deletions(-) create mode 100644 docs/docs/Best_Practices/Memory_and_Message_Limits.md diff --git a/docs/docs/Best_Practices/Memory_and_Message_Limits.md b/docs/docs/Best_Practices/Memory_and_Message_Limits.md new file mode 100644 index 00000000..abbef5a2 --- /dev/null +++ b/docs/docs/Best_Practices/Memory_and_Message_Limits.md @@ -0,0 +1,22 @@ +# Metadata and Message Limits +Operations that exceed their allowed metadata and/or message limits are terminated. + +### Maximum size for metadata +The maximum size for metadata is 32 megabytes (`32MB`). + +The sum of bytes used for the `message`, `action`, and `output` fields within [User Visible Errors](/Best_Practices/User_Visible_Errors.md) count towards total size of metadata. + +### 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 count towards the message size: +1. [Platform library](/References/Platform_Libraries.md) arguments + - Any arguments passed into a platform library will be included in the total message size. +2. [Logging](/References/Logging.md) + - The message provided to the logging function will be included in the total message size. + +### How to tell if the maximum message size was exceeded +When a platform library or log callback fails with a `RpcError`. diff --git a/docs/docs/References/Platform_Libraries.md b/docs/docs/References/Platform_Libraries.md index ddd42d4f..e4541d63 100644 --- 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