dashboard Documentation

File: README.md Copy Chapter

Serverless Framework Dashboard

This repository is the singular location of all open-source components of Serverless Framework Dashboard.

Here you will find:

• AWS Lambda Extensions – The source code of the AWS Lambda Extensions installed by users to send metrics, traces and logs to Serverless Framework Dashboard.
• AWS IAM Role – The AWS CloudFormation template containing an AWS IAM Role that allows Serverless Framework Dashboard permissions to specific services to provide monitoring and observability features.

File: go/packages/dev-mode/README.md Copy Chapter

Serverless Dev Mode Extension

This extension layer will forward logs from your lambda function to serverless console dev mode.

This layer is utilizing lambda logs API. It is important to note that the lambda logs API is not necessarily meant to forward logs in real time. Logs are really mean to be batched and sent out. This means that in this project we added a wait process that will keep the lambda function running until all logs have been posted. This means that you probably shouldn't run this extension in a production environment where longer running lambda functions will result in high costs.

Development Copy Chapter

There isn't much you have to do to build/deploy this code. Simply run the following command and the code will be deployed to whatever AWS account your AWS CLI is configured for.

make deploy

The command above will output a layer arn once successfully deployed.

After the layer is deployed you can attach this layer to any lambda function, just be sure to create the following environment variables.

Testing Copy Chapter

This app is reusing unit tests from our node extension so the unit tests live in ../node/packages/aws-lambda-otel-extension/test/unit/external/index.test.ts

These tests will spin up a local server that emulates the lambda API server.

To run these tests locally simply run

make test

Integrations tests Copy Section

Integrations tests for this extension are using the integration testing setup/framework that we are using for all other projects in this monorepo. This means that the integration tests are hosted in ../../../node/test/go/dev-mode folder. Check this folder for more details about the integration tests.

Releasing a version Copy Chapter

When you are ready to release a new version of this extension simply increment the version number in the version.txt file.

Regional Endpoints Copy Chapter

This app uses regional endpoints when publishing telemetry data. This keeps our data transfer as fast as possible so that customer lambda functions do not experience unnecessarily long total durations while this extension forwards data to our backend.

This does mean that if AWS adds a region or a region is not listed in the regionMap in the publishUrl file it is possible for telemetry API calls to fail. So it is important that if a new region is added to AWS that we deploy a new set of endpoints in platform-core.

File: go/packages/dev-mode/version.txt Copy Chapter

0.7.3

File: go/packages/slslambda/README.md Copy Chapter

Go SDK

Go SDK reports Traces, Captured Errors and Captured Warnings to Serverless Console
from the AWS lambda Go runtime environment. The SDK library must be added and
instrumented in your AWS Lambda function handler.

Key terms Copy Chapter

• A Captured Error is one instance of an error that is sent to Serverless
  Console. It can be viewed in the Trace Explorer Details.
• A Captured Warning is one instance of a string that is sent to
  Serverless Console, much like a Captured Error.

Compatibility Copy Chapter

While Serverless Console is developed by the makers of the Serverless Framework,
the entire Serverless Console product and this SDK are 100% agnostic of the
deployment tool you use. Serverless Console and this SDK work just as well with
Terraform, CDK, SAM, Pulumi, etc, as they do with Serverless Framework.

Installation Copy Chapter

Install the package Copy Section

To instrument your Lambda function code you just need to replace
"github.com/aws/aws-lambda-go/lambda" import with "github.com/serverless/console/go/packages/slslambda".

Before:

package main

import (
	"github.com/aws/aws-lambda-go/lambda"
)

func main() {
	lambda.Start(handle)
}

func handle() {}

After:

package main

import (
	"github.com/serverless/console/go/packages/slslambda"
)

func main() {
	slslambda.Start(handle)
}

func handle() {}

Enable Logging Copy Section

Logging must be enabled on your org in Serverless Console in order for the data to be ingested.

Enable Tracing, Logging, and Dev Mode

Set environment variable Copy Section

The package does require SLS_ORG_ID environment variable to be set in your Lambda function.
You must do that manually using AWS API or AWS Console.

Capturing Errors Copy Chapter

slslambda.CaptureError(ctx, err)

Capturing Warnings Copy Chapter

slslambda.CaptureWarning(ctx, "something bad will happen soon")

Example Copy Chapter

You can find a working example in the example directory.

File: node/package.json Copy Chapter

{
"repository": "serverless/runtime",
"author": "Serverless, Inc.",
"husky": {
"hooks": {
"pre-commit": "lint-staged"
}
},
"lint-staged": {
".js": [
"eslint"
],
".{css,html,js,json,md,yaml,yml}": [
"prettier -c"
]
},
"devDependencies": {
"@aws-lambda-powertools/logger": "^1.10.0",
"@aws-sdk/client-api-gateway": "^3.358.0",
"@aws-sdk/client-apigatewayv2": "^3.358.0",
"@aws-sdk/client-cloudwatch-logs": "^3.358.0",
"@aws-sdk/client-dynamodb": "^3.358.0",
"@aws-sdk/client-iam": "^3.358.0",
"@aws-sdk/client-lambda": "^3.358.0",
"@aws-sdk/client-s3": "^3.358.0",
"@aws-sdk/client-sns": "^3.358.0",
"@aws-sdk/client-sqs": "^3.358.0",
"@aws-sdk/client-sts": "^3.358.0",
"@commitlint/cli": "^17.6.5",
"@commitlint/lint": "^17.6.5",
"@octokit/rest": "^19.0.13",
"@rollup/plugin-multi-entry": "^4.1.0",
"@rollup/plugin-node-resolve": "^13.3.0",
"@rollup/plugin-typescript": "^8.5.0",
"@serverless/eslint-config": "^5.1.0",
"@serverless/sdk-schema": "^0.15.6",
"@serverless/test": "^11.1.1",
"@serverless/utils": "^6.11.1",
"@tsconfig/node16": "^1.0.4",
"adm-zip": "^0.5.10",
"bunyan": "^1.8.15",
"chai": "^4.3.7",
"chalk": "^4.1.2",
"child-process-ext": "^2.1.1",
"deasync": "^0.1.28",
"esbuild": "^0.15.18",
"esbuild-plugin-d.ts": "^1.1.0",
"eslint": "^8.43.0",
"eslint-plugin-import": "^2.27.5",
"essentials": "^1.2.0",
"express": "^4.18.2",
"ext": "^1.7.0",
"fast-glob": "^3.2.12",
"fs2": "^0.3.9",
"git-list-updated": "^1.2.1",
"github-release-from-cc-changelog": "^2.3.0",
"husky": "^4.3.8",
"lint-staged": "^13.2.2",
"lodash": "^4.17.21",
"log": "^6.3.1",
"log-node": "^8.0.3",
"long": "^5.2.3",
"memoizee": "^0.4.15",
"mocha": "^9.2.2",
"ncjsm": "^4.3.2",
"node-fetch": "^2.6.11",
"node-machine-id": "^1.1.12",
"pino": "^8.14.1",
"prettier": "^2.8.8",
"rimraf": "^3.0.2",
"rollup": "^2.79.1",
"rollup-plugin-dts": "^4.2.3",
"serverless-http": "^3.2.0",
"standard-version": "^9.5.0",
"stream-promise": "^3.2.0",
"timers-ext": "^0.1.7",
"toml": "^3.0.0",
"ts-proto": "^1.150.1",
"tslib": "^2.5.3",
"type": "^2.7.2",
"typescript": "^4.9.5",
"uni-global": "^1.0.0",
"uuid": "^9.0.0",
"winston": "^3.9.0",
"yargs-parser": "^21.1.1"
},
"scripts": {
"lint": "eslint .",
"lint:updated": "pipe-git-updated --ext=js --base=main -- eslint",
"prettier-check": "prettier -c "/*.{css,html,js,json,md,yaml,yml}"",
"prettier-check:updated": "pipe-git-updated --ext=css --ext=html --ext=js --ext=json --ext=md --ext=yaml --ext=yml --base=main -- prettier -c",
"prettify": "prettier --write --ignore-path .gitignore "/.{css,html,js,json,md,yaml,yml}"",
"prettify:updated": "pipe-git-updated --ext=css --ext=html --ext=js --ext=json --ext=md --ext=yaml --ext=yml --base=main -- prettier --write",
"test:dev-mode:integration": "mocha "test/go/dev-mode/test/integration/**/.test.js"",
"test:aws-lambda-sdk:integration:python": "mocha "test/python/aws-lambda-sdk/integration.test.js"",
"test:aws-lambda-sdk:integration:go": "mocha "test/go/aws-lambda-sdk/integration.test.js""
},
"engines": {
"node": ">=14.0"
},
"license": "MIT"
}

File: node/RELEASE_PROCESS.md Copy Chapter

Release process

Semi-automation Copy Chapter

All packages of the Serverless Runtime project rely on semantic commit messages, which allow for streamlining the release process (versioning and changelog generation is automated)

See proposed Commit Message Guidelines

Semantic commit messages are not required in PRs coming from forks (community contributions). Yet, such PR is expected to be squash merged by project members with a single semantic commit message.

PRs coming from branches have commit messages validated with commmitlint

Release flow Copy Chapter

Releases for each package are triggered manually by preparing release PRs.

Preparation steps:

1. Create the release branch (should derive from the current main state)
2. Bump version ranges of all dependencies to the latest supported versions (e.g., if the latest version of a dependency is 2.3.5 and the range in a package.json is ^2.2.4, then it should be updated to ^2.3.5)
3. Commit eventual dependency version updates with the following commit message:
   chore: Bump dependencies
4. Run npm run prepare-release command.
   It'll automatically bump the version in package.json to the expected one (by inspecting changes since the previous release) and will generate a new changelog entry.
5. Improve generated changelog entry in CHANGELOG.md if needed.
6. Commit package.json and CHANGELOG.md changes with the following commit message:
   chore: Release v<version>
7. Push branch upstream and create a PR.
8. After PR is accepted by CI and one of the reviewers, merge it via "Rebase and merge" option

Further actions are automated in CI context:

9. main CI build detects that release PR was merged (by fact that it covers change of version field in package.json file). Having that (after successful tests pass) version tag is created and pushed to the repository.
10. Tag CI build publishes a new version to npm, also it retrieves release notes from CHANGELOG.md and publishes them to GitHub.

Updating release notes for already published versions Copy Section

Improvements to release notes can be done at any time to any already published version:

1. Update CHANGELOG.md with desired changes (ensure they'd also end in main)
2. Push updated release notes to GitHub by running:
   npx github-release-from-cc-changelog <versionTag>

File: node/packages/aws-lambda-otel-extension/README.md Copy Chapter

@serverless/aws-lambda-otel-extension

AWS Lambda extension that gathers [OpenTelemetry](https://opentelemetry.io/) data and sends it to the Serverless Console ingestion servers Copy Chapter

Package is still in an experimental stage and subject to major changes.

At this point, only Node.js runtime is supported, but this support will be extended in the near future

How does it work? Copy Section

The extension is a lambda layer with a source maintained in opt folder. There are two extensions configured within a layer:

1. External, placed in opt/otel-extension/external folder, which gathers information (from (1) execution environment (2) AWS Lambdas APIs (3) Data provided via internal extension) and sends the compliant OpenTelemetry payload to Serverless Console ingestion servers
2. Internal, placed in opt/otel-extension/internal folder, which is pre-run in the same process as Node.js Lambda handler, and through pre-setup instrumentation gathers additional data about invocations, which is sent to external extension

What telemetry payload does it generate? Copy Section

TODO: This section will be completed in the near future

How to configure AWS Lambda to use it? Copy Section

1. Build layer artifact

1.2 Node.js runtime version (external + internal extension)

Note: pre-build layer artifacts are published to our AWS accounts, and instead of building it manually (as documented below) it is advised to rely on them instead (for ARN's of the pre-published layers check registry files which are attached to GitHub releases)

# Ensure layer dependencies are installed
cd external/otel-extension-external
npm install
cd ../../internal/otel-extension-internal-node
npm install

# Build artifact
cd ../../
npm run build

Artifact is generated into dist/extension.zip file

1.3 Runtime agnostic version (just external extension)

Runtime agnostic version (of just external layer) can be built as following

# Ensure layer dependencies are installed
cd external/otel-extension-external
npm install

# Build artifact
cd ../../
npm run build:external

Artifact is generated into dist/extension-external.zip file

1.4 Custom settings

Monitoring settings (as documented below) can also be bundled into generated layers, for that pass path to settings file with --settings-filename param. File is expected to be a valid Node.js CJS module, It can be plain JSON, or JS, which can be helpful in case of dynamically resolved settings

npm run build -- --settings-filename <path>

2. Publish layer

Publish layer artifact to your AWS account

3. Attach layer to target Lambda and configure necessary environment variables

Ensure that layer version ARN is listed in Lambda layers.

Ensure that internal extension of a layer is pre-loaded by configuring AWS_LAMBDA_EXEC_WRAPPER environment variable with /opt/otel-extension-internal-node/exec-wrapper.sh

4. Configure monitoring settings

Monitoring settings are expected to be provided in JSON format at SLS_EXTENSION environment variable.

Required settings:

`orgId`

Serverless Console organization id

`namespace`

Namespace at which reports should be grouped (Serverless Framework sets it with service name)

`environment`

Application environment (Serverless Framework sets with stage value)

`ingestToken`

Serverless Console ingestion token, to be obtained via Serverless Console API. At this point it's resolved automatically in context of the Serverless Framework (manual resolution instructions will be provided in a near future)

Optional settings:

`logs`

Settings that affect log monitoring. Supported options:

• logs.disabled - Set to true to disable logs monitoring

`request`

Settings that affect requests monitoring. Supported options:

• request.disabled - Set to true to disable requests monitoring

`response`

Settings that affect response monitoring. Supported options:

• response.disabled - Set to true to disable response monitoring

Generated reports structure Copy Section

TODO: Complete documentation on generated telemetry reports is in the works

Response reports

Any non JSON objects in either a simple response or a HTTP response payload are not included

For example, the following will be sent without any modifications 👇

{ "message": "lambda response" }

{ "statusCode": 200, "body": "{\"message\": \"lambda response\"}" }

The following responses will be altered

Simple non JSON object responses will be ignored

HTTP Responses with a non JSON body will be ignored

Tests Copy Section

Tests can only be run in context of package repository (they're not included with npm package).

See Tests documentation

File: node/packages/aws-lambda-otel-extension/CHANGELOG.md Copy Chapter

Changelog

All notable changes to this project will be documented in this file. See standard-version for commit guidelines.

[0.5.2](https://github.com/serverless/runtime/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-07-14) Copy Section

Bug Fixes Copy Section

• Ensure broken settings do not break extension (9d09dfd)

[0.5.1](https://github.com/serverless/runtime/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-07-14) Copy Section

Performance Improvements Copy Section

• Patch ineffective require-in-the-middle setup (62672b9)

[0.5.0](https://github.com/serverless/runtime/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-07-12) Copy Chapter

⚠ BREAKING CHANGES Copy Section

• Configuration variable SLS_OTEL_USER_SETTINGS is renamed to SLS_EXTENSION
• Introduce new mandatory orgId, namespace and environment settings (required by the Serverless Console)
• Extension is no longer observability tool agnostic. It's reconfigured to report specifically to the Serverless Console.
  At the same time its configuration settings are simplified:
  • Support for destination in all configuration groups is dropped.
  • New required ingestToken property is introduced (for injection of kinesis server authentication token)
  • Support for metrics.outputType and traces.outputType was removed (reports are hardcoded to be send in protobuf.

Features Copy Section

• New mandatory orgId, namespace and environment settings (cc009de)
• On invalid user settings make extension ineffective (8f7128b)
• Remove support for [metrics|traces].outputType (91e7e03)
• Rename SLS_OTEL_USER_SETTINGS into SLS_EXTENSION (aa2b00b)
• Unconditionally send reports to the Serverless Console (80ef8dc)
• Support bundling of custom settings into layers (cd699bc)
• Allow environment changes in bundled settings (6e7bf67)

Maintenance Improvements Copy Section

• Add debug log on event/next response (33950f2)
• Centralize user settings handling (b2bb89d)
• Improve clarity of build script (3db6c0d)

[0.4.6](https://github.com/serverless/runtime/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-06-29) Copy Section

Bug Fixes Copy Section

• Fix handling of promise resolution (867b3bc)

Maintenance Improvements Copy Section

• Improve resolution handling (938ce98)
• Simplify stale callback handling (fb2885a)

[0.4.5](https://github.com/serverless/runtime/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-06-29) Copy Section

Bug Fixes Copy Section

• Fix handling of a case where telemetryData arrives before eventData (26991ee)

Maintenance Improvements Copy Section

• Add debug logs on internal extension requests timing (2d2c2db)
• Ensure to reuse HTTP(S) connection sockets (82d295a)
• Remove node-fetch dependency (688e24d)

[0.4.4](https://github.com/serverless/runtime/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-06-27) Copy Section

Bug Fixes Copy Section

• Fix handling of doubled resolution (8eacf17)

Performance Improvements Copy Section

• Optimize protobuf encoding by using pre-compiled interface (70f26e6)
• Improve telemetry server response time (60ae043)

Maintenance Improvements Copy Section

• Clarify wrapping logic (2b203f0)
• Cleanup invalid async mark (7423971)

[0.4.3](https://github.com/serverless/runtime/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-06-23) Copy Section

Features Copy Section

• Add attributes and resource to req/res payload (18d69e9)

Maintenance Improvements Copy Section

• Changed getCurrentRequestData to getRequestContext (a80a961)
• Added invoke time to internal context (c70d60a)

[0.4.2](https://github.com/serverless/runtime/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-06-15) Copy Section

Maintenance Improvements Copy Section

• Adjusted errorType for handled/unhandled (4fe0437)
• Updated timeout errorType (d9b60cd)

[0.4.1](https://github.com/serverless/runtime/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-06-13) Copy Section

Bug Fixes Copy Section

• Fix ESM support in Node.js v16 runtime (2547826)

Maintenance Improvements Copy Section

• Cleanup timeout setup (ec7c67a)
• Debug log telemetry data cache handling (b69e62f)
• Ensure to flush report in one log line (64ca1dd)
• Generalize debugLogs handling (bd6340b)
• Improve debug logging (6aef91c)
• Unify debug log handling (57aceba)

[0.4.0](https://github.com/serverless/runtime/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-06-02) Copy Chapter

⚠ BREAKING CHANGES Copy Section

• All configuration settings are now set in JSON object in context of SLS_OTEL_USER_SETTINGS environment variable. Handling of following environment variables was replaced:
  • SLS_OTEL_REPORT_METRICS_URL (replaced by metrics.destination)
  • SLS_OTEL_REPORT_TRACES_URL (replaced by traces.destination)
  • SLS_OTEL_REPORT_LOGS_URL (replaced by logs.destination)
  • SLS_OTEL_REPORT_REQUEST_RESPONSE_URL (replaced by request.destination and response.destination)
  • SLS_OTEL_REPORT_REQUEST_HEADERS (replaced by common.destination.requestHeaders)
• disableLogsMonitoring is replaced by logs.disabled
• disableRequestResponseMonitoring is replaced by request.disabled and response.disabled

Features Copy Section

• Generalize request handling and integrate settings propagated via environment variables into user settings (e73acca)
• Support new user settings format (c6904b6)

Bug Fixes Copy Section

• Wait for request/response hooks before settling invocation (6742606)
• Ensure to handle property thenable/callback race (77bf67f)

Maintenance Improvements Copy Section

• Do not accept multiple paylaods at request functions (db33381)

[0.3.2](https://github.com/serverless/runtime/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-05-31) Copy Section

Features Copy Section

• Filter out Serverless Dashboard data logs (b35c41c)

[0.3.1](https://github.com/serverless/runtime/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-05-26) Copy Section

Bug Fixes Copy Section

• Fix dependencies configuration (9b41fa6)

Maintenance Improvements Copy Section

• Bundle internal and external extensions into a single file (9195c1e)
• Distinguish JSON from request data (aa0141b)
• Improve debug log for ingestion server requests (d2b5233)
• Improve debug log for telemetry payload (b133ea6)
• Log extension overhead processing durations (7ddb265)
• Remove obsolete debug log (59ae9a8)
• Rename logMessage to debugLog (b7c2edc)
• Simplify protobuf processing (e339066)

[0.3.0](https://github.com/serverless/runtime/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-05-23) Copy Chapter

⚠ BREAKING CHANGES Copy Section

• Path to exec wrapper has changed from /opt/otel-extension/internal/exec-wrapper.sh to /opt/otel-extension-internal-node/exec-wrapper.sh. Change should be reflected when configuring AWS_LAMBDA_EXEC_WRAPPER environment variable for lambda

Features Copy Section

• Build script for runtime agnostic version of external extension (e9fb48c)
• Split internal and external extension into independent extensions (13a7a72)

Bug Fixes Copy Section

• Fix handling of JSON type payloads (5ba0175)

Maintenance Improvements Copy Section

• Rewrite external extension (73cfc5c)
• Drop node-fetch dependency in external extension (cca15ed)
• Provide separate userSettings source for both extensions (5a6909d)
• Remove lodash.isobject dependency (4773a7c)
• Remove OTEL_SERVER_PORT definition from common scope (fe443a7)
• Remove common logMessage (a620a06)

[0.2.21](https://github.com/serverless/runtime/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-04-29) Copy Section

Features Copy Section

• Avoid sending binary response data (dbb3711)

[0.2.20](https://github.com/serverless/runtime/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-04-26) Copy Section

Bug Fixes Copy Section

• Updated timeout error message (2f49bcd)

[0.2.19](https://github.com/serverless/runtime/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-04-21) Copy Section

Features Copy Section

• Suport userSettings.disableLogsMonitoring (54d1fa9)
• Support userSettings.disableRequestResponseMonitoring (b7998b4)

Maintenance Improvements Copy Section

• Centralize log listener server handling (39fb512)
• Centralize log listener server host and port configuration (1c38e2d)
• Centralize subscription configuration (c6ffbc8)
• Improve handling of dead paths (9336587)
• Remove obsolete error handling (7310032)
• Remove obsolete handling from telemetry server (247dec6)
• Reorder initial setup (7f9e364)

[0.2.18](https://github.com/serverless/runtime/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-04-13) Copy Section

Bug Fixes Copy Section

• Adjusted code for integration tests (5709511)
• fixed integration test (81aa93f)
• Fixed waitFor bug (8cf697a)

[0.2.17](https://github.com/serverless/runtime/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-04-13) Copy Section

Bug Fixes Copy Section

• fixed integration test (81aa93f)
• Fixed waitFor bug (8cf697a)

[0.2.13](https://github.com/serverless/runtime/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-04-13) Copy Section

Bug Fixes Copy Section

• Fixed waitFor bug (aa0658c)

[0.2.12](https://github.com/serverless/runtime/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-04-13) Copy Section

Bug Fixes Copy Section

• Include spanId in req/res data (1801503)

Maintenance Improvements Copy Section

• Automate extension version resolution (d1d8c12)
• Improve faas.collector_version format (9ccbfa1)
• Optimize instrumentations setup (99b47fd)
• Prevent misleading "No modules.." warning (85fbc39)
• Remove obsolete config configuration (5b448ba)
• Remove obsolete instrumentation registration (014b6b3)
• Remove obsolete payload compression (f5ceb3d)

File: node/packages/aws-lambda-otel-extension/package.json Copy Chapter

{
"name": "@serverless/aws-lambda-otel-extension",
"repository": "serverless/runtime",
"version": "0.5.2",
"author": "Serverless, Inc.",
"dependencies": {
"adm-zip": "^0.5.9",
"child-process-ext": "^2.1.1",
"esbuild": "^0.14.49",
"essentials": "^1.2.0",
"fs2": "^0.3.9",
"memoizee": "^0.4.15",
"protobufjs": "^6.11.3",
"semver": "^7.3.7",
"yargs-parser": "^21.0.1"
},
"standard-version": {
"tagPrefix": "@serverless/aws-lambda-otel-extension@",
"path": ".",
"skip": {
"commit": true,
"tag": true
},
"types": [
{
"type": "feat",
"section": "Features"
},
{
"type": "fix",
"section": "Bug Fixes"
},
{
"type": "perf",
"section": "Performance Improvements"
},
{
"type": "refactor",
"section": "Maintenance Improvements"
}
]
},
"scripts": {
"build": "./scripts/build.js dist/extension.zip",
"build:external": "./scripts/build.js dist/extension-external.zip --mode=2",
"build:internal": "./scripts/build.js dist/extension-internal.zip --mode=1",
"generate-proto": "pbjs -t static-module -w commonjs -o external/otel-extension-external/proto.js proto/metric-service.proto proto/trace-service.proto",
"prepare-release": "standard-version && prettier --write CHANGELOG.md",
"test": "mocha "test/unit//*.test.js"",
"test:isolated": "mocha-isolated "test/unit//.test.js"",
"test:integration": "mocha "test/integration/**/.test.js"",
"test:performance": "mocha test/benchmark/performance.test.js"
},
"publishConfig": {
"access": "public"
},
"license": "MIT"
}

File: node/packages/aws-lambda-otel-extension/external/otel-extension-external/package.json Copy Chapter

{
"dependencies": {
"protobufjs": "^6.11.3"
}
}

File: node/packages/aws-lambda-otel-extension/internal/otel-extension-internal-node/package.json Copy Chapter

{
"dependencies": {
"@opentelemetry/api": "~1.0.4",
"@opentelemetry/core": "^1.4.0",
"@opentelemetry/instrumentation": "^0.27.0",
"@opentelemetry/instrumentation-aws-lambda": "^0.28.1",
"@opentelemetry/instrumentation-aws-sdk": "^0.5.1",
"@opentelemetry/instrumentation-dns": "^0.27.1",
"@opentelemetry/instrumentation-express": "^0.27.1",
"@opentelemetry/instrumentation-fastify": "^0.26.0",
"@opentelemetry/instrumentation-graphql": "^0.27.4",
"@opentelemetry/instrumentation-grpc": "^0.27.0",
"@opentelemetry/instrumentation-hapi": "^0.27.1",
"@opentelemetry/instrumentation-http": "^0.27.0",
"@opentelemetry/instrumentation-ioredis": "^0.27.1",
"@opentelemetry/instrumentation-koa": "^0.28.1",
"@opentelemetry/instrumentation-mongodb": "^0.28.0",
"@opentelemetry/instrumentation-mysql": "^0.27.1",
"@opentelemetry/instrumentation-net": "^0.27.1",
"@opentelemetry/instrumentation-pg": "^0.28.0",
"@opentelemetry/instrumentation-redis": "^0.28.0",
"@opentelemetry/resource-detector-aws": "^1.1.1",
"@opentelemetry/resources": "^1.4.0",
"@opentelemetry/sdk-trace-base": "^1.4.0",
"@opentelemetry/sdk-trace-node": "^1.4.0",
"lodash.clone": "^4.5.0",
"lodash.get": "^4.4.2",
"require-in-the-middle": "^5.1.0"
}
}

File: node/packages/aws-lambda-otel-extension/test/README.md Copy Chapter

Tests

Unit tests Copy Chapter

Unit tests are configured to be independent of any external infrastructure (AWS Lambda environment is emulated), and can be run offline

npm test

Integration tests Copy Chapter

AWS account is needed to run integration tests, and AWS credentials need to be configured.

In tests, the home folder is mocked, therefore AWS access cannot be reliably set up via the AWS_PROFILE variable or any other means that rely on configuration placed in the home folder.

Easiest is to run tests is by setting AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_REGION environment variables.

Tests create a temporary layer and Lambda resources and remove them after the test is finalized.

All created resourced are named or prefixed with test-otel-extension-<testUid> string, where testUid is four characters taken from local machine id or in case of CI runs a random string. testUid string can also be overridden via environment variable TEST_UID

npm run test:integration

Performance tests Copy Chapter

Both AWS credentials Serverless Console credentials are needed to run performance test.

Test confirms on performance of the extension instrumentation. Specifically they validate whether introduced initialization and invocation duration overhead doesn't go beyond agreed threshold.

Same as in case of integration tests, home folder is mocked, so AWS credentials cannot be set via AWS_PROFILE (easiest it to provide them via AWS_ACCESS_KEY_ID, and AWS_SECRET_ACCESS_KEY).

Console credentials need to be provided with following environment variables:

• SLS_ORG_NAME - Name of the organization
• SLS_ORG_TOKEN - Authentication org token, which can be obtained for given organization in Console UI

Otherwise characteristic of test is very same as in case of integration tests (please follow it's documentation)

npm run test:performance

Environment variables Copy Chapter

How extensions behave, for various testing purposes, can be tweaked with following environment variables:

Variables handled in extension logic Copy Section

• SERVERLESS_PLATFORM_STAGE - Ingestion server stage to which reports should be propagated (default is prod, with this setting it can be overridden to dev)
• SLS_DEBUG_EXTENSION - Log debug messages, of which scope is to:
  • Mark certain processing points
  • Log payloads which are send between extensions and to the external ingestion server
  • Report durations overhead that extension introduces
• SLS_TEST_EXTENSION_INTERNAL_LOG - In context of the internal extension, log payloads instead of sending them to the external extension
• SLS_TEST_EXTENSION_HOSTNAME - Custom environment hostname. Used to override sandbox when setting up log subscription server
• SLS_TEST_EXTENSION_REPORT_TYPE - Set to json to pass reports in direct JSON format instead of Protobuf
• SLS_TEST_EXTENSION_REPORT_DESTINATION - Telemetry reports normally are sent to the Console ingestion servers, with this variable this can be overridden:
  • Set to s3:////<root-key> to send reports to S3 bucket
  • Set to log to just log reports into process stdout

Variables handled by test suite Copy Section

• SLS_TEST_EXTENSION_COMMAND - (Processed only in context of the external extension unit test) A command to run external extension process (e.g. node path/to/external-extension/module.js)
• TEST_LAYER_FILENAME - Path to .zip file of a layer which contains both external and internal Node.js extensions, against which tests should be run
• TEST_EXTERNAL_LAYER_FILENAME - Path to .zip file of a layer which contains external (runtime agnostic) extension. Triggers mode in which two layers are attached to the lambda (one with external and other with internal extension)
• TEST_INTERNAL_LAYER_FILENAME - Path to .zip file of a layer which contains just internal Node.js extension. Triggers mode in which two layers are attached to the lambda (one with external and other with internal extension)

File: node/packages/aws-lambda-otel-extension/test/benchmark/README.md Copy Chapter

Benchmarks

Tested use cases Copy Chapter

Node.js function ([`callback`](../../fixtures/lambdas/callback.js)) Copy Section

No-op Node.js function. Handler takes callback and immediately invokes it with dummy payload

Node.js + Express function ([`express`](../../fixtures/lambdas/express.js)) Copy Section

Simple express app with two endpoints which respond with dummy payload.
Function is invoked with payload that reflects one that function will receive if it would be triggered through API Gateway integration

Node.js 250ms function ([`250ms`](../../fixtures/lambdas/250ms.js)) Copy Section

No-op Node.js function. Handler takes callback waits 250ms and invokes it with dummy payload.
In this case produced extension invocation overheads are slightly smaller as some of the extension work is done during lambda operation

Node.js 1s function ([`1s`](../../fixtures/lambdas/1s.js)) Copy Section

No-op Node.js function. Handler takes callback waits 1 second and invokes it with dummy payload.
In this case, produced extension invocation overheads are additionally reduced. Tests show that for longer going functions overheads remain same as for that one

Node.js heavy logging function ([`logger`](../../fixtures/lambdas/logger.js)) Copy Section

Logs 1000 individual log messages via console.log in short time frames

It's the only case which writes any logs (in other cases log reporting is not existing).

Benchmark variants Copy Chapter

`bare` Copy Section

No instrumentation (bare run with no extension layers onboard).

As there are no extensions loaded, there's no extension duration overhead introduced, and benchmark will naturally report them with zeros.

What we get is metrics from AWS report, that confirm on initialization duration, invocation duration, billed invocation duration and max memory used.

`externalOnly` Copy Section

Just external extension which processes lambda event cycle. As no internal extension is loaded, no reports are processed and send by the external extension.

Difference from bare is that external extension process is initialized by AWS, and its that process that monitors and queues lambda invocation event cycle.

This additional process management introduces natural duration overhead which is best calculated by reading duration as reported by AWS for this variant and subtracting from it a bare variant duration

There's no time spent here on processing reports and propagating them to the ingestion server (as none are to be send from the internal extension). So internally measured invocation duration overhead of external extension is also reported as not existing

`internalOnly` Copy Section

Just internal extension which generates telemetry reports and logs them to the console (when external extension is loaded those would be send to the external extension)

Difference from bare is that original lambda logic is additionally wrapped with internal extension log. Measured difference simply show what overhead is produced by gathering telemetry in context of the lambda handler process.

`jsonLog` Copy Section

External & internal extensions are loaded. Internal extension operates fully (generates telemetry and sends it to external extension), while in external extension just report payloads are generated and logged into stdout (there's no conversion to Protobuf and not reporting to the remote ingestion server).

Difference from externalOnly is purely that internal extension is loaded and fully active and that it sends reports to the external extension.

Comparing its duration overhead against externalOnly and subtracting overehead of internalOnly shows how much overhead is introduced by sending telemetry payloads to the external extension and processing it in its scope

`protoLog` Copy Section

Exactly same as jsonLog with a difference, that in the external extension JSON payloads are converted to the Protobuf (and it's Protobuf output that's logged to the stdout)

Comparing duration differences with jsonLog we can see how much overhead is generated by Protobuf conversion

`console` Copy Section

Exactly same as protoLog but external extension reports the generated payloads to the ingestion server.

Comparing duration differences with protoLog we can see how much overhead is generated by communication with the remote ingestion server

Reported metrics Copy Chapter

Each benchmark variant is run against 5 lambda instances.

Therefore for each metric outlined below, we get 5 numbers. Durations returned in result report are averages of those 5 values.

Internally measured durations are written by the extensions to the stdout, and are read (together with invocation reports as written by AWS) from CloudWatch logs.

Observed AWS Lambda execution lifecycle phases Copy Section

Initialization (`init`)

Lambda instance initialization

Observed metrics

`init:external`

Duration of the external extension initialization logic, measured internally in external extension. It's the time between start of the external extension process, and reporting to the AWS extension API that we're ready to process Lambda invocations (AWS won't run any invocations until we do that).

This won't cover total external extension process initialization time, which is also taken by initialization of the process on its own.
Currently through benchmark reports we can see that external extension initialization takes ca 100ms, while internally measured initialization takes ca 30ms)

`init:internal`

Duration of the internal extension initialization logic, measured internally in internal extension. It's a time measured from start of the internal extension logic, until it returns for further evaluation by AWS runtime engine.

This initialization is synchronous, but internal extension may propagate some async tasks, of which processing is then mixed with tasks as issued eventually by lambda initialization logic (if it's asynchronous) or first invocation logic.

Due to how otel libraries are designed, internal extension issues an asynchronous task, still it's very minimal and shouldn't introduce any notable overhead.

As internal extension runs in very same process as lambda, there's we don't deal with other process initialization overhead. Still as this extension is handled by AWS runtime logic which otherwise is not triggered, and pollutes process memory with its objects, we still can observe some extra overhead not covered by this metric.
Currently through benchmark reports, we can see that internal extension initialization (for noop lambda) takes ca 150ms, while internally measured initialization takes ca 120ms

`init:total`

Total initialization time as reported by AWS (with initDuration metric provided in report of the first invocation)

Invocation

Benchmarks observe first invocation (first) (one that in regular circumstances immediately follows initialization), and the the second (following).

Two first invocations are observed separately, as data shows that durations of first invocation are always worse than of the second, and that for the following (third, fourth etc.) invocations numbers are similar as for the second.
This difference could be attributed to how Node.js internal optimization works, where paths which were already taken usually run faster (it's to be confirmed whether we see similar differences with other runtimes).

Observed metrics

`[first|following]:internal:request`

Invocation request handing duration in context of the Node.js internal extension. It's a time that's measured from the moment when our handler wrapper received an invocation event from AWS until we invoke the original Lambda handler.

It's a synchronous task, but extension logic starts asynchronous request to the external extension, which is processed when original lambda logic is run (or after it ends processing, in case of fast resolving lambda). This means that the extension and original handler tasks ordering is mixed, and we cannot reliably measure internally an overhead as introduced by the internal extension request handling in total.

`[first|following]:internal:response`

Invocation response handling duration in the context of the Node.js internal extension. It's a time that's measured from the moment when original handler provided response until we pass it back to AWS.

This one is asynchronous, as we propagate the response only after we're certain that extension request and response handlers have finalized its tasks (send successfully the telemetry data to the external extension).

`[first|following]:external`

Time spent in context of external extension process between receiving the platform.runtimeDone event (which signals that ongoing invocation have ended) and reporting via AWS Lambda extension API that we're ready to process next invocation )(external extension reports that only after all started ingestion server requests are finalized)

`[first|following]:total`

Total duration time as reported by AWS (with duration metric provided in invocation report)

`[first|following]:billed`

Billed duration time as reported by AWS (with billedDuration metric provided in invocation report)

`[first|following]:local

Locally measured SDK invocation time. This value is largely influenced by the location from which we run benchmarks and quality of the internet connection.

For benchmarks run against us-east-1 region, shortest values we'll get e.g. in New York, but running benchmarks in San Francisco will already add extra latency, and numbers get additionally worse, when running benchmarks from farther locations

`[first|following]:maxMemoryUsed

Max memory used as reported by AWS (with maxMemoryUsed metric provided in invocation report). It's to expose what memory overhead is introduced by the extensions

Summary Copy Section

While overhead durations as measured and reported by the extensions internally help to coin where exactly performance bottlenecks occur, the real extension overhead numbers can only be deducted from durations as reported by the AWS.

With benchmark variants, as setup correctly. It's safe to assume that:

• Comparing durations of externalOnly vs bare expose the overhead of the AWS Lambda event lifecycle handling in the external extension
• Comparing durations of internalOnly vs bare expose the overhead of the internal extension telemetry generation
• Comparing durations of jsonLog vs externalOnly and subtracting overhead as observed with internalOnly informs us of overhead introduced by sending telemetry payloads from internal to the external extension and processing it in its scope
• Comparing durations of protoLog vs jsonLog expose the overhead of the Protobuf conversion that happens in external extension
• Comparing durations of console vs protoLog expose the overhead of the communication with ingestion server that happens in external extension

Setup & Run Copy Chapter

1. Ensure all dependencies are installed: Copy Section

Run npm install in following folders:

• external/otel-extension-external
• internal/otel-extension-internal-node
• test/fixtures/lambdas

2. Ensure AWS credentials Copy Section

In same manner as for AWS CLI

3. Configure environment variables Copy Section

• AWS_REGION - region against which benchmarks should be run
• SLS_ORG_NAME & SLS_ORG_TOKEN- (optional) Needed to benchmark scenario of reporting to the Console Kinesis server (if not provided, console variant will not be tested)
• TEST_UID - (optional) common name token to be used as part of generated resource names. All generated resource names will be prefixed with test-oext-<test-uid>. If not provided, one is generated on basis of local machine id. Note: Script ensures that all generated resources are removed after benchmark is done
• LOG_LEVEL - (optional) For more verbose output LOG_LEVEL=info can be used

4. Run Copy Section

Benchmark for all configured use cases and benchmark variants can be run as:

./test/scripts/benchmark.js

Generated benchmark results are output to the console in CSV format. To store them to the file output can be piped as:

./test/scripts/benchmark.js > benchmark.csv

4.1 Run customization Copy Section

Benchmark run can additionally be customized with following CLI params

• --use-cases Comma separated list of function use cases to test (e.g. callback,express)
• --benchmark-variants Comma separated list of benchmark variants to test (e.g. bare,externalOnly)
• --memory-size Memory size to provide to lambdas (by default it's 128MB).
• --extension-layers-mode By default benchmark are run against single layer which contains Node.js external and internal extension. By setting dual value for this mode, benchmark will be run with those two extensions provided as separate layers (and external layer will come with Node.js binary bundled)

Additionally extension layers that are used for testing can be overridden with following environment variables:

• TEST_LAYER_FILENAME - Path to .zip file of a layer which contains both external and internal Node.js extensions. Ineffective with --extension-layers-mode=dual
• TEST_EXTERNAL_LAYER_FILENAME - Path to .zip file of a layer which contains external (runtime agnostic) extension. Effective only with --extension-layers-mode=dual
• TEST_INTERNAL_LAYER_FILENAME - Path to .zip file of a layer which contains just internal Node.js extension. It's effective for internalOnly benchmark variant, and in other cases effective only with --extension-layers-mode=dual

File: node/packages/aws-lambda-otel-extension/test/fixtures/lambdas/package.json Copy Chapter

{
"dependencies": {
"express": "^4.18.1",
"serverless-http": "^3.0.1"
}
}

File: node/packages/aws-lambda-otel-extension/test/fixtures/lambdas/esm-callback/package.json Copy Chapter

{
"type": "module"
}

File: node/packages/aws-lambda-sdk/README.md Copy Chapter

@serverless/aws-lambda-sdk

AWS Lambda [Serverless Console](https://www.serverless.com/console) SDK Copy Chapter

Instruments AWS Lambda functions, propagates traces to the Serverless Console and exposes Serverless SDK to function logic

Setup Copy Section

1. Register with [Serverless Console](https://console.serverless.com/)

2. In [Serverless Console](https://console.serverless.com/) turn on integration for your AWS account and chosen Lambdas

3. (optionally) Fine tune default instrumentation behavior with following options

`SLS_DISABLE_HTTP_MONITORING` (or `options.disableHttpMonitoring`)

Disable tracing of HTTP and HTTPS requests

`SLS_DISABLE_REQUEST_RESPONSE_MONITORING` (or `options.disableRequestResponseMonitoring`)

(Dev mode only) Disable monitoring requests and reponses (function, AWS SDK requests and HTTP(S) requests)

`SLS_DISABLE_AWS_SDK_MONITORING` (or `options.disableAwsSdkMonitoring`)

Disable automated AWS SDK monitoring

`SLS_DISABLE_EXPRESS_MONITORING` (or `options.disableExpressMonitoring`)

Disable automated express monitoring

`SLS_DISABLE_TRACE_SAMPLING` (or `options.disableTraceSampling`)

Disable automatic trace sampling

Instrumentation Copy Section

AWS Lambda SDK automatically creates aws.lambda, aws.lambda.initialization and aws.lambda.invocation trace spans.
For more details see SDK Trace spans documentation

Additionally automatic instrumentation (with caveats) is provided for:

• HTTP(s) requests
• express app
• AWS SDK requests

SDK API Copy Section

• serverlessSdk

File: node/packages/aws-lambda-sdk/CHANGELOG.md Copy Chapter

Changelog

All notable changes to this project will be documented in this file. See standard-version for commit guidelines.

[0.15.15](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-09-27) Copy Section

[0.15.14](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-09-20) Copy Section

Features Copy Section

• Add support for env SLS_DISABLE_TRACE_SAMPLING (#876) (e6601f7)

[0.15.13](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-08-16) Copy Section

Bug Fixes Copy Section

• Update base SDK version and add test fixture for async createSpan (77c1917)

[0.15.12](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-08-10) Copy Section

Bug Fixes Copy Section

• Use createSpan instead of createTraceSpan (d455c52)

[0.15.11](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-08-03) Copy Section

Features Copy Section

• Add createTraceSpan support (58f3667)

[0.15.10](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-08-02) Copy Section

Features Copy Section

• Support setEndpoint in Lambda SDK (c7766ee)

[0.15.9](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-07-06) Copy Section

Bug Fixes Copy Section

• Ensure NODE_PATH always contains required paths (47acfd2)
• Ensure to expose uncaught exceptions (45e4893)
• Instrument @smithy scoped smithy client (f6fe1d7)
• Unregister @smithy/smithy-client instrumentation on uninstall (31e8b9b)

[0.15.8](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-06-23) Copy Section

Bug Fixes Copy Section

• Fix handling of request truncation (ca7d46b)

[0.15.7](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-06-22) Copy Section

Features Copy Section

• Do not sample infrequently invoked functions (da93c42)
• Increase sampling rate to 20% (a3ca4a3)

[0.15.6](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-06-15) Copy Section

Features Copy Section

• Truncate payload if exceeds 256KB (516f32d)

[0.15.5](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-06-07) Copy Section

Adapt updates from v0.5.20 of @serverless/sdk

[0.15.4](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-05-30) Copy Section

Bug Fixes Copy Section

• Fix handling of case where runtime waits for an empty event loop (947a769)

[0.15.3](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-05-25) Copy Section

Bug Fixes Copy Section

• Fix handling of not responding handlers (7d06d67)

Maintenance Improvements Copy Section

• Access sub spans collection directly (251fce4)

[0.15.2](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-05-18) Copy Section

Bug Fixes Copy Section

• Placeholder stream values when reporting request/response body (03b3161)

Maintenance Improvements Copy Section

• Improve organization of replacer logic (92bb89e)

[0.15.1](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-05-17) Copy Section

Features Copy Section

• Support response streaming (2e7f8d0)
• Do not write dev mode specific events in trace payload (a324263)

Maintenance Improvements Copy Section

• Improve filter logic organization (50166a0)

[0.15.0](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-05-11) Copy Chapter

⚠ BREAKING CHANGES Copy Section

• Telemetry payloads prefixed with SERVERLESS_TELEMETRY.T. are replaced with gzipped payloads written with SERVERLESS_TELEMETRY.TZ. prefix

Performance Improvements Copy Section

• Improve size of written telemetry log by gzipping it (#738) (3d28670)

[0.14.23](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-05-10) Copy Section

Maintenance Improvements Copy Section

• Black box AWS SDK spans via new dedicated method (1266baa)

[0.14.22](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-05-04) Copy Section

Adapt updates from v0.5.16 of @serverless/sdk

[0.14.21](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-04-28) Copy Section

Adapt updates from v0.5.15 of @serverless/sdk

[0.14.20](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-04-27) Copy Section

Adapt updates from v0.5.14 of @serverless/sdk

[0.14.19](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-04-27) Copy Section

Features Copy Section

• Improve sampling resolution (beb7208)

Bug Fixes Copy Section

• Ensure our --require option is first (e7d8a3e)

[0.14.18](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-04-26) Copy Section

Maintenance Improvements Copy Section

Adapt updates from v0.5.12 of @serverless/sdk

[0.14.17](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-04-21) Copy Section

Bug Fixes Copy Section

• Ensure sdk.runtime tag on all payloads (5f44099)

Maintenance Improvements Copy Section

• Remove no longer supported option (9ecade7)

[0.14.16](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-04-20) Copy Section

Maintenance Improvements Copy Section

Adapt bug fixes from @serverless/sdk to v0.5.10

[0.14.15](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-04-20) Copy Section

Maintenance Improvements Copy Section

Adapt bug fixes from @serverless/sdk to v0.5.9

[0.14.14](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-04-14) Copy Section

Bug Fixes Copy Section

• Span not closed warnings are now user warnings (#649) (d2b958c)

[0.14.13](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-04-14) Copy Section

Features Copy Section

• Add Structured Logging error capture (#643) (59db882)

[0.14.12](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-04-12) Copy Section

Bug Fixes Copy Section

• SDK will report warning for unclosed spans (#635) (77192f3)

[0.14.11](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-04-06) Copy Section

Features Copy Section

• Improve sampling algorithm (0428512)
• Recognize ALB events (4ceaca3)

Bug Fixes Copy Section

• Ensure to clear root span in case of internal error (#611) (7c7856e)

Maintenance Improvements Copy Section

• Improve configurablity of sampling function (e26be68)
• Seclude isApiEvent util (81d7e4a)

[0.14.10](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-04-03) Copy Section

Bug Fixes Copy Section

• Ensure aws-lambda-sdk types match aws-sdk (#597) (1e1b739)

[0.14.9](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-03-29) Copy Section

Features Copy Section

• Write sdk.runtime tag (065af50)

[0.14.8](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-03-15) Copy Section

Features Copy Section

• Enforce 20% sampling on successful invocations in prod environment (80a02b4)

[0.14.7](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-02-28) Copy Section

Bug Fixes Copy Section

• Ensure to not capture logs issued by the AWS runtime (2df64ee)

[0.14.6](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-02-10) Copy Section

Features Copy Section

• Strip binary lambda request (2b85fe8)
• Strip large lambda request and response bodies (afd9ec9)
• Strip too large AWS SDK request bodies (de064c1)

Maintenance Improvements Copy Section

• Do not strip non JSON bodies (431b48e)
• Ensure to not proces request and response when not in dev mode (9d016aa)
• Exclude runEsbuild util (7d985c4)
• Report binary response body removal with notice event (52588a0)

[0.14.5](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-02-02) Copy Section

Maintenance Improvements Copy Section

Upgrade to @serverless/sdk to v0.5.0

• Adapt to utility rename done on SDK side (2f16112)
• Reconfigure warnings with ._reportWarning (22b8d4f)

[0.14.4](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-02-01) Copy Section

Upgrade to @serverless/sdk to v0.4.4

[0.14.3](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-01-30) Copy Section

Features Copy Section

• Prevent lambda crashes on internal SDK errors (6f350a9)

Bug Fixes Copy Section

• Do not send root span without required tag to dev mode (44b0e4e)
• Fix AWS SDK v3 request error reporting (3dd663c)
• Fix handling of uncommon AWS SDK error report (64afe99)
• Fix invocation closure race condition (13649b2)

Maintenance Improvements Copy Section

• Rely on newly introduced reportSdkError util (e7d9cc0)
• Clear dead referrences to global.serverlessSdk (048e72e)
• Improve logic explanation (96c39a6)
• Improve readability of inline comment (e6a40a2)

[0.14.2](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-01-26) Copy Section

Maintenance Improvements Copy Section

• Upgrade to SDK v0.4.1 (efc2220)

[0.14.1](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-01-23) Copy Section

Bug Fixes Copy Section

• Ensure to clear custom tags collection between invocations (b8eadb6)

[0.14.0](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-01-19) Copy Chapter

⚠ BREAKING CHANGES Copy Section

• Outcome error meta is no longer provided with outcome error tags on aws.lambda root span.
  Instead it's transported with captured event which shares same timestamp with aws.lambda root span end time
• Global custom tags are exposed on TracePayload instead of the root span

Features Copy Section

• Propagate all captured events to dev mode (e19b41e)

Bug Fixes Copy Section

• Ensure to not instrument requests signing (ebf90ca)
• Handle gently non JSON compliant AWS SDK input and output (321a8f5)

Maintenance Improvements Copy Section

• Expose custom tags directly on trace instead of root span (91786ae)
• Remove responseStartTime in favor of endTime (33618d6)
• Report outcome error data with event instead of root span tags (87766c9)

[0.13.1](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-01-13) Copy Section

Features Copy Section

• Report traces at unhandled exceptions in invocation phase (eadeaee)
• Upgrade to @serverless/sdk v0.3.1 (Introduce servelressSdk.setTag) (78c5532)

Maintenance Improvements Copy Section

• Support trace closure at initialization phase (48262d0)

[0.13.0](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-01-12) Copy Chapter

⚠ BREAKING CHANGES Copy Section

• Upgrade to @serverless/sdk v0.3. serverlessSdk.captureTraceSpan is no longer available

Features Copy Section

• Upgrade to @serverless/sdk v0.3 (e415fbc)
• Report internal warnings with structured logs (63d046a)
• Ensure DynamoDB tags on AWS SDK spans that cover DynamoDbDocument service (#354) (1b49f9e)

[0.12.0](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-01-05) Copy Chapter

⚠ BREAKING CHANGES Copy Section

• global.serverlessSdk was removed. @serverless/aws-lambda-sdk and @serverless/sdk are now exposed in node path and can be required or imported naturally

Features Copy Section

• Expose @serverless/sdk in path instead of realying on a global (8f4ff07)
• Report captured events with a trace payload (5437bd7)
• Send captured events to dev mode (dfb7991)

Bug Fixes Copy Section

• Ensure to reset root span also in case of errors (1d8277c)
• Initialize original handler at AWS intended processing point (60db9bf)

Maintenance Improvements Copy Section

• Centralize SDK resolution (2f8b39c)
• Depend on @serverless/sdk (57e3621)
• Do not send Node's console originated events to dev extension (d3a2e41)

[0.11.6](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-12-19) Copy Section

Bug Fixes Copy Section

• Do not attempt to set AWS SDK request id when there's no request (85f02ad)
• Do not crash in case of AWS SDK v2 double resolution setup (95449b8)

[0.11.5](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-12-13) Copy Section

Bug Fixes Copy Section

• Fix handling of deferred spans, started before handler invocation (0970940)
• To respect open handles wait for response to end (cc3a531)
• Reduce number of concurrently open requests to avoid EMFILE (55d314d)
• Clear input and output for trace payload reliably (03140cb)

Maintenance Improvements Copy Section

• Upgrade @serverless/sdk-schema to v0.14 (365ba4e)
• Limit maximum number of concurrent requests to avoid EMFILE (d16b28c)
• Remove dead code (73c9fa5)

[0.11.4](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-11-24) Copy Section

Bug Fixes Copy Section

• Ensure to not crash in main SDK processing points (5499231)

[0.11.3](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-11-08) Copy Section

Maintenance Improvements Copy Section

• Improve SDK error messaging (f35ff84)

[0.11.2](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-11-03) Copy Section

Bug Fixes Copy Section

• Ensure warning ends with new line (18e902f)

Maintenance Improvements Copy Section

• Improve build script error reporting (c26c936)
• Reshape HTTP request args handling (13a3a53)

[0.11.1](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-10-31) Copy Section

Bug Fixes Copy Section

• Fix handling of no response lambdas (279c5c7)

[0.11.0](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-10-31) Copy Chapter

⚠ BREAKING CHANGES Copy Section

• Upgrade @serverless/sdk-schema from v0.12 to v0.13

Features Copy Section

• Report all kind of responses (2731384)
• Support Node.js v12 (5737b5c)

Bug Fixes Copy Section

• Fix capture of HTTP response body when it's a string (466fc22)

Maintenance Improvements Copy Section

• Cleanup support for startTime and endTime in response (e5ef5e8)
• Upgrade to @serverless/sdk-schema v0.13 (6ad4b72)

[0.10.2](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-10-24) Copy Section

Features Copy Section

• Added timestamp to req/res payloads (#280) (ffc1dcd)

Bug Fixes Copy Section

• Matched invocation start/end time (1080d28)

[0.10.1](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-10-21) Copy Section

[0.10.0](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-10-20) Copy Chapter

⚠ BREAKING CHANGES Copy Section

• SDK Schema is upgraded to v0.11 - http.request_body, http.response_body, aws.sdk.request_body and aws.sdk.response_body tags are removed in favor of top level input and output properties.

Features Copy Section

• Adapt span.input and span.output (bb5e222)

[0.9.1](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-10-17) Copy Section

Features Copy Section

• Do not trace DynamoDb request expressionValues (bbc118d)

[0.9.0](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-10-11) Copy Chapter

⚠ BREAKING CHANGES Copy Section

• Dev mode communication port was changed from 2772 to 2773. For compatibiility upgrade to v0.3+ version of the dev-mode layer

Maintenance Improvements Copy Section

• Switch dev mode communication port (6df2fc9)

[0.8.1](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-10-10) Copy Section

Bug Fixes Copy Section

• Ensure opt-out for request and response monitoring (0555565)

[0.8.0](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-10-07) Copy Chapter

⚠ BREAKING CHANGES Copy Section

• Request and response bodies are not longer reported in CloudWatch logs

Features Copy Section

• Support "dev" mode (8e74674)
• Report AWS SDK request and response body in dev mode (8e87989)
• Expose HTTP request and response bodies in tags in dev mode (eefcb33)
• In dev mode send spans as they are closed to external extension (72b59b8)
• Do not write request and response payloads (6d604c9)

Maintenance Improvements Copy Section

• Improve variables naming (99973ff)
• Support internal _slsIngore option to ignore HTTP requests (85cb986)

[0.7.0](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-09-30) Copy Chapter

⚠ BREAKING CHANGES Copy Section

• Upgrade @serverless/sdk-schema to v0.10 (Switch from express tags to aws.lambda.http_router)
• Rename instrument/*utilities into instrumenation/*
• Rename serveressSdk.instrument into serverlessSdk.instrumentation

Features Copy Section

• Support for Function URL events (d9f619c)
• Switch from express tags to aws.lambda.http_router (64f7543)

Bug Fixes Copy Section

• Fix span connections for consequently initialized async operations (cd2798e)
• Fix open parent span resolution (84f63e9)

Maintenance Improvements Copy Section

• Add temporary debug logs (8588da0)
• Expose debugLog util on serverlessSdk (bb25145)
• Improve middleware span resolution (641a690)
• Rename instrument namespace into instrumentation (88054dc)
• Separate instrument utility context (e159740)

[0.6.0](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-09-26) Copy Chapter

⚠ BREAKING CHANGES Copy Section

• Upgrade @serverless/sdk-schema to v0.9.0
• HTTP related have changed according to changes brought with new version of @serverless/sdk-schema
• Sub spans must be closed manually (they're no longer auto closed with closure of a parent)
• All opened spans are auto closed with a warning on root span closure (when trace is wrapped up)
• onCloseByParent option is replaced by onCloseByRoot, as it's only root that may auto close sub spans now
• traceSpan.createSubSpan method was removed in favor of serverlessSdk.createTraceSpan. Since now relations between spans are resolved automaticaly internally (no need to manually decide which span is parent span)

Features Copy Section

• Allow opened children in closed spans (d2f87d7)
• Resolve relation between spans automatically (a7e2b5e)
• Store http.request_header_names tag (223371c)
• Support new AWS SDK DynamoDB tags (1963d4b)
• Upgrade HTTP related tags to contain only param names information (0fed793)

Bug Fixes Copy Section

• Fix propagation of response data (135c524)

Performance Improvements Copy Section

• Ensure to not add unused dependencies to build (ce2f6e4)

Maintenance Improvements Copy Section

• Improve test error code (a396de3)

[0.5.0](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-09-20) Copy Chapter

⚠ BREAKING CHANGES Copy Section

• Upgrade @serverless/sdk-schema to v0.8

Features Copy Section

• Instrument express applications (be10ac2)
• Trace AWS SDK requests going to any services (c6dbe17)

Maintenance Improvements Copy Section

• Uprade @serverless/sdk-schema to v0.8 (72bfa6d)

[0.4.0](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-09-16) Copy Chapter

⚠ BREAKING CHANGES Copy Section

• Upgrade @serverless/sdk-schema to v0.7

Features Copy Section

• Instrument AWS SDK requests (8fe8676)
• Support ignoring specified HTTP requests from tracing (63a0450)

Bug Fixes Copy Section

• Ensure safe requires order (f853179)

Maintenance Improvements Copy Section

• Do not crash if tag is re-set with same value (d9c5647)
• Make serverlessSdk._initialize private (887bbc4)
• Upgrade @serverless/sdk-schema to v0.7 (2f481f8)

[0.3.2](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-09-14) Copy Section

Features Copy Section

• Write request and response payloads (b04f030)
• An option to disable HTTP instrumentation (c5da3fd)

Maintenance Improvements Copy Section

• Cleanup logic (06869fc)
• Do not write debug JSON payload (f94c874)
• Generalize handling of instrumentation configuration (84887b3)

[0.3.1](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-09-12) Copy Section

Features Copy Section

• Auto tracing of internal HTTP and HTTPS requests (ab8a428)
• TraceSpan option onCloseByParent (f34b5d8)

Bug Fixes Copy Section

• Fix wrapping of nested ESM handlers (03e7c18)

Maintenance Improvements Copy Section

• Rely on tags.setMany to set initial tags set (dd8522a)

[0.3.0](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-09-08) Copy Chapter

⚠ BREAKING CHANGES Copy Section

• @serverless/sdk-schema was upgraded to v0.5.0, which changed structure of API Gateway event related tags

Features Copy Section

• Setupaws.lambda.event_type and aws.lambda.event_source tags (c21622d)
• Setup aws.lambda.http.status_code tag (f60ec61)
• Write generic aws.lambda.http tags in case of API Gateway events (3231a6c)

[0.2.1](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-09-06) Copy Section

Features Copy Section

• Instrument API Gateway v2 HTTP API (v1 payload) events (82fefe2)
• Instrument API Gateway v2 HTTP API (v2 payload) events (f09907e)
• Instrument SNS events (a228bb7)
• Instrument SQS events (cea70d6)
• Support arrays as tag values (def9dfc)

[0.2.0](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-09-01) Copy Chapter

⚠ BREAKING CHANGES Copy Section

• Telemetry payload prefix is changed from ⚡ to SERVERLESS_TELEMETRY

Features Copy Section

• Instrument API Gateway REST API events (233880f)
• Introduce traceSpan.tags.setMany method (ab730db)

Maintenance Improvements Copy Section

• Change telemetry log prefix to SERVERLESS_TELEMETRY (52fd7df)
• Improve tags reset handling (6bda7f9)
• Remove ineffective code (87307e8)

0.1.0 (2022-08-29) Copy Section

Features Copy Section

Initial implementation

File: node/packages/aws-lambda-sdk/package.json Copy Chapter

{
"name": "@serverless/aws-lambda-sdk",
"repository": "serverless/console",
"version": "0.15.15",
"author": "Serverless, Inc.",
"dependencies": {
"@serverless/sdk": "^0.5.26",
"@serverless/sdk-schema": "^0.15.6",
"d": "^1.0.1",
"ext": "^1.7.0",
"long": "^5.2.3",
"type": "^2.7.2"
},
"typesVersions": {
"": {
"": [
".ts-types/"
]
}
},
"standard-version": {
"tagPrefix": "@serverless/aws-lambda-sdk@",
"path": ".",
"skip": {
"commit": true,
"tag": true
},
"types": [
{
"type": "feat",
"section": "Features"
},
{
"type": "fix",
"section": "Bug Fixes"
},
{
"type": "perf",
"section": "Performance Improvements"
},
{
"type": "refactor",
"section": "Maintenance Improvements"
}
]
},
"scripts": {
"build": "./scripts/build.js dist/extension.internal.zip",
"prepare-release": "standard-version && prettier --write CHANGELOG.md",
"test": "mocha "test/unit/**/.test.js"",
"test:isolated": "mocha-isolated "test/unit//*.test.js"",
"test:integration": "mocha "test/integration//*.test.js"",
"test:performance": "mocha test/benchmark/performance.test.js"
},
"publishConfig": {
"access": "public"
},
"license": "MIT"
}

File: node/packages/aws-lambda-sdk/docs/sdk-trace.md Copy Chapter

AWS Lambda SDK Trace

For each function invocation single AWS Lambda SDK Trace is generated.

Before returning the result to AWS Lambda trace payload is written to the console with following log line:

SERVERLESS_TELEMETRY.T.<base64 encoded payload>

Trace tags Copy Chapter

Tags exposed on top trace

Trace spans Copy Chapter

SDK automatically creates following spans, all spans expose TraceSpan interface

`aws.lambda` Copy Section

Root span for each function invocation. In case of first invocation it contains two sub spans aws.lambda.initializaton and aws.lambda.invocation. For following invocations there's just aws.lambda.invocation sub span

Parent: None

Tags

Always present

Error case

Tags set in case of 'error:handled' outcome

HTTP Endpoint

Tags collected if event is sourced by either:

• AWS API Gateway v1 REST API endpoint configured with AWS_PROXY integration type.
• AWS API Gateway v2 HTTP API endpoint configured with either v1 or v2 version of a payload
• AWS Function URL

AWS API Gateway

Tags collected if event is sourced by either:

• AWS API Gateway v1 REST API endpoint configured with AWS_PROXY integration type.
• AWS API Gateway v2 HTTP API endpoint configured with either v1 or v2 version of a payload

Function URL

Tags collected if event is sourced by Function URL

SQS queue message

Tags collected if event is sourced by SQS queue

SNS topic message

Tags collected if event is sourced by SNS topic subscription

`aws.lambda.initialization` Copy Section

Covers function initialization phase.

Can be always accessed at serverlessSdk.traceSpans.awsLambdaInitialization

Parent: aws.lambda

Tags

None

`aws.lambda.invocation` Copy Section

Covers function invocation phase.

Current invocation span can always be accessed at serverlessSdk.traceSpans.awsLambdaInvocation

Parent: aws.lambda

Tags

None

File: node/packages/aws-lambda-sdk/docs/sdk.md Copy Chapter

Serverless SDK

Properties and methods of the `serverlessSdk` Copy Chapter

Common properties for SDK are documented at SDK API

This document describes properties specific to AWS Lambda SDK

`.traceSpans` Copy Section

For detailed info on spans check sdk-trace.md

• root (also aliased as awsLambda) - Root AWS lambda span
• awsLambdaInitialization - Initialization span
• awsLambdaInvocation - Invocation span (not available at initialization phase)

`serverlessSdk.instrumentation` Copy Section

Most of the instrumentation is setup automatically, still there are scenarios when it's difficult to ensure that (e.g. when target modules are imported as ESM, or come from bundles). In such case instrumentation need to be set manually, and then following utilities should be used:

• awsSdkV2.install(AWS) - Instrument AWS SDK v2 (takes instance of SDK as the argument). See instrumentation/aws-sdk
• awsSdkV3Client.install(client) - Instrument AWS SDK v3 client. See instrumentation/aws-sdk
• expressApp.install(express) - Instrument Express. See instrumentatiom/express-app

File: node/packages/aws-lambda-sdk/docs/instrumentation/aws-sdk.md Copy Chapter

AWS SDK instrumentation

Disable with SLS_DISABLE_AWS_SDK_MONITORING environment variable

All AWS SDK requests are traced.

Tracing is turned on automatically for AWS SDK clients that are normally loaded via Node.js require.

However if AWS SDK is bundled then instrumentation needs to be turned on manually with following steps:

import AWS from 'aws-sdk';

// Instrument AWS SDK v2:
serverlessSdk.instrumentation.awsSdkV2.install(AWS);

import { Lambda } from '@aws/client-lambda';
const lambda = new Lambda({ region: process.env.AWS_REGION });

// Instrument AWS SDK v3 Client
serverlessSdk.instrumentation.awsSdkV3Client.install(lambda);

Covered AWS SDK requests are reflected in aws.sdk.<service-name> spans

Base span tags Copy Chapter

Tags that apply to all AWS SDK requests:

`aws.sdk.sns` span tags Copy Chapter

Tags that apply to requests that go to SNS service

`aws.sdk.sqs` span tags Copy Chapter

Tags that apply to requests that go to SQS service

`aws.sdk.dynamodb` span tags Copy Chapter

Tags that apply to requests that go to DynamoDb service

Request and response data Copy Chapter

In developer mode, additionally request and response bodies are monitored. That can be disabled with SLS_DISABLE_REQUEST_RESPONSE_MONITORING environment variable

File: node/packages/aws-lambda-sdk/instrument/README.md Copy Chapter

No local modules aside of main serverlessSdk object should be required in context of this directory

When relying on serverlessSdk, require it from lib/sdk

File: node/packages/aws-lambda-sdk/test/README.md Copy Chapter

Tests

Unit tests Copy Chapter

Unit tests are configured to be independent of any external infrastructure (AWS Lambda environment is emulated), and can be run offline

npm test

Integration tests Copy Chapter

AWS account is needed to run integration tests, and AWS credentials need to be configured.

In tests, the home folder is mocked, therefore AWS access cannot be reliably set up via the AWS_PROFILE variable or any other means that rely on configuration placed in the home folder.

Easiest is to run tests is by setting AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_REGION environment variables.

Tests create a temporary layer and Lambda resources and remove them after the test is finalized.

All created resourced are named or prefixed with test-sdk-<testUid> string, where testUid is four characters taken from local machine id or in case of CI runs a random string. testUid string can also be overridden via environment variable TEST_UID

npm run test:integration

Environment variables Copy Chapter

How extensions behave, for various testing purposes, can be tweaked with following environment variables:

Variables handled in extension logic Copy Section

• SERVERLESS_PLATFORM_STAGE - Ingestion server stage to which reports should be propagated (default is prod, with this setting it can be overridden to dev)
• SLS_SDK_DEBUG - Log debug messages, of which scope is to:
  • Mark certain processing points

Variables handled by test suite Copy Section

• TEST_INTERNAL_LAYER_FILENAME - Path to .zip file of a layer which contains just internal Node.js extension. Triggers mode in which two layers are attached to the lambda (one with external and other with internal extension)

File: node/packages/aws-lambda-sdk/test/benchmark/README.md Copy Chapter

Benchmarks

Tested use cases Copy Chapter

Node.js function ([`callback`](../../fixtures/lambdas/callback.js)) Copy Section

No-op Node.js function. Handler takes callback and immediately invokes it with dummy payload

Node.js 250ms function ([`250ms`](../../fixtures/lambdas/250ms.js)) Copy Section

No-op Node.js function. Handler takes callback waits 250ms and invokes it with dummy payload.
In this case produced extension invocation overheads are slightly smaller as some of the extension work is done during lambda operation

Node.js requiring function ([`requires`](../../fixtures/lambdas/requires.js)) Copy Section

Node.js function that requires a lot of modules

Benchmark variants Copy Chapter

`bare` Copy Section

No instrumentation (bare run with no extension layers onboard).

As there are no extensions loaded, there's no extension duration overhead introduced, and benchmark will naturally report them with zeros.

What we get is metrics from AWS report, that confirm on initialization duration, invocation duration, billed invocation duration and max memory used.

`internal` Copy Section

Internal extension which calculates and logs generated traces payload to the console

Reported metrics Copy Chapter

Each benchmark variant is run against 5 lambda instances.

Therefore for each metric outlined below, we get 5 numbers. Durations returned in result report are averages of those 5 values.

Internally measured durations are written by the extensions to the stdout, and are read (together with invocation reports as written by AWS) from CloudWatch logs.

Observed AWS Lambda execution lifecycle phases Copy Section

Initialization (`init`)

Lambda instance initialization

Observed metrics

`init:internal`

Duration of the internal extension initialization logic, measured internally in internal extension. It's a time measured from start of the internal extension logic, until it returns for further evaluation by AWS runtime engine.

`init:total`

Total initialization time as reported by AWS (with initDuration metric provided in report of the first invocation)

Invocation

Benchmarks observe first invocation (first) (one that in regular circumstances immediately follows initialization), and the the second (following).

Two first invocations are observed separately, as data shows that durations of first invocation are always worse than of the second, and that for the following (third, fourth etc.) invocations numbers are similar as for the second.
This difference could be attributed to how Node.js internal optimization works, where paths which were already taken usually run faster (it's to be confirmed whether we see similar differences with other runtimes).

Observed metrics

`[first|following]:internal:request`

Invocation request handing duration in context of the Node.js internal extension. It's a time that's measured from the moment when our handler wrapper received an invocation event from AWS until we invoke the original Lambda handler.

`[first|following]:internal:response`

Invocation response handling duration in the context of the Node.js internal extension. It's a time that's measured from the moment when original handler provided response until we pass it back to AWS.

`[first|following]:total`

Total duration time as reported by AWS (with duration metric provided in invocation report)

`[first|following]:billed`

Billed duration time as reported by AWS (with billedDuration metric provided in invocation report)

`[first|following]:local

Locally measured SDK invocation time. This value is largely influenced by the location from which we run benchmarks and quality of the internet connection.

For benchmarks run against us-east-1 region, shortest values we'll get e.g. in New York, but running benchmarks in San Francisco will already add extra latency, and numbers get additionally worse, when running benchmarks from farther locations

`[first|following]:maxMemoryUsed

Max memory used as reported by AWS (with maxMemoryUsed metric provided in invocation report). It's to expose what memory overhead is introduced by the extensions

Setup & Run Copy Chapter

1. Ensure AWS credentials Copy Section

In same manner as for AWS CLI

2. Configure environment variables Copy Section

• AWS_REGION - region against which benchmarks should be run
• SLS_ORG_ID- Console organization id (can by dummy, as it'll be part of generated trace which otherwise is not send to console servers)
• TEST_UID - (optional) common name token to be used as part of generated resource names. All generated resource names will be prefixed with test-oext-<test-uid>. If not provided, one is generated on basis of local machine id. Note: Script ensures that all generated resources are removed after benchmark is done
• LOG_LEVEL - (optional) For more verbose output LOG_LEVEL=info can be used

4. Run Copy Section

Benchmark for all configured use cases and benchmark variants can be run as:

./test/scripts/benchmark.js

Generated benchmark results are output to the console in CSV format. To store them to the file output can be piped as:

./test/scripts/benchmark.js > benchmark.csv

4.1 Run customization Copy Section

Benchmark run can additionally be customized with following CLI params

• --use-cases Comma separated list of function use cases to test (e.g. callback,require)
• --benchmark-variants Comma separated list of benchmark variants to test (e.g. internal)
• --memory-size Memory size to provide to lambdas (by default it's 128MB).

File: node/packages/aws-lambda-sdk/test/fixtures/lambdas/package.json Copy Chapter

{
"dependencies": {
"@aws-lambda-powertools/logger": "^1.10.0",
"@aws-sdk/client-dynamodb": "^3.358.0",
"@aws-sdk/client-lambda": "^3.358.0",
"@aws-sdk/client-s3": "^3.358.0",
"@aws-sdk/client-sns": "^3.358.0",
"@aws-sdk/client-sqs": "^3.358.0",
"@aws-sdk/client-ssm": "^3.358.0",
"@aws-sdk/client-sts": "^3.358.0",
"@aws-sdk/lib-dynamodb": "^3.358.0",
"@aws-sdk/s3-request-presigner": "^3.358.0",
"aws-sdk": "2.1313.0",
"bunyan": "^1.8.15",
"express": "^4.18.2",
"ext": "^1.7.0",
"pino": "^8.14.1",
"serverless-http": "^3.2.0",
"winston": "^3.9.0"
}
}

File: node/packages/aws-lambda-sdk/test/fixtures/lambdas/error-async-initialization/package.json Copy Chapter

{
"type": "module"
}

File: node/packages/aws-lambda-sdk/test/fixtures/lambdas/esm-aws-sdk-v2/package.json Copy Chapter

{
"type": "module"
}

File: node/packages/aws-lambda-sdk/test/fixtures/lambdas/esm-aws-sdk-v3/package.json Copy Chapter

{
"type": "module"
}

File: node/packages/aws-lambda-sdk/test/fixtures/lambdas/esm-callback/package.json Copy Chapter

{
"type": "module"
}

File: node/packages/aws-lambda-sdk/test/fixtures/lambdas/esm-express/package.json Copy Chapter

{
"type": "module"
}

File: node/packages/aws-lambda-sdk/test/fixtures/lambdas/esm-http/package.json Copy Chapter

{
"type": "module"
}

File: node/packages/aws-lambda-sdk/test/fixtures/lambdas/esm-nested/package.json Copy Chapter

{
"type": "module"
}

File: node/packages/aws-lambda-sdk/test/fixtures/lambdas/esm-sdk/package.json Copy Chapter

{
"type": "module"
}

File: node/packages/aws-lambda-sdk/test/fixtures/lambdas/esm-thenable/package.json Copy Chapter

{
"type": "module"
}

File: node/packages/sdk/README.md Copy Chapter

@serverless/sdk

[Serverless Console](https://www.serverless.com/console) SDK Copy Chapter

Use case Copy Section

Environment agnostic Serverless Console instrumentation functions for Node.js applications.

This library is safe to use without side-effects in any Node.js applications. It becomes effective once (one of the listed below) environment specific SDK is loaded on top.

Environment extensions

• AWS Lambda - @serverless/aws-lambda-sdk

Installation Copy Section

npm install @serverless/sdk

Usage Copy Section

CJS:

const serverlessSdk = require('@serverless/sdk');

// ...
serverlessSdk.captureError(new Error('Unexpected'));

ESM:

import serverlessSdk from '@serverless/sdk';

// ...
serverlessSdk.captureError(new Error('Unexpected'));

Setup Copy Section

1. Register with [Serverless Console](https://console.serverless.com/)

2. Initialize and setup SDK specific to your enviroment

See Environment extensions

2.1 Configuration options

Common options supported by all environments:

`SLS_ORG_ID` (or `options.orgId`)

Required setting. Id of your organization in Serverless Console.

`SLS_DISABLE_HTTP_MONITORING` (or `options.disableHttpMonitoring`)

Disable tracing of HTTP and HTTPS requests. See HTTP instrumentation

`SLS_DISABLE_REQUEST_RESPONSE_MONITORING` (or `options.disableRequestResponseMonitoring`)

(Dev mode only) Disable monitoring requests and reponses (function, AWS SDK requests and HTTP(S) requests)

`SLS_DISABLE_EXPRESS_MONITORING` (or `options.disableExpressMonitoring`)

Disable automated express monitoring. See express app instrumentation

`SLS_DISABLE_CAPTURED_EVENTS_STDOUT` (or `options.disableCapturedEventsStdout`)

Disable writing captured events registered via .captureError and .captureWarning to stdout

Instrumentation Copy Section

This package comes with instrumentation for following areas.

Note: instrumentation is enabled via environment specific SDK instance, relying just on @serverless/sdk doesn't enable any instrumentation)

• HTTP(s) requests
• express app
• Node.js console

API Copy Section

• serverlessSdk

File: node/packages/sdk/CHANGELOG.md Copy Chapter

Changelog

All notable changes to this project will be documented in this file. See standard-version for commit guidelines.

[0.5.26](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-09-27) Copy Section

Bug Fixes Copy Section

• Report SDK user error for invalid span name (#879) (73b091d)

[0.5.25](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-08-16) Copy Section

Bug Fixes Copy Section

• Handle async closures in createSpan correctly (8c9e03f)

[0.5.24](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-08-09) Copy Section

Bug Fixes Copy Section

• Use createSpan instead of createTraceSpan (a1d3e19)

[0.5.23](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-08-02) Copy Section

Bug Fixes Copy Section

• Use Multiple Types for different createTraceSpan calls (7a07b72)

[0.5.22](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-08-02) Copy Section

Features Copy Section

• Add support for custom spans (c43f756)

Bug Fixes Copy Section

• Seperate createTraceSpan tests into its own block (f6d85b0)

[0.5.21](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-08-01) Copy Section

Features Copy Section

• Add setEndpoint to SDK (e67efc6)

[0.5.20](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-06-07) Copy Section

Features Copy Section

• Enforce limits on tag values (8985b99)
• Enforce max length on tag name (38a771b)

[0.5.19](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-05-18) Copy Section

Bug Fixes Copy Section

• Fix error data resolution from AWS Powertools error log (fcb6fe7)
• Ensure to expose our crashes that console will swallow (81f680e)

[0.5.18](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-05-17) Copy Section

Features Copy Section

• Enable filters configuration for HTTP requests (554e358)

[0.5.17](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-05-10) Copy Section

Bug Fixes Copy Section

• Fix detection of not observed response body (f7eb441)

Maintenance Improvements Copy Section

• Support black boxing internal spans (4ae3a31)
• Do not create HTTP trace spans in black box context (12ef23b)
• Remove no longer needed debug logs (978deb8)

[0.5.16](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-05-04) Copy Section

Bug Fixes Copy Section

• Ensure to resolve stack trace only for exposed logs (c71982e)

[0.5.15](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-04-28) Copy Section

Bug Fixes Copy Section

• Resolve parametrized paths with nested routers (1f30b8e)

[0.5.14](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-04-27) Copy Section

Bug Fixes Copy Section

• Fix resolution of parametrized route paths (7bdc66f)

[0.5.13](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-04-27) Copy Section

Bug Fixes Copy Section

• Fix log levels parsing in structured logs instrumentation (#694) (21f0929)

[0.5.12](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-04-26) Copy Section

Features Copy Section

• Full resolution of paths that involve nested express routers (e3641aa)

[0.5.11](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-04-21) Copy Section

Bug Fixes Copy Section

• Ensure to report unexpected parsing issues (0864381)

Maintenance Improvements Copy Section

• Optimise JSON string detection (f38b906)
• Optimize error data detection (45c4a65)
• Remove obsolete debug log (3034aa7)

[0.5.10](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-04-20) Copy Section

Bug Fixes Copy Section

• Do not fail on missing layer.method (21aabd9)

Maintenance Improvements Copy Section

• Improve sdk._reportWarning resolution (65ad54b)

[0.5.9](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-04-20) Copy Section

Bug Fixes Copy Section

• Fix router middleware detection in Express instrumentation (f89cc69)

Maintenance Improvements Copy Section

• Fix information in inline comment (a7ea178)

[0.5.8](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-04-14) Copy Section

Bug Fixes Copy Section

• Updated warning type to user (#648) (6a2e446)

[0.5.7](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-04-13) Copy Section

Features Copy Section

• Capture Structured Logs as Errors & Warnings (#638) (4311ac1)

[0.5.6](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-04-12) Copy Section

Bug Fixes Copy Section

• SC-799 Added capture warning when spans are not closed (#631) (16f9a8b)

[0.5.5](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-04-06) Copy Section

Maintenance Improvements Copy Section

• Write JSON strings as structured logs (e5f5162)

[0.5.4](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-03-29) Copy Section

Bug Fixes Copy Section

• Fix resolution of url data from options.path in HTTP instrumentation (e5a4ccd)

[0.5.3](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-03-01) Copy Section

Maintenance Improvements Copy Section

• Ensure full stack traces in debug mode (cd87544)
• Minimize needed debug logs verbosity (2171f39)

[0.5.2](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-02-24) Copy Section

Bug Fixes Copy Section

• Respect native HTTP request error handling (bc1f263)

[0.5.1](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-02-10) Copy Section

Bug Fixes Copy Section

• Remove support for traceCaptureBodySizeKb setting (relying on it may introduce bugs) (8d5d410)

Maintenance Improvements Copy Section

• Internal _reportNotice interface (8aac3f2)
• Report with notice large HTTP bodies (e9b59ca)

[0.5.0](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-02-02) Copy Chapter

⚠ BREAKING CHANGES Copy Section

• All internal warnings need to be configured via serverlessSdk._reportWarning to be reflected as captured events
• serverless._reportSdkError is renamed to serverless._reportError

Features Copy Section

• Dedicated internal endpoint for reporting warnings (685cb2a)
• Support different SDK error types and reflect the type in structured log (d45cbfa)
• Write captured events reported with .capture* methods to stdout (4f940eb)

Bug Fixes Copy Section

• Ensure to always generate captured events for internal errors (dc1e70f)
• Ensure to always generate captured events for internal warnings (eef80e0)

Maintenance Improvements Copy Section

• Reflect internal error types in structured log (0f7f554)
• Rename ._reportSdkError to ._reportError (33327cb)

[0.4.4](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-02-01) Copy Section

Bug Fixes Copy Section

• Do not define undefined properties in structured error (37e2491)
• Ensure to unpack structured SDK errors for captured events (b0ecd2b)

Maintenance Improvements Copy Section

• Improve stack trace presentation in SDK error (40c3930)
• Report stack trace with simpler stack property (a6f4604)

[0.4.3](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-01-30) Copy Section

Features Copy Section

• Log instead of throw on invalid internal tag settings (8b4c595)
• Prevent lambda crashes on internal SDK errors (015c598)

Maintenance Improvements Copy Section

• Introduce ._reportSdkError for silent error reporting (f2a5c5d)
• Prevent HTTP releated debug log when instrumentation is off (1c6f201)
• Seclude resolveNonErrorName util (57e28f5)

[0.4.2](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-01-27) Copy Section

Bug Fixes Copy Section

• Fix manual express instrumentation (0fefb5a)

[0.4.1](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-01-26) Copy Section

Features Copy Section

• Cover each console.error invocation with captured event (c37ef74)
• Store stack trace with each captured error and warning (eadaafa)

[0.4.0](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-01-19) Copy Chapter

⚠ BREAKING CHANGES Copy Section

• Root (global) tags are no longer stored on the root span. Instead they're stored on SDK directly and are expected to be considered as trace-wide tags

Bug Fixes Copy Section

• Ensure not to crash on invalid serverless.setTag input (c5f28ff)
• Fix expressApp instrumentation endpoint (11314b4)
• Warn instead of throw when SDK is used without initialization (fe64a4f)

Maintenance Improvements Copy Section

• Enable customization of event data via private options (a5e8f36)
• Store global tags on SDK directly (not on root span) (9a72787)

[0.3.1](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-01-13) Copy Section

Features Copy Section

• serverlessSdk.setTag (c546bcd)
• Automatically resolve .traceSpans.root (99eb5e2)

[0.3.0](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-01-12) Copy Chapter

⚠ BREAKING CHANGES Copy Section

• sdk.createTraceSpan is removed. The functionality of creating custom spans is not considered part of public API at the time being (a new method for that will be introduced in one of the following releases)

Features Copy Section

• Make createTraceSpan private (017ef10)
• Dedicated handling for structured warnings issued by the SDK (1d38f5f)
• Relax tag name format restriction (414108f)
• Log error instead of throwing on invalid capturedEvent user input (b958948)

Maintenance Improvements Copy Section

• Fixed typings file (#369) (2deeb4b)
• Revert problematic TS addition (ad88aab)

[0.2.4](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-01-11) Copy Section

Features Copy Section

• Support custom fingerprints (b29b1e5)

[0.2.3](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-01-09) Copy Section

Bug Fixes Copy Section

• Adjusted typescript implementation for sdk (#360) (e8a7066)

[0.2.2](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-01-09) Copy Section

Bug Fixes Copy Section

• Ensure _origin on created events before they're emited (#353) (9c6bef2)

[0.2.1](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-01-05) Copy Section

Features Copy Section

• serverless.captureWarning utility (f559a2e)
• Instrument console.error (0647848)
• Instrument console.warn (9088bbe)

Maintenance Improvements Copy Section

• Differentiate events sourced from console.* calls (bea40aa)
• Fix location of createErrorCapturedEvent module (07210b1)
• Simplify console.error args handling (8d3d254)

[0.2.0](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-12-22) Copy Chapter

⚠ BREAKING CHANGES Copy Section

• Remove resolution of aws.lambda.outcome tag enum. This needs to be done in the context of aws-lambda-sdk
• Trace span event emitter is generalized (to be not only Trace span specific) and relocated, it is accessible now at _eventsEmitter instead of _traceSpanEmitter property on SDK
• Trace span events are renamed from open to trace-span-open and close to trace-span-close

Features Copy Section

• serverless.captureError with internal CapturedEvent interface (b808b8a)
• Remove AWS specific logic (2ab35d0)

Maintenance Improvements Copy Section

• Exclude resolveEpochTimestampString (284908c)
• Exclude Tags interface from TraceSpan context (1cafe8b)
• Exclude toLong utility (8571198)
• Fix typo in internal function name (a1bd97c)
• Generalize ensureXName logic (e93607b)
• Generalize internal event emitter (80c5961)
• Implement tags.toJSON() (7d9fc1f)
• Remove dead code (14f3613)
• Seclude generateId utility (e8842c7)
• Seclude toProtobufEpochTimestamp (e886a5e)
• Seclude toProtobuTags utility (47f2598)
• Simplify traceSpan.startTime validation (60d62f6)

0.1.0 (2022-12-15) Copy Section

Features Copy Section

• Initial version (taken out from @serverless/aws-lambda-sdk) (4a41a0a)

File: node/packages/sdk/package.json Copy Chapter

{
"name": "@serverless/sdk",
"repository": "serverless/console",
"version": "0.5.26",
"author": "Serverless, Inc.",
"dependencies": {
"d": "^1.0.1",
"ext": "^1.7.0",
"long": "^5.2.3",
"type": "^2.7.2",
"uni-global": "^1.0.0"
},
"typesVersions": {
"": {
"": [
".ts-types/"
]
}
},
"standard-version": {
"tagPrefix": "@serverless/sdk@",
"path": ".",
"skip": {
"commit": true,
"tag": true
},
"types": [
{
"type": "feat",
"section": "Features"
},
{
"type": "fix",
"section": "Bug Fixes"
},
{
"type": "perf",
"section": "Performance Improvements"
},
{
"type": "refactor",
"section": "Maintenance Improvements"
}
]
},
"scripts": {
"prepare-release": "standard-version && prettier --write CHANGELOG.md",
"test": "mocha "test/unit/**/.test.js"",
"test:isolated": "mocha-isolated "test/unit/**/*.test.js""
},
"publishConfig": {
"access": "public"
},
"license": "MIT"
}

File: node/packages/sdk/docs/sdk.md Copy Chapter

Serverless SDK

Properties and methods of the `serverlessSdk` Copy Chapter

`.name` Copy Section

Name of the used SDK package. By default @serverless/sdk, but if environment extension is used, it's overriden (to e.g. @serverless/aws-lambda-sdk)

`.version` Copy Section

Package version

`.orgId` Copy Section

Authenticated Serverless Console organization id

`.traceSpans` Copy Section

Dictionary of common spans created in context of given environment

`.instrumentation` Copy Section

Most of the instrumentation is setup automatically, still there are scenarios when it's difficult to ensure that (e.g. when target modules are bundled). In such case instrumentation need to be set manually. In context of @serverless/sdk following instrumentation extensions are provided:

• .instrumentation.expressApp.install(express) - Instrument Express. See instrumentatiom/express-app

`.captureError(error[, options])` Copy Section

Record captured error. Captured error is sent to Serverless Console backend and printed to the stdout in structured format (writing to stdout can be disabled with SLS_DISABLE_CAPTURED_EVENTS_STDOUT env var)

• error - Captured error
• options:
  • tags (object) - User tags object. Tag names can contain alphanumeric (both lower and upper case), -, _ and . characters. Values can be string, boolean, number, Date or Array containing any values of prior listed types
  • fingerprint (string) - Console UI groups common errors by the fingerprint, which by default is derived from the error stack trace. This can be overriden by passing custom fingerprint value

`.captureWarning(message[, options])` Copy Section

Record warning. Captured warning is sent to Serverless Console backend and printed to the stdout in structured format (writing to stdout can be disabled with SLS_DISABLE_CAPTURED_EVENTS_STDOUT env var)

• message - Warning message
• options:
  • tags (object) - User tags object. Tag names can contain alphanumeric (both lower and upper case), -, _ and . characters. Values can be string, boolean, number, Date or Array containing any values of prior listed types
  • fingerprint (string) - Console UI groups common warnings by the fingerprint, which by default is derived from its message. This can be overriden by passing custom fingerprint value

`.setTag(name, value)` Copy Section

Set custom (user defined) trace tag

• name (string) - Tag name, can contain alphanumeric (both lower and upper case), -, _ and . characters
• value (any) - Tag value. Can be string, boolean, number, Date or Array containing any values of prior listed types

File: node/packages/sdk/docs/trace-span.md Copy Chapter

TraceSpan

Properties Copy Chapter

`name` _(string)_ Copy Section

Span name

`traceId` _(string)_ Copy Section

Id of a trace (same for all spans in a trace)

`spanId` _(string)_ Copy Section

Id of a span, unique for each span

`startTime` _(bigInt)_ Copy Section

High-resolution nanoseconds timestamp, result of process.hrtime.bigint() (not an epoch timestamp)

`endTime` _(bigInt)_ Copy Section

High-resolution Nanoseconds timestamp, result of process.hrtime.bigint() (not an epoch timestamp)

`parentSpan` _(TraceSpan)_ Copy Section

Parent TraceSpan (null in case of a root span)

`subSpans` _(Set(...TraceSpan))_ Copy Section

Set of all direct sub spans

`spans` _(Set(...TraceSpan))_ Copy Section

Set of all descendant spans (dynamically resolved)

`tags` _(Map)_ Copy Section

Map of internal tags set on a span.

`input` _(string)_ Copy Section

Eventual span input body

`output` _(string)_ Copy Section

Eventual span output body

Methods Copy Chapter

`toJSON()`

Returns JSON representation of the span

File: node/packages/sdk/docs/instrumentation/express-app.md Copy Chapter

[`express`](https://expressjs.com/) app instrumentation

Disable with SLS_DISABLE_EXPRESS_MONITORING environment variable

If express framework (together with tools like serverless-http) is used to route incoming requests. Trace spans for it's middlewares are created

Tracing is turned on automatically, assuming that express is loaded normally via Node.js require. If it comes bundled then instrumentation needs to be turned on manually with following steps:

import express from 'express';

const app = express();

serverlessSdk.instrumentation.expressApp.install(app);

Handling of express route is covered in context of main express span. Additionally middleware jobs are recorded as following spans:

• express.middleware.<name>, generic middleware (setup via app.use)
• express.middlewa.route.<method>.<name> - route specific middleware (setup via app.get, app.post etc.)
• express.middleware.error.<name> - error handling middleware

Tags introduced on _root_ span

File: node/packages/sdk/docs/instrumentation/http.md Copy Chapter

HTTP(S) requests

Disable with SLS_DISABLE_HTTP_MONITORING environment variable

All HTTP and HTTPS requests are monitored and stored as node.http.request & node.https.request trace spans.

Trace span tags: Copy Chapter

Request and response data

In developer mode, additionally request and response bodies are monitored. That can be disabled with SLS_DISABLE_REQUEST_RESPONSE_MONITORING environment variable

File: node/packages/sdk/docs/instrumentation/node-console.md Copy Chapter

Node.js [`console`](https://nodejs.org/api/console.html) instrumentation

Disable with SLS_DISABLE_NODE_CONSOLE_MONITORING environment variable

All console.error invocations are monitored and propagated as captured errors to the Serverless Console

File: node/packages/sdk-schema/README.md Copy Chapter

Serverless SDK Schema

This is the auto generated NPM package from the Serverless Protobufs. Serverless uses Protobufs as the required format for all instrumentation libraries that communicate with the Serverless Platform.

File: node/packages/sdk-schema/CHANGELOG.md Copy Chapter

Changelog

All notable changes to this project will be documented in this file. See standard-version for commit guidelines.

[0.15.6](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-06-14) Copy Section

Features Copy Section

• TracePayload.is_truncated (a3df350)

[0.15.5](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-05-17) Copy Section

Features Copy Section

• Introduce aws.lambda.response_mode tag (e61819e)

[0.15.4](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-05-15) Copy Section

Features Copy Section

• Dev Mode transport payload upgrade (ec7551d)

[0.15.3](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-03-29) Copy Section

Features Copy Section

• AWS Lambda runtime related tags (f239b44)

[0.15.2](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-03-08) Copy Section

Features Copy Section

• Define is_sampled_out for TracePayload (20c1966)

[0.15.1](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-02-09) Copy Chapter

Features Copy Section

• Notice event tags (c6641be)

[0.15.0](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-02-02) Copy Chapter

⚠ BREAKING CHANGES Copy Section

• Captured event WarningType.WARNING_TYPE_SDK reference is renamed to WarningType.WARNING_TYPE_SDK_USER
• Captured event ErrorType.ERROR_TYPE_CAUGHT reference is renamed to ErrorType.ERROR_TYPE_CAUGHT_USER

Features Copy Section

• Distinguish between user or internal SDK generated warning (27f28f2)
• Distinguish user and sdk caught errors (177516b)

[0.14.5](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-01-24) Copy Chapter

Features Copy Section

• Define WarningTags.stacktrace (b04ae2c)

[0.14.4](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-01-18) Copy Section

Features Copy Section

• Define TracePayload.custom_tags (21056f6)

[0.14.3](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-01-13) Copy Chapter

Features Copy Section

• Define Span.custom_tags for custom user tags (38338ee)

[0.14.2](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2023-01-11) Copy Chapter

Features Copy Section

• WarningTags.type (0cbd622)
• Define Event.custom_fingerprint (306362a)

[0.14.1](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-12-23) Copy Chapter

Features Copy Section

• Add Warning Tags to Event Schema (#333) (94c9c5f)

[0.14.0](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-12-07) Copy Section

⚠ BREAKING CHANGES Copy Section

• tracePayload: events is added as a repeated field

Features Copy Section

• Add Events as a property of TracePayload (aced7ec)

[0.13.2](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-12-02) Copy Section

Features Copy Section

• Added Event and EventPayload schemas

[0.13.1](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-11-24) Copy Chapter

Features Copy Section

• Make aws.sdk.signature_version tag optional (cd566b0)

[0.13.0](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-10-31) Copy Chapter

⚠ BREAKING CHANGES Copy Section

• requestResponse payload: data is removed in favor of body and origin

Features Copy Section

• requestResponse payload: Replace data with body and origin (c1c7b86)
• Support Node.js v12 (bb62fa1)

[0.12.1](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-10-24) Copy Section

Features Copy Section

• Added timestamp to req/res proto schema (ce13fd8)

[0.12.0](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-10-20) Copy Section

⚠ BREAKING CHANGES Copy Section

• Updated logs schema to support ingest process a bit better (f217ea2)

[0.11.0](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-10-20) Copy Chapter

⚠ BREAKING CHANGES Copy Section

• http.request_body, http.response_body, aws.sdk.request_body and aws.sdk.response_body tags are removed in favor of top level input and output` properties

Features Copy Section

• Move span input and output data to top level properties (277b6e9)

[0.10.1](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-10-04) Copy Chapter

Features Copy Section

• Configure optional request_body and response_body tags (ed44a1c)

[0.10.0](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-09-28) Copy Chapter

⚠ BREAKING CHANGES Copy Section

• express tags namespace is removed in favor of introduced aws.lambda.http_router

Features Copy Section

• Remove express tags in favor of aws.lambda.http_router (ff17ea9)

[0.9.0](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-09-26) Copy Chapter

⚠ BREAKING CHANGES Copy Section

• Remove aws.lambda.api_gateway.request.path_parameters in favor of aws.lambda.api_gateway.request.path_parameter_names
• Remove aws.lambda.api_gateway.request.headers in favor of http.request_header_names
• Remove http.query in favor of http.query_parameter_names
• Change numbering of some http.* fields

Features Copy Section

• Remove aws.lambda.api_gateway.request.path_parameters in favor of aws.lambda.api_gateway.request.path_parameter_names (44702ad)
• Remove aws.lambda.api_gateway.request.headers in favor of http.request_header_names (2a38ba4)
• Remove http.query in favor of http.query_parameter_names (ee0c8e5)
• Define exclusive_start_key and attribute_values DynamoDB tags (d15839d)

Maintenance Improvements Copy Section

• Pre-reserve slots for fields eventually to be introduced later (c693280)

[0.8.0](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-09-20) Copy Chapter

⚠ BREAKING CHANGES Copy Section

• Types of some numeric tags were updated to more optimal ones

Maintenance Improvements Copy Section

• Improve types of numeric properties (aa8dcc5)

[0.7.0](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-09-16) Copy Chapter

⚠ BREAKING CHANGES Copy Section

• Remove aws.sdk.account_id tag
• Rename aws.sdk.aws_service to aws.sdk.service
• Remove aws.sdk.dynamodb.table_names in favor of singular aws.sdk.dynamodb.table_name
• Rename aws.sdk.dynamodb.filter_expression to aws.sdk.dynamodb.filter (to match convention)
• aws.sdk.region and aws.sdk.request_id are made optional
• express.method and express.path are made optional

Features Copy Section

• Remove aws.sdk.account_id as it's not directly accessible (87af073)
• Make aws.sdk.region and aws.sdk.request_id optional (f6af48d)
• Remove obsolete aws_ prefix (1acc6cf)
• Rename aws.sdk.dynamodb.filter_expression to aws.sdk.dynamodb.filter (to match convention) (1cd3f32)
• Configure aws.sdk.dynamodb.key_condition to store KeyConditionExpression (11a98c9)
• Update to singular aws.sdk.dynamodb.table_name field (b87db6e)
• Make all express tags optional (96eae9f)

[0.6.0](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-09-14) Copy Chapter

⚠ BREAKING CHANGES Copy Section

• AWS SDK base tags are moved from service specific (aws.sdk.<service>) context to generic (aws.sdk)
• Removeoperation tags from aws.sdk.<service> context in favor of existing aws.sdk.operation tag
• Number ids of tag properties in AWS SDK context are changed

Features Copy Section

• Move base AWS SDK tags to aws.sdk namespace (4027b75)
• Remove duplicate operation tags (47fe2c6)
• Add aws.sdk.dynamodb.filter_expression tag (6bb5d3d)
• Cleanup numbering of tag properties (8b8b582)

[0.5.0](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-09-08) Copy Chapter

⚠ BREAKING CHANGES Copy Section

• Remove url related aws.lambda.api_gateway.request tags. Instead aws.lambda.http tags should be filled only
• Reordered tags in context HttpTags and added required host tag
• ExpressTags.status_code is converted to be optional
• HttpTags.status_code is converted to be optional

Features Copy Section

• Add RequestResponse Schema (#177) (9152c8a)
• Improve HTTP request tags (855070d)
• Make status_code optional in express tracking (e46b8d8)
• Make status_code optional in HTTP tracking (f862891)
• Remove url related aws.lambda.api_gateway.request tags (0861571)

[0.4.0](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-09-06) Copy Chapter

⚠ BREAKING CHANGES Copy Section

• aws.lambda.sqs.operation and aws.lambda.sns.operationare removed from schema (been added by mistake as they apply only to AWS SDK spans)

Bug Fixes Copy Section

• Remove tags which do not apply to aws.lambda span (705087b)

[0.3.0](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-08-31) Copy Chapter

⚠ BREAKING CHANGES Copy Section

• AwsApiGatewayRequestTags.string_parameters is renamed to AwsApiGatewayRequestTags.query_string_parameters

Bug Fixes

• Fix schema property name (6100b51)

[0.2.0](https://github.com/serverless/console/compare/@serverless/[email protected]...@serverless/[email protected]) (2022-08-29) Copy Chapter

⚠ BREAKING CHANGES Copy Section

• Top level tags are no longer expected to have underscores replaced with ".", and they were reorganized into nested structure- Some properties out of SlsTags and AwsLambdaTags where changed to be optional

Features Copy Section

• Mark as optional properties not provided by the extension (8ca71a6)
• Unify tags definiton rules (a55d091)

0.1.0 (2022-08-22) Copy Section

• Initial Release of Schema (bfb26db)

File: node/packages/sdk-schema/package.json Copy Chapter

{
"name": "@serverless/sdk-schema",
"repository": "serverless/console",
"version": "0.15.6",
"main": "dist/index.cjs.js",
"module": "dist/index.esm.js",
"types": "dist/index.d.ts",
"scripts": {
"test": "mocha "test/unit//*.test.js"",
"test:isolated": "mocha-isolated "test/unit//*.test.js"",
"build": "rimraf -rf ./dist && tsc --emitDeclarationOnly && rollup --config && rimraf -rf ./dist/dts",
"prepare-release": "standard-version && prettier --write CHANGELOG.md"
},
"author": "Serverless, Inc.",
"license": "MIT",
"dependencies": {
"long": "^5.2.3",
"protobufjs": "^7.2.3"
},
"standard-version": {
"tagPrefix": "@serverless/sdk-schema@",
"path": ".",
"skip": {
"commit": true,
"tag": true
},
"types": [
{
"type": "feat",
"section": "Features"
},
{
"type": "fix",
"section": "Bug Fixes"
},
{
"type": "perf",
"section": "Performance Improvements"
},
{
"type": "refactor",
"section": "Maintenance Improvements"
}
]
},
"publishConfig": {
"access": "public"
}
}

File: node/packages/sdk-schema/tsconfig.json Copy Chapter

{
"extends": "@tsconfig/node16/tsconfig.json",
"compilerOptions": {
"declaration": true,
"declarationDir": "./dist/dts",
"emitDecoratorMetadata": true,
"experimentalDecorators": true,
"outDir": "./dist",
"sourceMap": true
},
"include": ["out/**/*"],
"exclude": ["src/output", "dist"],
"ts-node": {
"files": true
}
}

File: node/packages/sdk-schema/tsconfig.rollup.json Copy Chapter

{
"extends": "@tsconfig/node16/tsconfig.json",
"compilerOptions": {
"declaration": false,
"emitDecoratorMetadata": true,
"experimentalDecorators": true,
"sourceMap": true,
"target": "es2019"
},
"include": ["out/**/*"],
"exclude": ["src/output", "dist"],
"ts-node": {
"files": true
}
}

File: node/test/benchmark/README.md Copy Chapter

Benchmarks

Tested use cases Copy Chapter

Node.js success function ([`node-success`](../../packages/aws-lambda-sdk/test/fixtures/lambdas/callback.js)) Copy Section

No-op Node.js success function. Handler takes callback and immediately invokes it with dummy payload

Python success function ([`python-success`](../../../python/packages/aws-lambda-sdk/tests/fixtures/lambdas/success.py)) Copy Section

No-op Python success function. Handler takes callback and immediately invokes it with dummy payload

Benchmark variants Copy Chapter

`bare` Copy Section

No instrumentation (bare run with no extension layers onboard).

`consoleProd` Copy Section

Serverless Console production Mode: Just internal extension which calculates and logs generated traces payload to the console

`external` Copy Section

Extenal extension which processes the invocation processing flow

`consoleOfflineDevMode` Copy Section

Instrumentation operating in dev mode, yet with dummy dev mode layer (written in Node.js), which just takes payloads from the extension but doesn't send them to the Serverless Console websocket

Reported metrics Copy Chapter

Each benchmark variant is run against 5 lambda instances.

Therefore for each metric outlined below, we get 5 numbers. Durations returned in result report are averages of those 5 values.

Internally measured durations are written by the extensions to the stdout, and are read (together with invocation reports as written by AWS) from CloudWatch logs.

Observed AWS Lambda execution lifecycle phases Copy Section

Initialization (`init`)

Lambda instance initialization

Observed metrics

`init:external:overhead`

Internally measured external extension initilizaton time, which attributes to additional intialization latency

`init:internal:overhead`

Internally measured internal extension initilizaton time, which attributes to additional intialization latency

`init:internal:total`

Duration of the internal extension initialization logic, measured internally in internal extension. It's a time measured from start of the internal extension logic, until it returns for further evaluation by AWS runtime engine.

`init:total`

Total initialization time as reported by AWS (with initDuration metric provided in report of the first invocation)

Invocation

Benchmarks observe first invocation (first) (one that in regular circumstances immediately follows initialization), and the the second (following).

Two first invocations are observed separately, as data shows that durations of first invocation are always worse than of the second, and that for the following (third, fourth etc.) invocations numbers are similar as for the second.
This difference could be attributed to how Node.js internal optimization works, where paths which were already taken usually run faster (it's to be confirmed whether we see similar differences with other runtimes).

Observed metrics

`[first|following]:internal:request-overhead`

Internally measured internal extension invocation handling overhead. Time between custom handler triggered by the AWS runtime and original handler triggered by the instrumentation logic

`[first|following]:internal:response-overhead`

Internally measured internal extension invocation handling overhead. Time between response being returned by the original handler and same response being returned to AWS runtime

`[first|following]:external:response-overhead`

Internally measured external extension invocation handling overhead. Time between receiving information of invocation being finalized and marking the extension ready to process next invocation

`[first|following]:internal:total`

Internally measured total invocation time

`[first|following]:total`

Total duration time as reported by AWS (with duration metric provided in invocation report)

`[first|following]:billed`

Billed duration time as reported by AWS (with billedDuration metric provided in invocation report)

`[first|following]:local`

Locally measured SDK invocation time. This value is largely influenced by the location from which we run benchmarks and quality of the internet connection.

For benchmarks run against us-east-1 region, shortest values we'll get e.g. in New York, but running benchmarks in San Francisco will already add extra latency, and numbers get additionally worse, when running benchmarks from farther locations

`[first|following]:maxMemoryUsed`

Max memory used as reported by AWS (with maxMemoryUsed metric provided in invocation report). It's to expose what memory overhead is introduced by the extensions

Setup & Run Copy Chapter

1. Ensure installed dependencies Copy Section

1.1 Node.js

Ensure dependencies are ensure in following folders (they can be installed via npm install commmand):

• node
• node/packages/aws-lambda-sdk
• node/packages/aws-lambda-sdk/test/fixtures/lambdas

1.2 Python

Ensure dependencies for the serverless-aws-lambda-sdk package being installed as:

python3 -m venv .venv
source .venv/bin/activate
rm -rf python/packages/aws-lambda-sdk/dist
python3 -m pip install serverless-aws-lambda-sdk --target=python/packages/aws-lambda-sdk/dist

1.3 Go

Ensure Go is installed in the environment

2. Setup environment variables Copy Section

2.1 Ensure AWS credentials

In same manner as for AWS CLI

2.2 Configure environment variables

• AWS_REGION - region against which benchmarks should be run
• SLS_ORG_ID- Console organization id (can by dummy, as it'll be part of generated trace which otherwise is not send to console servers)
• TEST_UID - (optional) common name token to be used as part of generated resource names. All generated resource names will be prefixed with test-oext-<test-uid>. If not provided, one is generated on basis of local machine id. Note: Script ensures that all generated resources are removed after benchmark is done
• LOG_LEVEL - (optional) For more verbose output LOG_LEVEL=info can be used

3. Run Copy Section

Benchmark for all configured use cases and benchmark variants can be run as:

./node/test/scripts/benchmark/index.js

Generated benchmark results are output to the console in CSV format. To store them to the file output can be piped as:

./node/test/scripts/benchmark/index.js > benchmark.csv

4.1 Run customization Copy Section

Benchmark run can additionally be customized with following CLI params

• --use-cases Comma separated list of function use cases to test (e.g. node-success,pythi)
• --benchmark-variants Comma separated list of benchmark variants to test (e.g. internal)
• --memory-size Memory size to provide to lambdas (by default it's 128MB).

File: node/test/go/dev-mode/README.md Copy Chapter

Dev Mode Integration Tests

AWS account is needed to run integration tests, and AWS credentials need to be configured.

In tests, the home folder is mocked, therefore AWS access cannot be reliably set up via the AWS_PROFILE variable or any other means that rely on configuration placed in the home folder.

Easiest is to run tests is by setting AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_REGION environment variables.

Tests create a temporary layer and Lambda resources and remove them after the test is finalized.

All created resourced are named or prefixed with test-dev-mode-<testUid> string, where testUid is four characters taken from local machine id or in case of CI runs a random string. testUid string can also be overridden via environment variable TEST_UID

There is a test command in the root node folder you use to run these tests. So if you are in this directory be sure to back out to the `node`` folder and run the following command.

npm run test:integration

Environment variables Copy Chapter

How extensions behave, for various testing purposes, can be tweaked with following environment variables:

Variables handled in extension logic Copy Section

• SLS_TEST_EXTENSION_LOG - Log forwarded logs to Cloudwatch
• SLS_ORG_ID - Fake org ID we want to include with our test payloads

Variables handled by test suite Copy Section

• TEST_EXTERNAL_LAYER_FILENAME - Path to .zip file of a layer which contains just external dev-mode extension.

File: node/test/go/dev-mode/test/fixtures/lambdas/package.json Copy Chapter

{}

File: node/test/python/aws-lambda-sdk/benchmark/README.md Copy Chapter

Benchmarks

Tested use cases Copy Chapter

Success function ([`success`](../../../../../python/packages/aws-lambda-sdk/tests/fixtures/lambdas/success.py)) Copy Section

No-op success function. Handler takes callback and immediately invokes it with dummy payload

Benchmark variants Copy Chapter

`bare` Copy Section

No instrumentation (bare run with no extension layers onboard).

As there are no extensions loaded, there's no extension duration overhead introduced, and benchmark will naturally report them with zeros.

What we get is metrics from AWS report, that confirm on initialization duration, invocation duration, billed invocation duration and max memory used.

`internal` Copy Section

Internal extension which calculates and logs generated traces payload to the console

Reported metrics Copy Chapter

Each benchmark variant is run against 5 lambda instances.

Therefore for each metric outlined below, we get 5 numbers. Durations returned in result report are averages of those 5 values.

Internally measured durations are written by the extensions to the stdout, and are read (together with invocation reports as written by AWS) from CloudWatch logs.

Observed AWS Lambda execution lifecycle phases Copy Section

Initialization (`init`)

Lambda instance initialization

Observed metrics

`init:internal`

Duration of the internal extension initialization logic, measured internally in internal extension. It's a time measured from start of the internal extension logic, until it returns for further evaluation by AWS runtime engine.

`init:total`

Total initialization time as reported by AWS (with initDuration metric provided in report of the first invocation)

Invocation

Benchmarks observe first invocation (first) (one that in regular circumstances immediately follows initialization), and the the second (following).

Two first invocations are observed separately, as data shows that durations of first invocation are always worse than of the second, and that for the following (third, fourth etc.) invocations numbers are similar as for the second.

Observed metrics

`[first|following]:internal:request`

Invocation request handing duration in context of the internal extension. It's a time that's measured from the moment when our handler wrapper received an invocation event from AWS until we invoke the original Lambda handler.

`[first|following]:internal:response`

Invocation response handling duration in the context of the internal extension. It's a time that's measured from the moment when original handler provided response until we pass it back to AWS.

`[first|following]:total`

Total duration time as reported by AWS (with duration metric provided in invocation report)

`[first|following]:billed`

Billed duration time as reported by AWS (with billedDuration metric provided in invocation report)

`[first|following]:local

Locally measured SDK invocation time. This value is largely influenced by the location from which we run benchmarks and quality of the internet connection.

For benchmarks run against us-east-1 region, shortest values we'll get e.g. in New York, but running benchmarks in San Francisco will already add extra latency, and numbers get additionally worse, when running benchmarks from farther locations

`[first|following]:maxMemoryUsed

Max memory used as reported by AWS (with maxMemoryUsed metric provided in invocation report). It's to expose what memory overhead is introduced by the extensions

Setup & Run Copy Chapter

1. Ensure AWS credentials Copy Section

In same manner as for AWS CLI

2. Configure environment variables Copy Section

• AWS_REGION - region against which benchmarks should be run
• SLS_ORG_ID- Console organization id (can by dummy, as it'll be part of generated trace which otherwise is not send to console servers)
• TEST_UID - (optional) common name token to be used as part of generated resource names. All generated resource names will be prefixed with test-oext-<test-uid>. If not provided, one is generated on basis of local machine id. Note: Script ensures that all generated resources are removed after benchmark is done
• LOG_LEVEL - (optional) For more verbose output LOG_LEVEL=info can be used

4. Run Copy Section

Benchmark for all configured use cases and benchmark variants can be run as:

../scripts/benchmark.js

Generated benchmark results are output to the console in CSV format. To store them to the file output can be piped as:

../scripts/benchmark.js > benchmark.csv

4.1 Run customization Copy Section

Benchmark run can additionally be customized with following CLI params

• --use-cases Comma separated list of function use cases to test (e.g. callback,require)
• --benchmark-variants Comma separated list of benchmark variants to test (e.g. internal)
• --memory-size Memory size to provide to lambdas (by default it's 128MB).

File: proto/README.md Copy Chapter

Serverless Console Schema

Building Node.js Library Copy Chapter

Prerequisites Copy Section

1. Install protoc. On Mac you can run brew install protobuf
2. Install buf. On Mac you can run brew install bufbuild/buf/buf

Generating Library Copy Section

1. From ./proto run buf build & buf generate
2. From ./node run npm install
3. From ./node/packages/sdk-schema run npm run build

You now have a built package that you can either link locally or publish.

Building Python Library Copy Chapter

Prerequisites Copy Section

1. Install protoc. On Mac you can run brew install protobuf
2. Install buf. On Mac you can run brew install bufbuild/buf/buf

Generating Library Copy Section

1. cd to the root directory of the repo
2. python3.9 -m venv .venv
3. source .venv/bin/activate
4. cd ./proto
5. buf build
6. buf generate --template=buf.gen.python.yaml
7. cd ../python/packages/sdk-schema
8. pip install . --target=./dist
9. python -m build --wheel --sdist .

You now have a built package that can be published. For more details, see sdk-schema/README.md.

File: proto/buf.gen.python.yaml Copy Chapter

version: v1
plugins:

• name: python
  strategy: all
  out: ../python/packages/sdk-schema/serverless_sdk_schema/schema

File: proto/buf.gen.yaml Copy Chapter

version: v1
plugins:

• name: protoc-gen-ts
  path: ../node/node_modules/ts-proto/protoc-gen-ts_proto
  strategy: all
  out: ../node/packages/sdk-schema/out
  opt:
  • forceLong=long
  • esModuleInterop=true
  • oneof=unions

File: proto/buf.yaml Copy Chapter

version: v1
name: buf.build/serverless/sdk-schema
breaking:
use:
- FILE
lint:
use:
- DEFAULT

File: proto/docs/schema.md Copy Chapter

Protocol Documentation

Table of Contents Copy Chapter

• serverless/instrumentation/tags/v1/aws.proto

  • AwsApiGatewayTags

  • AwsApiGatewayTags.AwsApiGatewayRequestTags

  • AwsLambdaInitializationTags

  • AwsLambdaInvocationTags

  • AwsLambdaRuntimeTags

  • AwsLambdaTags

  • AwsSdkDynamodbTags

  • AwsSdkSnsTags

  • AwsSdkSqsTags

  • AwsSdkTags

  • AwsSnsEventTags

  • AwsSqsEventTags

  • AwsTags

  • HttpRouterTags

  • AwsLambdaTags.Outcome

  • AwsLambdaTags.ResponseMode

• serverless/instrumentation/tags/v1/common.proto

  • HttpTags

• serverless/instrumentation/tags/v1/error.proto

  • ErrorTags

  • ErrorTags.ErrorType

• serverless/instrumentation/tags/v1/notice.proto

  • NoticeTags

  • NoticeTags.NoticeType

• serverless/instrumentation/tags/v1/tags.proto

  • DashboardTags
  • SdkTags
  • SlsTags
  • Tags

• serverless/instrumentation/tags/v1/warning.proto

  • WarningTags

  • WarningTags.WarningType

• serverless/instrumentation/v1/dev_mode.proto

  • DevModePayload
  • DevModeTransportPayload
  • LambdaTelemetry

• serverless/instrumentation/v1/event.proto

  • Event
  • EventPayload

• serverless/instrumentation/v1/log.proto

  • LogEvent
  • LogPayload

• serverless/instrumentation/v1/metric.proto

  • Metric
  • Metric.ValueAtQuantile
  • MetricPayload

• serverless/instrumentation/v1/request_response.proto

  • RequestResponse

  • RequestResponse.Origin

• serverless/instrumentation/v1/trace.proto

  • Span
  • TracePayload

• Scalar Value Types

Top

serverless/instrumentation/tags/v1/aws.proto Copy Chapter

AwsApiGatewayTags Copy Section

AwsApiGatewayTags.AwsApiGatewayRequestTags Copy Section

AwsLambdaInitializationTags Copy Section

AwsLambdaInvocationTags Copy Section

AwsLambdaRuntimeTags Copy Section

Describes the AWS Lambda runtime details

AwsLambdaTags Copy Section

AwsSdkDynamodbTags Copy Section

AwsSdkSnsTags Copy Section

AwsSdkSqsTags Copy Section

AwsSdkTags Copy Section

AwsSnsEventTags Copy Section

AwsSqsEventTags Copy Section

AwsTags Copy Section

HttpRouterTags Copy Section

Describe routing of incoming HTTP requests.
Reflects configuration of a router used to route the request
It can be Express.js, or API Gateway if Express.js is not detected to be used

AwsLambdaTags.Outcome Copy Section

A Lambda function invocation can have one of the following
outcomes upon completion.

AwsLambdaTags.ResponseMode Copy Section

Top

serverless/instrumentation/tags/v1/common.proto Copy Chapter

HttpTags Copy Section

Generic tagset intended to describe incoming or outgoing HTTP requests

Top

serverless/instrumentation/tags/v1/error.proto Copy Chapter

ErrorTags Copy Section

ErrorTags.ErrorType Copy Section

Top

serverless/instrumentation/tags/v1/notice.proto Copy Chapter

NoticeTags Copy Section

NoticeTags.NoticeType Copy Section

Top

serverless/instrumentation/tags/v1/tags.proto Copy Chapter

DashboardTags Copy Section

SdkTags Copy Section

SlsTags Copy Section

Tags Copy Section

@validation_root

Top

serverless/instrumentation/tags/v1/warning.proto Copy Chapter

WarningTags Copy Section

WarningTags.WarningType Copy Section

Top

serverless/instrumentation/v1/dev_mode.proto Copy Chapter

DevModePayload Copy Section

A DevMode Payload is a message that will contain reqRes data or span data
that is forwarded to ingest via the internal extension

DevModeTransportPayload Copy Section