# Lambda Auto-Instrumentation

> Automatically instrument your Lambdas with OpenTelemetry

---

The OpenTelemetry community provides standalone instrumentation Lambda layers
for the following languages:

- Java
- JavaScript
- Python
- Ruby

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

     <ul class="nav nav-tabs" id="tabs-0" role="tablist">
  <li class="nav-item">
      <button class="nav-link active"
          id="tabs-00-00-tab" data-bs-toggle="tab" data-bs-target="#tabs-00-00" role="tab"
          data-td-tp-persist="java" aria-controls="tabs-00-00" aria-selected="true">
        Java
      </button>
    </li><li class="nav-item">
      <button class="nav-link"
          id="tabs-00-01-tab" data-bs-toggle="tab" data-bs-target="#tabs-00-01" role="tab"
          data-td-tp-persist="javascript" aria-controls="tabs-00-01" aria-selected="false">
        JavaScript
      </button>
    </li><li class="nav-item">
      <button class="nav-link"
          id="tabs-00-02-tab" data-bs-toggle="tab" data-bs-target="#tabs-00-02" role="tab"
          data-td-tp-persist="python" aria-controls="tabs-00-02" aria-selected="false">
        Python
      </button>
    </li><li class="nav-item">
      <button class="nav-link"
          id="tabs-00-03-tab" data-bs-toggle="tab" data-bs-target="#tabs-00-03" role="tab"
          data-td-tp-persist="ruby" aria-controls="tabs-00-03" aria-selected="false">
        Ruby
      </button>
    </li>
</ul>

<div class="tab-content" id="tabs-0-content">
    <div class="tab-body tab-pane fade show active"
        id="tabs-00-00" role="tabpanel" aria-labelled-by="tabs-00-00-tab" tabindex="0">
        <p>The Lambda layer supports the Java 8, 11, and 17 (Corretto) Lambda runtimes. For
more information about supported Java versions, see the
<a href="/zh/docs/languages/java/">OpenTelemetry Java documentation</a>.</p>
<p><strong>Note:</strong> 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.</p>
<p>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.</p>
<p>We recommend that you only enable auto-instrumentation for the
libraries/frameworks that are used by your application.</p>
<p>To enable only specific instrumentations, you can use the following environment
variables:</p>
<ul>
<li>
<p><code>OTEL_INSTRUMENTATION_COMMON_DEFAULT_ENABLED</code>: when set to false, disables
auto-instrumentation in the Layer, requiring each instrumentation to be
enabled individually.</p>
</li>
<li>
<p><code>OTEL_INSTRUMENTATION_&lt;NAME&gt;_ENABLED</code>: set to true to enable
auto-instrumentation for a specific library or framework. Replace <code>&lt;NAME&gt;</code> by
the instrumentation that you want to enable. For the list of available
instrumentations, see <a href="/zh/docs/zero-code/java/agent/disable/#suppressing-specific-agent-instrumentation">Suppressing specific agent instrumentation</a>.</p>
</li>
</ul>
<p>For example, to only enable auto-instrumentation for Lambda and the AWS SDK, you
would set the following environment variables:</p>
<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-sh" data-lang="sh"><span class="line"><span class="cl"><span class="nv">OTEL_INSTRUMENTATION_COMMON_DEFAULT_ENABLED</span><span class="o">=</span><span class="nb">false</span>
</span></span><span class="line"><span class="cl"><span class="nv">OTEL_INSTRUMENTATION_AWS_LAMBDA_ENABLED</span><span class="o">=</span><span class="nb">true</span>
</span></span><span class="line"><span class="cl"><span class="nv">OTEL_INSTRUMENTATION_AWS_SDK_ENABLED</span><span class="o">=</span><span class="nb">true</span>
</span></span></code></pre></div>
    </div>
    <div class="tab-body tab-pane fade"
        id="tabs-00-01" role="tabpanel" aria-labelled-by="tabs-00-01-tab" tabindex="0">
        <p>The Lambda layer supports Node.js v18+ Lambda runtimes. For more information
about supported JavaScript and Node.js versions, see the
<a href="https://github.com/open-telemetry/opentelemetry-js" target="_blank" rel="noopener" class="external-link">OpenTelemetry JavaScript documentation</a>.</p>

    </div>
    <div class="tab-body tab-pane fade"
        id="tabs-00-02" role="tabpanel" aria-labelled-by="tabs-00-02-tab" tabindex="0">
        <p>The Lambda layer supports Python 3.9+ Lambda runtimes. For more information
about supported Python versions, see the
<a href="https://github.com/open-telemetry/opentelemetry-python/blob/main/README.md#supported-runtimes" target="_blank" rel="noopener" class="external-link">OpenTelemetry Python documentation</a>
and the package on <a href="https://pypi.org/project/opentelemetry-api/" target="_blank" rel="noopener" class="external-link">PyPi</a>.</p>

    </div>
    <div class="tab-body tab-pane fade"
        id="tabs-00-03" role="tabpanel" aria-labelled-by="tabs-00-03-tab" tabindex="0">
        <p>The Lambda layer supports Ruby 3.2 and 3.3 Lambda runtimes. For more information
about supported OpenTelemetry Ruby SDK and API versions, see the
<a href="https://github.com/open-telemetry/opentelemetry-ruby/blob/main/README.md#compatibility" target="_blank" rel="noopener" class="external-link">OpenTelemetry Ruby documentation</a>
and the package on <a href="https://rubygems.org/search?query=opentelemetry" target="_blank" rel="noopener" class="external-link">RubyGem</a>.</p>

    </div>
</div>


## Configure `AWS_LAMBDA_EXEC_WRAPPER`

Change the entry point of your application by setting
`AWS_LAMBDA_EXEC_WRAPPER=/opt/otel-handler` for Node.js, Java, Ruby, or Python.
This wrapper script invokes your Lambda application with the automatic
instrumentation applied.

## 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.

Find the
[most recent instrumentation layer release](https://github.com/open-telemetry/opentelemetry-lambda/releases)
for your language and use its ARN after changing the `<region>` tag to the
region your Lambda is in.

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. The community publishes layers in all
available regions.

## 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.

     <ul class="nav nav-tabs" id="tabs-1" role="tablist">
  <li class="nav-item">
      <button class="nav-link active"
          id="tabs-01-00-tab" data-bs-toggle="tab" data-bs-target="#tabs-01-00" role="tab"
          data-td-tp-persist="java" aria-controls="tabs-01-00" aria-selected="true">
        Java
      </button>
    </li><li class="nav-item">
      <button class="nav-link"
          id="tabs-01-01-tab" data-bs-toggle="tab" data-bs-target="#tabs-01-01" role="tab"
          data-td-tp-persist="javascript" aria-controls="tabs-01-01" aria-selected="false">
        JavaScript
      </button>
    </li><li class="nav-item">
      <button class="nav-link"
          id="tabs-01-02-tab" data-bs-toggle="tab" data-bs-target="#tabs-01-02" role="tab"
          data-td-tp-persist="python" aria-controls="tabs-01-02" aria-selected="false">
        Python
      </button>
    </li><li class="nav-item">
      <button class="nav-link"
          id="tabs-01-03-tab" data-bs-toggle="tab" data-bs-target="#tabs-01-03" role="tab"
          data-td-tp-persist="ruby" aria-controls="tabs-01-03" aria-selected="false">
        Ruby
      </button>
    </li>
</ul>

<div class="tab-content" id="tabs-1-content">
    <div class="tab-body tab-pane fade show active"
        id="tabs-01-00" role="tabpanel" aria-labelled-by="tabs-01-00-tab" tabindex="1">
        <p><code>OTEL_EXPORTER_OTLP_PROTOCOL=grpc</code> supports: <code>grpc</code>, <code>http/protobuf</code> and
<code>http/json</code> <code>OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317</code></p>

    </div>
    <div class="tab-body tab-pane fade"
        id="tabs-01-01" role="tabpanel" aria-labelled-by="tabs-01-01-tab" tabindex="1">
        <p><code>OTEL_EXPORTER_OTLP_PROTOCOL</code> env var is not supported The hard coded exporter
uses the protocol <code>http/protobuf</code>
<code>OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318</code></p>

    </div>
    <div class="tab-body tab-pane fade"
        id="tabs-01-02" role="tabpanel" aria-labelled-by="tabs-01-02-tab" tabindex="1">
        <p><code>OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf</code> supports: <code>http/protobuf</code> and
<code>http/json</code> <code>OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318</code></p>

    </div>
    <div class="tab-body tab-pane fade"
        id="tabs-01-03" role="tabpanel" aria-labelled-by="tabs-01-03-tab" tabindex="1">
        <p><code>OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf</code> supports: <code>http/protobuf</code>
<code>OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318</code></p>

    </div>
</div>


## Publish your Lambda

Publish a new version of your Lambda to deploy the new changes and
instrumentation.
