initial draft of lambda guidance (#2632)

Co-authored-by: Severin Neumann <[email protected]> Co-authored-by: Patrice Chalin <[email protected]> Co-authored-by: Phillip Carter <[email protected]>
open-telemetry · May 6, 2023 · 5d56161 · 5d56161
1 parent eef8331
commit 5d56161
Show file tree

Hide file tree

Showing 5 changed files with 361 additions and 0 deletions.
diff --git a/content/en/docs/faas/_index.md b/content/en/docs/faas/_index.md
@@ -0,0 +1,27 @@
+---
+title: Functions as a Service
+linkTitle: FaaS
+description: >-
+  OpenTelemetry supports various methods of monitoring Function-as-a-Service
+  provided by different cloud vendors
+weight: 12
+---
+
+Functions as a Service (FaaS) is an important serverless compute platform for
+cloud native applications. However, platform quirks usually mean these
+applications have slightly different monitoring guidance and requirements than
+applications running on Kubernetes or Virtual Machines.
+
+The initial vendor scope of the FaaS documentation is around Microsoft Azure,
+Google Cloud Platform (GCP), and Amazon Web Services (AWS). AWS functions are
+also known as Lambda.
+
+### Community Assets
+
+The OpenTelemetry community currently provides pre-built Lambda layers able to
+auto-instrument your application as well as a the option of standalone Collector
+Lambda layer that can be used when instrumenting applications manually or
+automatically.
+
+The release status can be tracked in the
+[OpenTelemetry-Lambda repository](https://github.com/open-telemetry/opentelemetry-lambda).
diff --git a/content/en/docs/faas/lambda-auto-instrument.md b/content/en/docs/faas/lambda-auto-instrument.md
@@ -0,0 +1,131 @@
+---
+title: Lambda Auto-Instrumentation
+weight: 11
+description: Automatically instrument your Lambdas with OpenTelemetry
+---
+
+The OpenTelemetry community provides standalone instrumentation Lambda layers
+for the following languages:
+
+- Java
+- JavaScript
+- Python
+
+These can be added to your Lambda using the AWS portal to automatically
+instrument your application. These layers do not include the Collector which is
+a required addition unless you configure an external Collector instance to send
+your data.
+
+### Add the ARN of the OTel Collector Lambda layer
+
+See the [Collector Lambda layer guidance](../lambda-collector/) to add the layer
+to your application and configure the Collector. We recommend you add this
+first.
+
+### Language Requirements
+
+<!-- prettier-ignore -->
+{{< tabpane text=true >}}
+{{% tab Java %}}
+
+The Lambda layer supports the Java 11 (Corretto) Lambda runtime. It does not
+support the Java 8 Lambda runtimes. For more information about supported Java
+versions, see the
+[OpenTelemetry Java documentation](/docs/instrumentation/java/).
+
+**Note:** The Java Auto-instrumentation Agent is in the Lambda layer - Automatic
+instrumentation has a notable impact on startup time on AWS Lambda and you will
+generally need to use this along with provisioned concurrency and warmup
+requests to serve production requests without causing timeouts on initial
+requests while it initializes.
+
+By default, the OTel Java Agent in the Layer will try to auto-instrument all the
+code in your application. This can have a negative impact on the Lambda cold
+startup time.
+
+We recommend that you only enable auto-instrumentation for the
+libraries/frameworks that are used by your application.
+
+To enable only specific instrumentations you can use the following environment
+variables:
+
+    * OTEL_INSTRUMENTATION_COMMON_DEFAULT_ENABLED - When set to false, disables auto-instrumentation in the Layer, requiring each instrumentation to be enabled individually.
+    * OTEL_INSTRUMENTATION_[NAME]_ENABLED - Set to true to enable auto-instrumentation for a specific library or framework. [NAME] should be replaced by the instrumentation that you want to enable. The full list of available instrumentations can be found in this link.
+
+For example, to only enable auto-instrumentation for Lambda and the AWS SDK, you
+would have to set the following environment variables:
+
+    ```bash
+    Copy
+    OTEL_INSTRUMENTATION_COMMON_DEFAULT_ENABLED=false
+    OTEL_INSTRUMENTATION_AWS_LAMBDA_ENABLED=true
+    OTEL_INSTRUMENTATION_AWS_SDK_ENABLED=true
+    ```
+
+<!-- prettier-ignore -->
+{{% /tab %}}
+{{% tab JavaScript %}}
+
+The Lambda layer supports Node.JS v14+ Lambda runtimes. For more information
+about supported JavaScript and Node.JS versions, see the
+[OpenTelemetry JavaScript documentation](https://github.com/open-telemetry/opentelemetry-js).
+
+<!-- prettier-ignore -->
+{{% /tab %}}
+{{% tab Python %}}
+
+The Lambda layer supports Python 3.8 and Python 3.9 Lambda runtimes. For more
+information about supported Python versions, see the
+[OpenTelemetry Python documentation](https://github.com/open-telemetry/opentelemetry-python/blob/master/README.md#supported-runtimes)
+and the package on [PyPi](https://pypi.org/project/opentelemetry-api/).
+
+<!-- prettier-ignore -->
+{{% /tab %}}
+{{< /tabpane >}}
+
+### Add the ARN of Instrumentation Lambda Layer
+
+To enable the OTel auto-instrumentation in your Lambda function, you need to add
+and configure the instrumentation and Collector layers, and then enable tracing.
+
+1. Open the Lambda function you intend to instrument in the AWS console.
+2. In the Layers in Designer section, choose Add a layer.
+3. Under specify an ARN, paste the layer ARN, and then choose Add.
+
+### Configure your SDK exporters
+
+The default exporters used by the Lambda layers will work without any changes if
+there is an embedded Collector with gRPC / HTTP receivers. The environment
+variables do not need to be updated. However, there are varying levels of
+protocol support and default values by language which are documented below.
+
+<!-- prettier-ignore -->
+{{< tabpane text=true >}}
+{{% tab Java %}}
+
+`OTEL_EXPORTER_OTLP_PROTOCOL=grpc` Supports: `grpc`, `http/protobuf` and
+`http/json` `OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317`
+
+<!-- prettier-ignore -->
+{{% /tab %}}
+{{% tab Python %}}
+
+`OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf` Supports: `http/protobuf` and
+`http/json` `OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318`
+
+<!-- prettier-ignore -->
+{{% /tab %}}
+{{% tab JavaScript %}}
+
+`OTEL_EXPORTER_OTLP_PROTOCOL` env var is not supported The hard coded exporter
+uses the protocol `http/protobuf`
+`OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318`
+
+<!-- prettier-ignore -->
+{{% /tab %}}
+{{< /tabpane >}}
+
+### Publish your Lambda
+
+Publish a new version of your Lambda to deploy the new changes and
+instrumentation.
diff --git a/content/en/docs/faas/lambda-collector.md b/content/en/docs/faas/lambda-collector.md
@@ -0,0 +1,168 @@
+---
+title: Lambda Collector Configuration
+linkTitle: Lambda Collector Config
+weight: 11
+description: Add and configure the Collector Lambda layer to your Lambda
+---
+
+The OpenTelemetry community offers the Collector in a separate Lambda layer from
+the instrumentation layers to give users maximum flexibility. This is different
+than the current AWS Distribution of OpenTelemetry (ADOT) implementation which
+bundles instrumentation and the Collector together.
+
+### Add the ARN of the OTel Collector Lambda layer
+
+Once you've instrumented your application you should add the Collector Lambda
+layer to collect and submit your data to your chosen backend.
+
+Note: Lambda layers are a regionalized resource, meaning that they can only be
+used in the Region in which they are published. Make sure to use the layer in
+the same region as your Lambda functions.
+
+Find the supported regions and amd64(x86_64)/arm64 layer ARN in the table below
+for the ARNs to consume.
+
+### Configure the OTel Collector
+
+The configuration of the OTel Collector Lambda layer follows the OpenTelemetry
+standard.
+
+By default, the OTel Collector Lambda layer uses the config.yaml.
+
+#### Set the Environment Variable for your Preferred Backend
+
+In the Lambda environment variable settings create a new variable that holds
+your authorization token.
+
+#### Update the Default Exporters
+
+In your `config.yaml` file add your preferred exporter(s) if they are not
+already present. Configure your exporter(s) using the environment variables you
+set for your access tokens in the previous step.
+
+**Without an environment variable being set for your exporters the default
+configuration only supports emitting data using the logging exporter.** Here is
+the default configuration:
+
+```yaml
+receivers:
+  otlp:
+    protocols:
+      grpc:
+        endpoint: 'localhost:4317'
+      http:
+        endpoint: 'localhost:4318'
+
+exporters:
+  logging:
+    loglevel: debug
+
+service:
+  pipelines:
+    traces:
+      receivers: [otlp]
+      exporters: [logging]
+    metrics:
+      receivers: [otlp]
+      exporters: [logging]
+  telemetry:
+    metrics:
+      address: localhost:8888
+```
+
+### Publish your Lambda
+
+Publish a new version of your Lambda to enable the changes you made.
+
+### Advanced OTel Collector Configuration
+
+Please find the list of available components supported for custom configuration
+here. To enable debugging, you can use the configuration file to set log level
+to debug. See the example below.
+
+#### Choose your Preferred Confmap Provider
+
+The OTel Lambda Layers supports the following types of confmap providers:
+`file`, `env`, `yaml`, `http`, `https`, and `s3`. To customize the OTel
+collector configuration using different Confmap providers, Please refer to
+[Amazon Distribution of OpenTelemetry Confmap providers document](https://aws-otel.github.io/docs/components/confmap-providers#confmap-providers-supported-by-the-adot-collector)
+for more information.
+
+#### Create a Custom Configuration File
+
+Here is a sample configuration file of `collector.yaml` in the root directory:
+
+```yaml
+#collector.yaml in the root directory
+#Set an environemnt variable 'OPENTELEMETRY_COLLECTOR_CONFIG_FILE' to '/var/task/collector.yaml'
+
+receivers:
+  otlp:
+    protocols:
+      grpc:
+        endpoint: 'localhost:4317'
+      http:
+        endpoint: 'localhost:4318'
+
+exporters:
+  logging:
+  awsxray:
+
+service:
+  pipelines:
+    traces:
+      receivers: [otlp]
+      exporters: [awsxray]
+    metrics:
+      receivers: [otlp]
+      exporters: [logging]
+  telemetry:
+    metrics:
+      address: localhost:8888
+```
+
+#### Map your Custom Configuration File using Environment Variables
+
+Once your collector configuration is set through a confmap providers. Create an
+environment variable on your Lambda function
+`OPENTELEMETRY_COLLECTOR_CONFIG_FILE` and set the path of configuration w.r.t to
+the confmap provider as its value. for e.g, if you are using a file configmap
+provider, set its value to `/var/task/*<path>/<to>/<filename>\_`. This will tell
+the extension where to find the collector configuration.
+
+##### Custom Collector Configuration Using the CLI
+
+You can set this via the Lambda console, or via the AWS CLI.
+
+```bash
+aws lambda update-function-configuration --function-name Function --environment Variables={OPENTELEMETRY_COLLECTOR_CONFIG_FILE=/var/task/collector.yaml}
+```
+
+##### Set Configuration Environment Variables from CloudFormation
+
+You can configure environment variables via **CloudFormation** template as well:
+
+```yaml
+Function:
+  Type: AWS::Serverless::Function
+  Properties:
+    ...
+    Environment:
+      Variables:
+        OPENTELEMETRY_COLLECTOR_CONFIG_FILE: /var/task/collector.yaml
+```
+
+##### Load Configuration from an S3 Object
+
+Loading configuration from S3 will require that the IAM role attached to your
+function includes read access to the relevant bucket.
+
+```yaml
+  Function:
+    Type: AWS::Serverless::Function
+    Properties:
+      ...
+      Environment:
+        Variables:
+          OPENTELEMETRY_COLLECTOR_CONFIG_FILE: s3://<bucket_name>.s3.<region>.amazonaws.com/collector_config.yaml
+```
diff --git a/content/en/docs/faas/lambda-manual-instrument.md b/content/en/docs/faas/lambda-manual-instrument.md
@@ -0,0 +1,27 @@
+---
+title: Lambda Manual Instrumentation
+weight: 11
+description: Manually instrument your Lambdas with OpenTelemetry
+---
+
+For languages not covered in the Lambda auto-instrumentation document, the
+community does not have a standalone instrumentation layer.
+
+Users will need to follow the generic instrumentation guidance for their chosen
+language and add the Collector Lambda layer to submit their data.
+
+### Add the ARN of the OTel Collector Lambda layer
+
+See the [Collector Lambda layer guidance](../lambda-collector/) to add the layer
+to your application and configure the Collector. We recommend you add this
+first.
+
+### Instrument the Lambda with OTel
+
+Review the [language instrumentation guidance](/docs/instrumentation/) on how to
+manually instrument your application.
+
+### Publish your Lambda
+
+Publish a new version of your Lambda to deploy the new changes and
+instrumentation.
diff --git a/static/refcache.json b/static/refcache.json
@@ -95,6 +95,10 @@
     "StatusCode": 206,
     "LastSeen": "2023-02-15T20:20:22.109017-05:00"
   },
+  "https://aws-otel.github.io/docs/components/confmap-providers#confmap-providers-supported-by-the-adot-collector": {
+    "StatusCode": 206,
+    "LastSeen": "2023-05-05T14:18:57.288423-07:00"
+  },
   "https://aws.amazon.com/": {
     "StatusCode": 200,
     "LastSeen": "2023-02-15T20:20:57.179898-05:00"
@@ -3559,6 +3563,10 @@
     "StatusCode": 200,
     "LastSeen": "2023-02-20T08:26:15.285143-05:00"
   },
+  "https://pypi.org/project/opentelemetry-api/": {
+    "StatusCode": 206,
+    "LastSeen": "2023-05-05T14:18:57.011667-07:00"
+  },
   "https://quarkus.io": {
     "StatusCode": 206,
     "LastSeen": "2023-02-18T12:39:46.550519-05:00"