diff --git a/content/en/docs/faas/_index.md b/content/en/docs/faas/_index.md new file mode 100644 index 000000000000..f9200a395538 --- /dev/null +++ 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 new file mode 100644 index 000000000000..272cc95f859e --- /dev/null +++ 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 + + +{{< 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 + ``` + + +{{% /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). + + +{{% /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/). + + +{{% /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. + + +{{< tabpane text=true >}} +{{% tab Java %}} + +`OTEL_EXPORTER_OTLP_PROTOCOL=grpc` Supports: `grpc`, `http/protobuf` and +`http/json` `OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317` + + +{{% /tab %}} +{{% tab Python %}} + +`OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf` Supports: `http/protobuf` and +`http/json` `OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318` + + +{{% /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` + + +{{% /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 new file mode 100644 index 000000000000..e47512ba5aee --- /dev/null +++ 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/*//\_`. 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://.s3..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 new file mode 100644 index 000000000000..4d9384111c6a --- /dev/null +++ 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 index 8858ea997008..429c5bb30b36 100644 --- 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"