AWS Lambda

AWS Lambda para ClickStack - A stack de observabilidade do ClickHouse

Este guia integra:

✅ Logs

✅ Métricas

✅ Traces

​

Instalando as camadas Lambda do OpenTelemetry

O projeto OpenTelemetry fornece camadas Lambda separadas para:

1. Instrumentar automaticamente o código da sua função Lambda usando a instrumentação automática do OpenTelemetry.
2. Encaminhar os logs, métricas e traces coletados para o ClickStack.

​

Adicionando a camada de instrumentação automática específica da linguagem

As camadas Lambda de instrumentação automática específicas da linguagem instrumentam automaticamente o código da sua função Lambda com o pacote de instrumentação automática do OpenTelemetry correspondente à linguagem usada.

Cada linguagem e região tem seu próprio ARN de camada.

Se sua Lambda já estiver instrumentada com um SDK do OpenTelemetry, você pode pular esta etapa.

Para começar:

1. Na seção Layers, clique em “Add a layer”
2. Selecione a opção de especificar um ARN e escolha o ARN correto com base na linguagem, substituindo <region> pela sua região (ex.: us-east-2):

Javascript

arn:aws:lambda:<region>:184161586896:layer:opentelemetry-nodejs-0_7_0:1

Python

copy

arn:aws:lambda:<region>:184161586896:layer:opentelemetry-python-0_7_0:1

Java

copy

arn:aws:lambda:<region>:184161586896:layer:opentelemetry-javaagent-0_6_0:1

Ruby

copy

arn:aws:lambda:<region>:184161586896:layer:opentelemetry-ruby-0_1_0:1

Os lançamentos mais recentes das camadas podem ser encontrados no repositório GitHub do OpenTelemetry Lambda Layers.

3. Configure as seguintes variáveis de ambiente na sua função Lambda em “Configuration” > “Environment variables”.

Javascript

OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
AWS_LAMBDA_EXEC_WRAPPER=/opt/otel-handler
OTEL_PROPAGATORS=tracecontext
OTEL_TRACES_SAMPLER=always_on

Python

OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
AWS_LAMBDA_EXEC_WRAPPER=/opt/otel-instrument
OTEL_PROPAGATORS=tracecontext
OTEL_TRACES_SAMPLER=always_on

Java

OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
AWS_LAMBDA_EXEC_WRAPPER=/opt/otel-handler
OTEL_PROPAGATORS=tracecontext
OTEL_TRACES_SAMPLER=always_on

Ruby

OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
AWS_LAMBDA_EXEC_WRAPPER=/opt/otel-handler
OTEL_PROPAGATORS=tracecontext
OTEL_TRACES_SAMPLER=always_on

​

Instalando a camada Lambda do OpenTelemetry Collector

A camada Lambda do collector permite encaminhar logs, métricas e traces da sua função Lambda para o ClickStack sem afetar os tempos de resposta devido à latência do exporter.

Para instalar a camada do collector:

1. Na seção Layers, clique em “Add a layer”
2. Selecione “Specify an ARN” e escolha o ARN correto com base na arquitetura. Lembre-se de substituir <region> pela sua região (ex.: us-east-2):

x86_64

arn:aws:lambda:<region>:184161586896:layer:opentelemetry-collector-amd64-0_8_0:1

arm64

arn:aws:lambda:<region>:184161586896:layer:opentelemetry-collector-arm64-0_8_0:1

3. Adicione o arquivo collector.yaml abaixo ao seu projeto para configurar o collector para enviar dados ao ClickStack:

Managed ClickStack

# collector.yaml
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 'localhost:4317'
      http:
        endpoint: 'localhost:4318'

processors:
  batch:
  decouple:

exporters:
  otlphttp:
    endpoint: "<YOU_OTEL_COLLECTOR_HTTP_ENDPOINT>"
    compression: gzip

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch, decouple]
      exporters: [otlphttp]
    metrics:
      receivers: [otlp]
      processors: [batch, decouple]
      exporters: [otlphttp]
    logs:
      receivers: [otlp]
      processors: [batch, decouple]
      exporters: [otlphttp]

ClickStack Open Source

# collector.yaml
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 'localhost:4317'
      http:
        endpoint: 'localhost:4318'

processors:
  batch:
  decouple:

exporters:
  otlphttp:
    endpoint: "<YOU_OTEL_COLLECTOR_HTTP_ENDPOINT>"
    headers:
      authorization: <YOUR_INGESTION_API_KEY>
    compression: gzip

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch, decouple]
      exporters: [otlphttp]
    metrics:
      receivers: [otlp]
      processors: [batch, decouple]
      exporters: [otlphttp]
    logs:
      receivers: [otlp]
      processors: [batch, decouple]
      exporters: [otlphttp]

4. Adicione a seguinte variável de ambiente:

OPENTELEMETRY_COLLECTOR_CONFIG_FILE=/var/task/collector.yaml

​

Verificando a instalação

Após implantar as camadas, agora você deverá ver traces coletados automaticamente da sua função Lambda no HyperDX. Os processadores decouple e batching podem introduzir um atraso na coleta de telemetria, então os traces podem demorar para aparecer. Para emitir logs ou métricas personalizados, você precisará instrumentar seu código com os SDKs do OpenTelemetry específicos da sua linguagem.

​

Solução de problemas

​

Instrumentação personalizada não está enviando

Se você não estiver vendo seus traces definidos manualmente nem outros dados de telemetria, talvez esteja usando uma versão incompatível do pacote da API do OpenTelemetry. Verifique se o pacote da API do OpenTelemetry está, no mínimo, na mesma versão ou em uma versão inferior à versão incluída no AWS Lambda.

​

Habilitando logs de depuração do SDK

Defina a variável de ambiente OTEL_LOG_LEVEL como DEBUG para habilitar os logs de depuração do SDK do OpenTelemetry. Isso ajuda a garantir que a camada de instrumentação automática esteja instrumentando sua aplicação corretamente.

​

Habilitando logs de depuração do collector

Para diagnosticar problemas no collector, você pode habilitar os logs de depuração modificando o arquivo de configuração do collector para adicionar o exporter logging e definindo o nível de log de telemetria como debug, o que habilita logs mais detalhados da Lambda layer do collector.

Managed ClickStack

# collector.yaml
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 'localhost:4317'
      http:
        endpoint: 'localhost:4318'

exporters:
  logging:
    verbosity: detailed
  otlphttp:
    endpoint: "<YOU_OTEL_COLLECTOR_HTTP_ENDPOINT>"
    compression: gzip

service:
  telemetry:
    logs:
      level: "debug"
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch, decouple]
      exporters: [otlphttp, logging]
    metrics:
      receivers: [otlp]
      processors: [batch, decouple]
      exporters: [otlphttp, logging]
    logs:
      receivers: [otlp]
      processors: [batch, decouple]
      exporters: [otlphttp, logging]

ClickStack Open Source

# collector.yaml
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 'localhost:4317'
      http:
        endpoint: 'localhost:4318'

exporters:
  logging:
    verbosity: detailed
  otlphttp:
    endpoint: "<YOU_OTEL_COLLECTOR_HTTP_ENDPOINT>"
    headers:
      authorization: <YOUR_INGESTION_API_KEY>
    compression: gzip

service:
  telemetry:
    logs:
      level: "debug"
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch, decouple]
      exporters: [otlphttp, logging]
    metrics:
      receivers: [otlp]
      processors: [batch, decouple]
      exporters: [otlphttp, logging]
    logs:
      receivers: [otlp]
      processors: [batch, decouple]
      exporters: [otlphttp, logging]