Skip to content

Commit

Permalink
docs: Update docs to reflect Dashboard v2 changes (#12155)
Browse files Browse the repository at this point in the history 
* docs: Update content on new monitoring

* docs: Add section on orgs & members

* docs: Remove reference to concurrent builds

* docs: Replace "Enterprise" with "Dashboard"

* docs: Updates node.js SDK docs

* docs: Update menu and add upgrade guide

* docs: Adding docs on span() in node.js SDK

* docs: Add setEndpoint, tagging API and migration

* docs: Update Python SDK migration

* docs: Update Python SDK

* docs: Use env vars to dsiable auto spans

* docs: Remove refernece to span.* Event methods

* docs: Replace "end" with "close" methods

* docs: Updates config notes per new SDKs

* docs: Add note on wrapping

* docs: Add instrumentation steps

* docs: Update syntax for disabling monitoring

* docs: Update syntax on disabling dashboard monitoring

* docs: Running prettify
  • Loading branch information
@skierkowski
skierkowski committed Sep 15, 2023
1 parent 9b770a2 commit c66aad7
Show file tree
Hide file tree
Showing 10 changed files with 1,202 additions and 331 deletions.
42 changes: 21 additions & 21 deletions docs/guides/cicd/faq.md
View file
Expand Up @@ -15,46 +15,46 @@ layout: Doc

## Is there a free tier?

Yes, up to 1 concurrent build with the Free tier. No credit card required, just sign up.

## How much does it cost if I need more?

You get one free concurrent deployment with the Free tier. The Team tier includes 2 concurrent builds and you can buy
more for \$25/mo/concurrent build.
Yes. No credit card required, just sign up. Free tier only supports public
repos. Upgrade to a paid tier to use CI/CD with private repos.

## Do you support preview deployments from pull requests?

Yes! You can add preview deployments to your CI/CD Settings. This will automatically test and deploy your service from a
pull request. The results will be posted in the pull request status. You can also setup auto deletion of deployed
resources for preview deployments so that “sls remove” is automatically run when your feature branch is merged and
deleted.
Yes! You can add preview deployments to your CI/CD Settings. This will
automatically test and deploy your service from a pull request. The results will
be posted in the pull request status. You can also setup auto deletion of
deployed resources for preview deployments so that “sls remove” is automatically
run when your feature branch is merged and deleted.

## Can I deploy for multiple branches?

Yes! Add other branch deployments to configure from any branch to any stage. We see a lot of folks deploy to a staging
environment from the master branch, and to production from a production branch.
Yes! Add other branch deployments to configure from any branch to any stage. We
see a lot of folks deploy to a staging environment from the master branch, and
to production from a production branch.

## Can I use different AWS Accounts for each Stage?

Yes! You can use deployment profiles to add as many AWS Accounts as you would like, and map them to individual stages in
your application.
Yes! You can use deployment profiles to add as many AWS Accounts as you would
like, and map them to individual stages in your application.

## Is it just for Serverless Framework?

Yes! Serverless CI/CD is designed around the Serverless Framework to provide a seamless experience for developers.
Anything you can deploy with the Serverless Framework you can deploy with Serverless CI/CD. The Serverless Framework is
Yes! Serverless CI/CD is designed around the Serverless Framework to provide a
seamless experience for developers. Anything you can deploy with the Serverless
Framework you can deploy with Serverless CI/CD. The Serverless Framework is
extensible with Plugins , so it works with a broad range of services.

## Are all runtimes supported?

Only the most popular runtimes, Node and Python, are currently supported. These two runtimes account for about 90% of
all serverless services. Support for other runtimes is coming soon.
Only the most popular runtimes, Node and Python, are currently supported. These
two runtimes account for about 90% of all serverless services. Support for other
runtimes is coming soon.

## Does Serverless CI/CD support AWS, Azure and GCP?

Only AWS is supported at this time; however, support for other cloud service providers is coming.
Only AWS is supported at this time; however, support for other cloud service
providers is coming.

## Do I need to host, manage, or operate any agents?

Nope! Serverless CI/CD is a 100% SaaS and managed for you. If you prefer to self-host, that is available as an option
with the Enterprise tier.
Nope! Serverless CI/CD is a 100% SaaS and managed for you.
138 changes: 20 additions & 118 deletions docs/guides/monitoring/README.md
View file
Expand Up @@ -17,7 +17,7 @@ Serverless Monitoring help you monitor, develop and optimize your serverless app

## Installing

Monitoring is enabled by default when you deploy a Service using the Serverless Framework CLI.
Monitoring is enabled by default if `org` and `app` are defined in the `serverless.yml`, you just need to deploy your service once those lines are added.

## Configuration

Expand All @@ -31,20 +31,15 @@ Serverless Framework, when configured to connect to the dashboard, will automati

Serverless Framework will enable log collection by adding a CloudWatch Logs Subscription to send logs that match a particular pattern to our infrastructure for processing. This is used for generating metrics and alerts.

When deploying, Serverless Framework will also create an IAM role in your account that allows the Serverless Framework backend to call FilterLogEvents on the CloudWatch Log Groups that are created in the Service being deployed. This is used to display the CloudWatch logs error details views alongside the stack trace.

If you have an existing CloudWatch Logs Subscription on your Log Group, please see the section on [pull-based log ingestion](#pull-based-log-ingestion).
When deploying, Serverless Framework will also create an IAM role in your account that allows the Serverless Framework backend access the CloudWatch Log Groups that are created in the Service being deployed. This is used to display the CloudWatch logs error details views alongside the stack trace.

## Disabling log collection

If you wish to disable log collection, set the following option:

**serverless.yml**
If you wish to disable log collection, simply add this to `serverless.yml`.

```yaml
custom:
enterprise:
collectLambdaLogs: false
dashboard:
disableMonitoring: true
```

**AWS Spans**
Expand All @@ -57,9 +52,9 @@ If you wish to disable AWS Span collection, set fhe following option:
**serverless.yml**

```yaml
custom:
enterprise:
disableAwsSpans: true
provider:
environment:
SLS_DISABLE_AWS_SDK_MONITORING: true
```

**HTTP(s) Spans**
Expand All @@ -72,118 +67,25 @@ If you wish to disable Http Span collection, set fhe following option:
**serverless.yml**

```yaml
custom:
enterprise:
disableHttpSpans: true
```

## Advanced Configuration Options

### Uploading Source Map

The [New Error Alert](#new-error) and the [Error Metrics](#errors) can be used to view the stack trace for the occurrence of an error. Tools like Webpack and Typescript generate the packaged code and therefore may obfuscate the stack trace. The Serverless Framework Enterprise Plugin and SDK support sourcemaps to properly generate the stack trace.

To use a sourcemap, ensure that your packaging directory includes the compiled source, original source, and the source maps.

For example, if your directory structure is:

```
$ ls -l dist/* src/*
-rw-r--r-- 1 dschep staff 576B Mar 21 17:21 dist/handler.js
-rw-r--r-- 1 dschep staff 911B Mar 21 17:21 dist/handler.js.map
-rw-r--r-- 1 dschep staff 451B Mar 22 12:13 src/handler.js
```

Then you should have a packaging directory that includes all the files above:

```yaml
package:
patterns:
- src/*.js
- dist/*.js
- dist/*.js.map
```

### Capturing non-fatal errors

Your lambda function may throw an exception, but your function handles it in order to respond to the requestor without throwing the error. One very common example is functions tied to HTTP endpoints. Those usually should still return JSON, even if there is an error since the API Gateway integration will fail rather than returning a meaningful error.

For this case, we provide a `captureError` function available on either the `context` or on the module imported from `'./serverless_sdk'` in NodeJS or `serverless_sdk` in Python. This will cause the invocation to still display as an
error in the serverless dashboard while allowing you to return an error to the user.

Here is an example of how to use it from the `context` object:

```javascript
module.exports.hello = async (event, context) => {
try {
// do some real stuff but it throws an error, oh no!
throw new Error('aa');
} catch (error) {
context.captureError(error);
}
return {
statusCode: 500,
body: JSON.stringify({ name: 'bob' }),
};
};
provider:
environment:
SLS_DISABLE_HTTP_MONITORING: true
```

[Full NodeJS Documentation](../sdk/nodejs.md#captureerror)

[Full Python Documentation](../sdk/python.md#capture_exception)

### AWS SDK spans

Serverless automatically instruments `aws-sdk` and `boto3`(`botocore` specifically) in NodeJS and
Python. Calls(service & operation. eg: S3 putItem) to the SDK are show in the invocation detail
in the dashboard.
## Custom instrumentation using the Serverless SDK

### HTTP spans
In addition to the automatic instrumentation provided by Serverless Framework Dashboard, you can also add custom instrumentation using the Serverless SDK.

Serverless also instruments your lambdas to report the spans for HTTP & HTTPS requests. In NodeJS
the `http` and `https` modules are instrumented, so any library built upon those will be captured.
In Python, the `urllib3`(thus `requests`) and `urllib2`(in Python2) and `urlib.request`(in Python3)
libraries are instrumented to capture HTTP & HTTPS requests.
You can use the Serverless SDK for a few use cases:

By default, requests to AWS are not captured because of the above AWS SDK instrumentation which
provides more insight into the request.
- Capturing handled errors
- Capturing custom spans
- Capturing error and warnings events
- Tagging traces for better searchability
- Integrating with structured logging libraries

[Configuration docs](../sdk/#advanced-span-configuration)

### Custom function spans

You can also instrument your own spans for services not covered by AWS SDK & HTTP span
instrumentation such as databases.

Here's an example of how to instrument a block of code in NodeJS:

```javascript
module.exports.handler = async (event, context) => {
await context.span('some-label', async () => {
// The execution of this function is captured as a span.
// It is automatically invoked with no arguments and awaited.
});
};
```
See the SDK documentation for Node and Python for details.

[Full NodeJS Documentation](../sdk/nodejs.md#span)

[Full Python Documentation](../sdk/python.md#span)

### Pull-based log ingestion

The default monitoring path for the Serverless Framework involves setting up a Subscription Filter on your CloudWatch Log Group to send selected logs to the Serverless Framework ingestion system.

AWS currently has a hard limit of one Subscription Filter per Log Group. If you try to deploy with the Serverless Framework plugin, you'll get an error saying the resource limit was exceeded.

If you want to keep your existing Subscription while still adding Serverless Framework support, you can enable pull-based log ingestion using the following syntax in your `serverless.yml`:

```yaml
custom:
enterprise:
logIngestMode: pull
```

With pull-based ingestion, the Serverless Framework infrastructure will periodically request logs from your CloudWatch Log Group and send them into our system.

Please note that using the pull-based log ingestion method will result in delays in ingesting your logs. This delay is usually between 30 and 120 seconds. As such, we recommend only using the pull-based log ingestion method in a development environment or when testing the features of Serverless Framework.
62 changes: 62 additions & 0 deletions docs/guides/monitoring/instrumentation.md
View file
@@ -0,0 +1,62 @@
<!--
title: Serverless Dashboard - Instrumentation
menuText: Instrumentation
layout: Doc
-->

<!-- DOCS-SITE-LINK:START automatically generated -->

### [Read this on the main serverless docs site](https://www.serverless.com/framework/docs/guides/monitoring/instrumentation/)

<!-- DOCS-SITE-LINK:END -->

# Instrumentation

Once you have added the AWS Account Integration, you will need to enable
instrumentation on each AWS Lambda function to enable metric, log, trace, span,
and events collection in Serverless Framework Dashboard.

Currently Instrumentation is supported for the Node.js 12+ and Python 3.8+
runtimes only; however, other runtime support is coming soon.

## Enabling instrumentation for a function

To enable instrumentation go to **Settings** > **Integrations** and select the
AWS Integration, and click **Edit**.

On the integration settings page you'll have the option to set the
**Instrumentation** to **On**.

When instrumentation is enabled, then metrics, logs, traces, spans, and events
are collected and made available on Metrics and Explorer in Serverless Framework
Dashboard. Instrumentation is optimized for production use, as it adds virtually
no latency to the Lambda function, and Trace Sampling limits the number of
ingested traces.

## Trace Sampling

To help you reduce costs, Serverless Framework Dashboard provides Trace Sampling
to limit the number of ingested traces.

No further action is needed to enable sampling.

Trace sampling is applied progressively in proportion to invocation load. At
low volumes the sample rate will be 0%, meaning 100% of invocations will
generate traces, while at high volumes only 20% of successful invocations will
be generate traces.

If a trace contains any error or warning events, including any warnings
generated by the SDK (e.g. invalid tag key on `setTag()`), then the Trace will
not be sampled. This ensures that all errors and warnings will be available in
the Trace Explorer.

Metrics are not subject to Sampling. All metrics generated and collected by the
Instrumentation will continue to work, even if the trace was successful.

## Custom Instrumentation

In addition to the automatic instrumentation of your AWS Lambda functions, you
can also add custom instrumentation for setting tags, and events in your code.

Use the [Node.js](./nodejs-sdk.md) and [Python](./python-sdk.md) Serverless SDK
to add custom instrumentation.
71 changes: 66 additions & 5 deletions docs/guides/monitoring/metrics.md
View file
Expand Up @@ -12,12 +12,73 @@ layout: Doc

# Metrics

As part of the Serverless Insights feature we also include a set of pre-configured metrics and charts, including the following:
Metrics is a Serverless Dashboard feature which enables viewing metrics across
AWS Accounts and Lambda functions.

## Errors and Invocations
To get started you need to [add an AWS Account integration](./integrations/aws.md)
and [enable Dev or Prod Instrumentation Mode](./instrumentation.md).

The errors and invocations chart shows error count trends and the aggregate number of invocations for a particular service for a selected time period. Click into any bar on the chart to see function specific metrics.
Once instrumentation is enabled, go to the **Metrics** page to view all of your
AWS Lambda function metrics including durations, invocations, and event counts.

## Durations
Currently Metrics are supported on the Node.js 12+ and Python 3.8+ runtimes on
AWS Lambda only. Support for other runtimes is coming soon.

The durations chart shows the aggregate duration times for all functions in a particular Service for a selected time period. Click into any point on the chart to see function specific metrics.
## Metric Aggregation

Metrics are automatically aggregated on the charts over an interval as small as
1 minute, and as large as 1 day, depending on the time interval you select. As
such, the metrics are only available in aggregate, not as individual data
points.

## Available Charts

The metrics page features a number of charts, including Invocations, Uncaught
Errors, and more. The title of each chart provides a tooltip with a detailed
description of the metric.

You can also hover over individual bars to get a detailed breakdown of the
metrics for that point in time.

Majority of the charts are interactive. You can click on the chart, which will
send you to the Trace Explorer to view the full chart and individual traces
which meat the same filter criteria.

## Saving Views

From the title, you can select to create a new custom view of the Metrics. All
the filters will be saved with that view. This enables you to create views for
specific use cases. When filters are updated, they are saved in the view.

## Filters

Applying filters to the metrics view allows you to narrow in on
specific functions, or use cases that are of interest to you. Filters can be
saved as a shared views to collaborate with team mates on specific searches.

- **Resources** - Filter for specific AWS Resources in any of the integrated
AWS Accounts. Currently this only supports AWS Lambda, but other AWS resources
will be made available soon.
- **Namespace** - Namespaces are configured on individual AWS Lambda functions
on the AWS Integrations page. Filtering by namespace allows you to filter the
metrics based on the namespaces that were configured on the functions for which
the metric applies.
- **Environment** - Like namespaces, environments are configured on the AWS
Integration page for each AWS Lambda function. The are also automatically
determined from the CloudFormation stack if applicable. Filtering by environment
allows you to filter the metrics based on the environments that were configured
on the functions for which the metric applies.
- **Region** - Region is the specific AWS Region of the Lambda function.
- **AWS Account** - If you have multiple AWS Account integrations in your
org, you can filter for metrics for individual AWS Accounts.
- **Events** - Individual invocations may produce multiple errors or warnings.
The Serverless SDK may also produce errors and warnings. Filtering by Events
enables filtering for invocations which include any of the selected Event types.
You can find more details about Event types on the [Trace Explorer](./trace-explorer.md).
- **Cold start** - Filters for metrics on AWS Lambda invocations that were a
cold start.
- **Duration** - Filters based on the AWS Lambda response duration.
- **Custom Tags** - Filters for metrics on invocations that had the provided
custom tags. Custom tags on traces, errors, and warnings are all queried. Use
the [Node.js](../nodejs-sdk.md) or [Python](./python-sdk.md) Serverless SDK to
set custom tags.

0 comments on commit c66aad7

Please sign in to comment.