AWS Lambda

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.

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:

npm install @clickhouse/clickstack-node

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

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:

// 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

Fully managed
Self-managed

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:

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'

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.

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 to select layers for your runtime, architecture, and AWS region and configure the instrumentation wrapper. Add and configure the OpenTelemetry Collector Lambda layer. 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.

Fully managed
Self-managed

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.

exporters:
  otlphttp/clickhouse:
    endpoint: ${env:CLICKHOUSE_OTLP_ENDPOINT}
    headers:
      Authorization: "Bearer ${env:CLICKHOUSE_INGESTION_API_KEY}"

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.

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:

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.

Introduction

Features

Administration

Guides

Integration partners

Self-managed

Node.js async handlers

Configure your destination

Other runtimes and handlers

Configure the Lambda Collector destination

Verify ingestion

​Node.js async handlers

​Configure your destination

​Other runtimes and handlers

​Configure the Lambda Collector destination

​Verify ingestion

Node.js async handlers

Configure your destination

Other runtimes and handlers

Configure the Lambda Collector destination

Verify ingestion