diff --git a/src/directory/directory.mjs b/src/directory/directory.mjs index ce5383d2542..51d55925f07 100644 --- a/src/directory/directory.mjs +++ b/src/directory/directory.mjs @@ -367,6 +367,9 @@ export const directory = { { path: 'src/pages/[platform]/build-a-backend/functions/configure-functions/index.mdx' }, + { + path: 'src/pages/[platform]/build-a-backend/functions/streaming-logs/index.mdx' + }, { path: 'src/pages/[platform]/build-a-backend/functions/grant-access-to-other-resources/index.mdx' }, diff --git a/src/pages/[platform]/build-a-backend/functions/streaming-logs/index.mdx b/src/pages/[platform]/build-a-backend/functions/streaming-logs/index.mdx new file mode 100644 index 00000000000..d6753ef2045 --- /dev/null +++ b/src/pages/[platform]/build-a-backend/functions/streaming-logs/index.mdx @@ -0,0 +1,98 @@ +import { getCustomStaticPath } from '@/utils/getCustomStaticPath'; + +export const meta = { + title: 'Streaming logs', + description: + 'Stream execution logs directly to your terminal while Sandbox is running', + platforms: [ + 'android', + 'angular', + 'flutter', + 'javascript', + 'nextjs', + 'react', + 'react-native', + 'swift', + 'vue' + ] +}; + +export function getStaticPaths() { + return getCustomStaticPath(meta.platforms); +} + +export function getStaticProps(context) { + return { + props: { + platform: context.params.platform, + meta + } + }; +} + +Amplify enables you to stream logs from your Function directly to your terminal while running [`ampx sandbox`](/[platform]/reference/cli-commands/#npx-ampx-sandbox). To get started, specify the `--stream-function-logs` option when starting sandbox: + +```bash title="Terminal" showLineNumbers={false} +npx ampx sandbox --stream-function-logs +``` + + + +**Note**: this feature is only available for [Sandbox](/[platform]/deploy-and-host/sandbox-environments/) + + + +Streaming Function logs directly to your terminal enable faster debug iterations, and greater insight into your Functions' executions. + +## Filtering + +By default, Amplify will stream all of your Functions' logs. If you wish to only stream a subset of Functions you can specify a filter by Function name or a regular expression for Function names. For example, if you have a collection of [Auth triggers](/[platform]/build-a-backend/auth/customize-auth-lifecycle/triggers/) where the Function names include "auth" + +```bash title="Terminal" showLineNumbers={false} +npx ampx sandbox --stream-function-logs --logs-filter auth +``` + +After you successfully deploy your personal cloud sandbox, start your frontend application, and sign up for the first time, you will see logs from your triggers' executions printed to the terminal where sandbox is running. + +```console title="Terminal" +> npx ampx sandbox --stream-function-logs --logs-filter auth +... + +✨ Total time: 158.44s + +[Sandbox] Watching for file changes... +File written: amplify_outputs.json +[auth-pre-sign-up] 3:36:34 PM INIT_START Runtime Version: nodejs:18.v30 Runtime Version ARN: arn:aws:lambda:us-east-1::runtime:f89c264158db39a1cfcbb5f9b3741413df1cfce4d550c9a475a67d923e19e2f4 +[auth-pre-sign-up] 3:36:34 PM START RequestId: 685be2bd-5df1-4dd5-9eb1-24f5f6337f91 Version: $LATEST +[auth-pre-sign-up] 3:36:34 PM END RequestId: 685be2bd-5df1-4dd5-9eb1-24f5f6337f91 +[auth-pre-sign-up] 3:36:34 PM REPORT RequestId: 685be2bd-5df1-4dd5-9eb1-24f5f6337f91 Duration: 4.12 ms Billed Duration: 5 ms Memory Size: 512 MB Max Memory Used: 67 MB Init Duration: 173.67 ms +[auth-post-confirmation] 3:38:40 PM INIT_START Runtime Version: nodejs:18.v30 Runtime Version ARN: arn:aws:lambda:us-east-1::runtime:f89c264158db39a1cfcbb5f9b3741413df1cfce4d550c9a475a67d923e19e2f4 +[auth-post-confirmation] 3:38:40 PM START RequestId: fce69b9f-b257-4af8-8a6e-821f84a39ce7 Version: $LATEST +[auth-post-confirmation] 3:38:41 PM 2024-07-19T22:38:41.209Z fce69b9f-b257-4af8-8a6e-821f84a39ce7 INFO processed 412f8911-acfa-41c7-9605-fa0c40891ea9 +[auth-post-confirmation] 3:38:41 PM END RequestId: fce69b9f-b257-4af8-8a6e-821f84a39ce7 +[auth-post-confirmation] 3:38:41 PM REPORT RequestId: fce69b9f-b257-4af8-8a6e-821f84a39ce7 Duration: 264.38 ms Billed Duration: 265 ms Memory Size: 512 MB Max Memory Used: 93 MB Init Duration: 562.19 ms +[auth-pre-authentication] 3:38:41 PM INIT_START Runtime Version: nodejs:18.v30 Runtime Version ARN: arn:aws:lambda:us-east-1::runtime:f89c264158db39a1cfcbb5f9b3741413df1cfce4d550c9a475a67d923e19e2f4 +[auth-pre-authentication] 3:38:41 PM START RequestId: 9210ca3a-1351-4826-8544-123684765710 Version: $LATEST +[auth-pre-authentication] 3:38:41 PM END RequestId: 9210ca3a-1351-4826-8544-123684765710 +[auth-pre-authentication] 3:38:41 PM REPORT RequestId: 9210ca3a-1351-4826-8544-123684765710 Duration: 3.47 ms Billed Duration: 4 ms Memory Size: 512 MB Max Memory Used: 67 MB Init Duration: 180.24 ms +[auth-post-authentication] 3:38:42 PM INIT_START Runtime Version: nodejs:18.v30 Runtime Version ARN: arn:aws:lambda:us-east-1::runtime:f89c264158db39a1cfcbb5f9b3741413df1cfce4d550c9a475a67d923e19e2f4 +[auth-post-authentication] 3:38:42 PM START RequestId: 60c1d680-ea24-4a8b-93de-02d085859140 Version: $LATEST +[auth-post-authentication] 3:38:42 PM END RequestId: 60c1d680-ea24-4a8b-93de-02d085859140 +[auth-post-authentication] 3:38:42 PM REPORT RequestId: 60c1d680-ea24-4a8b-93de-02d085859140 Duration: 4.61 ms Billed Duration: 5 ms Memory Size: 512 MB Max Memory Used: 68 MB Init Duration: 172.66 ms +``` + +## Writing to a file + +By default, Amplify will print logs to the terminal where sandbox is running, however you can alternatively write logs to a file by specifying `--logs-out-file`: + +```bash title="Terminal" showLineNumbers={false} +npx ampx sandbox --stream-function-logs --logs-out-file sandbox.log +``` + +This can be combined with `--logs-filter` to create a log file of just your Auth-related Functions, for example: + +```bash title="Terminal" showLineNumbers={false} +npx ampx sandbox --stream-function-logs --logs-filter auth --logs-out-file sandbox-auth.log +``` + +However it cannot be combined multiple times to write logs to multiple files. diff --git a/src/pages/[platform]/deploy-and-host/sandbox-environments/features/index.mdx b/src/pages/[platform]/deploy-and-host/sandbox-environments/features/index.mdx index 5df09fe49f6..35f13fb5cbf 100644 --- a/src/pages/[platform]/deploy-and-host/sandbox-environments/features/index.mdx +++ b/src/pages/[platform]/deploy-and-host/sandbox-environments/features/index.mdx @@ -166,6 +166,10 @@ When working with multiple sandboxes, secrets must be configured for each one. A npx ampx sandbox --identifier feature1sandbox secret set baz ``` +## Stream function logs + +Amplify offers the ability to stream function logs directly to your terminal or a file. [Learn more about streaming function logs](/[platform]/build-a-backend/functions/streaming-logs/). + ## Generate client config The client config, or `amplify_outputs.json` file, contains the configuration strings for interacting with AWS resources specific to an environment. The Amplify client libraries need the client config in order to use the library APIs to connect to backend resources. By default, the cloud sandbox generates the client configuration file at the root of the project (such as `@/amplify_outputs.json`). If you want to place the file at a different path (such as for a monorepo or Android app), run the following command in the terminal: diff --git a/src/pages/[platform]/reference/cli-commands/index.mdx b/src/pages/[platform]/reference/cli-commands/index.mdx index 5a6a4d3d532..e0f563e9017 100644 --- a/src/pages/[platform]/reference/cli-commands/index.mdx +++ b/src/pages/[platform]/reference/cli-commands/index.mdx @@ -56,6 +56,9 @@ Sandbox enables you to develop your backend alongside your frontend's developmen - `--outputs-format` (_string_) - Format in which the client config file is written (choices: `json`, `dart`). - `--outputs-version` (_string_) - Version of the configuration. Version 0 represents classic amplify-cli config file amplify-configuration and 1 represents newer config file amplify_outputs (choices: `0`, `1`). - `--profile` (_string_) - An AWS profile name. +- `--stream-function-logs` (_boolean_) - Whether to stream function execution logs. (default: false) +- `--logs-filter` (_string[]_) - Regex pattern to filter logs from only matched functions. E.g. to stream logs for a function, specify it's name, and to stream logs from all functions starting with auth specify 'auth' (default: Stream all logs) +- `--logs-out-file` (_string_) - File to append the streaming logs. The file is created if it does not exist. (default: stdout) ### Usage