> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# AWS Lambda

> AWS Lambda setup and configuration for ClickHouse Observability and self-managed deployments.

For Node.js functions with async handlers, use the ClickStack Node.js SDK. For other runtimes or callback-based handlers, use the OpenTelemetry Lambda layers described below.

This guide integrates:

## Node.js async handlers

Use a Lambda Node.js runtime that meets the SDK's Node.js 22.15 minimum. Install the SDK and include it in your deployment package:

```shell theme={null}
npm install @clickhouse/clickstack-node
```

Set these Lambda environment variables to initialize the SDK before your handler loads and name your service:

```text theme={null}
NODE_OPTIONS=--import @clickhouse/clickstack-node/register
OTEL_SERVICE_NAME=my-lambda-function
```

Wrap your async handler with `withFlush` so buffered telemetry is exported before the invocation returns:

```javascript theme={null}
// index.mjs
import { withFlush } from '@clickhouse/clickstack-node';

export const handler = withFlush(async (event) => {
  console.log('request received');
  return { statusCode: 200, body: 'OK' };
});
```

Set the function's handler to `index.handler`. If you bundle the function, keep the SDK and instrumented dependencies external and include them in the deployment package. Do not also enable an auto-instrumentation Lambda layer for this setup.

Set the destination variables below in the Lambda function's environment configuration. The endpoint must be reachable from your function. The SDK ends its flush before the invocation deadline; callback-based handlers are not supported by `withFlush`.

### Configure your destination

> [tab] Fully managed
>
> [Beta offering](https://clickhouse.com/docs/reference/settings/beta-and-experimental-features.md#beta-features)
>
> Open **Team Settings → Data → Managed Telemetry** in your service and copy the **OTLP HTTP endpoint** and **API key**. Use the complete HTTPS endpoint, including its port:
>
> ```shell theme={null}
> export OTEL_EXPORTER_OTLP_ENDPOINT='https://YOUR_OTEL_ENDPOINT:4318'
> export OTEL_EXPORTER_OTLP_HEADERS='authorization=Bearer%20YOUR_INGESTION_API_KEY'
> export OTEL_EXPORTER_OTLP_PROTOCOL='http/protobuf'
> ```

> [tab] Self-managed
>
> Use your collector's OTLP HTTP endpoint and ingestion key. Use `http://` instead of `https://` if your collector does not have TLS configured. For collector setup, see [Ingesting with OpenTelemetry](https://clickhouse.com/docs/clickstack/observability/ingesting-data/opentelemetry.md#self-managed).
>
> ```shell theme={null}
> export OTEL_EXPORTER_OTLP_ENDPOINT='https://YOUR_COLLECTOR_HOST:4318'
> export OTEL_EXPORTER_OTLP_HEADERS='authorization=YOUR_INGESTION_API_KEY'
> export OTEL_EXPORTER_OTLP_PROTOCOL='http/protobuf'
> ```

## Other runtimes and handlers

Follow the official [Lambda auto-instrumentation instructions](https://opentelemetry.io/docs/platforms/faas/lambda-auto-instrument/) to select layers for your runtime, architecture, and AWS region and configure the instrumentation wrapper.

Add and configure the [OpenTelemetry Collector Lambda layer](https://opentelemetry.io/docs/platforms/faas/lambda-collector/). Keep the application's SDK exporters pointed at the local Collector, as described upstream. Configure the Collector's outgoing connection below.

### Configure the Lambda Collector destination

Set `CLICKHOUSE_OTLP_ENDPOINT` and `CLICKHOUSE_INGESTION_API_KEY` in your Lambda function's environment variables. Add the following exporter to your Collector configuration.

> [tab] Fully managed
>
> [Beta offering](https://clickhouse.com/docs/reference/settings/beta-and-experimental-features.md#beta-features)
>
> Open **Team Settings → Data → Managed Telemetry** in your service and copy the **OTLP HTTP endpoint** and **API key**. Set `CLICKHOUSE_OTLP_ENDPOINT` to the complete HTTPS endpoint, including its port, and `CLICKHOUSE_INGESTION_API_KEY` to the key.
>
> ```yaml theme={null}
> exporters:
>   otlphttp/clickhouse:
>     endpoint: ${env:CLICKHOUSE_OTLP_ENDPOINT}
>     headers:
>       Authorization: "Bearer ${env:CLICKHOUSE_INGESTION_API_KEY}"
> ```

> [tab] Self-managed
>
> Set `CLICKHOUSE_OTLP_ENDPOINT` to your collector's OTLP HTTP endpoint and `CLICKHOUSE_INGESTION_API_KEY` to its ingestion key. The endpoint must be reachable from your Lambda function. For destination collector setup, see [Ingesting with OpenTelemetry](https://clickhouse.com/docs/clickstack/observability/ingesting-data/opentelemetry.md#self-managed).
>
> ```yaml theme={null}
> exporters:
>   otlphttp/clickhouse:
>     endpoint: ${env:CLICKHOUSE_OTLP_ENDPOINT}
>     headers:
>       Authorization: "${env:CLICKHOUSE_INGESTION_API_KEY}"
> ```

Use `otlphttp/clickhouse` in the `exporters` list of each signal pipeline you want to send. For example, with the upstream `otlp` receiver:

```yaml theme={null}
service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [otlphttp/clickhouse]
    metrics:
      receivers: [otlp]
      exporters: [otlphttp/clickhouse]
    logs:
      receivers: [otlp]
      exporters: [otlphttp/clickhouse]
```

Merge these settings into your Collector configuration, preserving its receiver and processor settings. Package the configuration with your function and set `OPENTELEMETRY_COLLECTOR_CONFIG_URI` to its location, such as `/var/task/collector.yaml`, following the upstream Collector setup instructions.

## Verify ingestion

Deploy and invoke your function. In ClickHouse Observability, select a recent time range and find your function's service name in Traces. Check Logs and Metrics if your instrumentation emits those signals; adding a pipeline does not enable their collection automatically.

For layer configuration and troubleshooting, see the [OpenTelemetry Lambda documentation](https://github.com/open-telemetry/opentelemetry-lambda).