Trace sua função Java do Lambda com New Relic e OpenTelemetry

Este guia abordará como você pode usar OpenTelemetry Lambda para trace sua função Java do Lambda usando OpenTelemetry Lambda Layers gerenciados pela AWS. OpenTelemetry facilita a instrumentação de suas funções, incluindo instrumentação automática para muitas bibliotecas populares.

Pré-requisitos

Este guia pressupõe que você tenha o seguinte:

• Uma conta New Relic . Se você não tiver um, crie um gratuitamente.
• Uma conta AWS. Se você não tiver um, crie um gratuitamente.
• Uma função Java do Lambda em execução nos tempos de execução java8.al2 ou java11 . Se você ainda não tem um, crie um agora.

Etapa 1: ativar o raio-X

Mesmo que não estejamos usando o AWS X-Ray nesta configuração, ainda precisamos habilitar o X-Ray na função do Lambda para habilitar o recurso de rastreamento integrado ao AWS OpenDistro.

Para ativar o Raio X:

1. Abra sua função no Console do Lambda.
2. Escolha Configuration e depois Monitoring Tools.
3. Escolha Edit.
4. Em X-Ray, ative Active tracing.

Alternativamente, se você estiver usando modelos SAM (Serverless aplicativo Model) ou CloudFormation , você pode habilitar o X-Ray adicionando o seguinte às propriedades da sua função do Lambda:

yourFunctionHere:
  Type: AWS::Serverless::Function
  Properties:
    # ...
    Policies:
      - AWSLambdaBasicExecutionRole
      # ...
      - AWSXrayWriteOnlyAccess
    Tracing: Active

Passo 2: Instale a camada

AWS publica uma camada gerenciada que inclui o coletorOpenTelemetry Lambda, o OpenTelemetry Java SDK e o agente automático de instrumentação ADOT.

Para instalá-lo:

1. Abra sua função no Console do Lambda.

2. Em Layers na seção Designer , escolha Add a layer.

3. Em Specify an ARN, cole um dos ARNs da camada para a arquitetura da sua função na lista abaixo. Substitua {region}pela sua região da AWS, como us-east-1.

4. Escolha Add.

   • AMD64/X86_64: arn:aws:lambda:{region}:901920570463:layer:aws-otel-java-agent-amd64-ver-1-11-1:1
   • ARM64: arn:aws:lambda:{region}:901920570463:layer:aws-otel-java-agent-arm64-ver-1-11-1:1

Para modelos SAM ou CloudFormation, adicione isto às propriedades da sua função:

yourFunctionHere:
  Type: AWS::Serverless::Function
  Properties:
    # ...
    Layers:
      # Use this if using x86_64 architecture
      - !Sub arn:${AWS::Partition}:lambda:${AWS::Region}:901920570463:layer:aws-otel-java-agent-amd64-ver-1-11-1:1
      # Use this if using arm64 architecture
      - !Sub arn:${AWS::Partition}:lambda:${AWS::Region}:901920570463:layer:aws-otel-java-agent-arm64-ver-1-11-1:1

Etapa 3: configurar a camada

Para configurar a camada precisamos configurar um wrapper exec. O wrapper exec é um script executado durante a inicialização da função. Neste caso, o script configura o OpenTelemetry.

1. Abra sua função no Console do Lambda.

2. Escolha Configuration e depois Environment variables.

3. Em Environment variables, escolha Edit.

4. Escolha Add environment variable.

5. Para Key defina-o como AWS_LAMBDA_EXEC_WRAPPER e defina Value como uma das opções a seguir (depende do tipo de manipulador). Em seguida, escolha Save.

   • /opt/otel-handler: para agrupar manipuladores regulares (implementando RequestHandler)
   • /opt/otel-proxy-handler: para agrupar manipuladores regulares (implementando RequestHandler) com proxy por meio do API Gateway, permitindo a propagação de contexto HTTP
   • /opt/otel-stream-handler: para agrupar manipuladores de streaming (implementando RequestStreamHandler), permitindo a propagação de contexto HTTP para solicitações HTTP

Para modelos SAM ou CloudFormation, adicione isto às propriedades da sua função:

yourFunctionHere:
  Type: AWS::Serverless::Function
  Properties:
    # ...
    Environment:
      Variables:
        AWS_LAMBDA_EXEC_WRAPPER: /opt/otel-handler

Etapa 4: adicionar variáveis de ambiente do New Relic

Para enviar os dados OpenTelemetry que esta camada coleta para o New Relic, precisamos configurar o coletor OpenTelemetry Lambda que é empacotado com a camada para exportar a telemetria que recebe para o endpointOpenTelemetry do New Relic. Antes de fazermos isso, primeiro precisamos definir algumas variáveis de ambiente das quais dependerá.

1. Gere e copie uma New Relic chave de licençada sua conta New Relic.

2. Abra sua função no Lambda Console.

3. Escolha Configuration e depois Environment variables.

4. Em Environment variables, escolha Edit.

5. Escolha Add environment variable.

6. Para Key defina-o como NEW_RELIC_LICENSE_KEY e defina Value como o valor da chave de licença gerada na etapa 1. Em seguida, escolha Save.

7. Escolha Add environment variable novamente.

8. Para Key defina-o como NEW_RELIC_OPENTELEMETRY_ENDPOINT e defina Value como uma das opções abaixo (depende da sua região do New Relic). Em seguida, escolha Save.

   • otlp.nr-data.net:4317: Se sua conta New Relic estiver na região dos EUA
   • otlp.eu01.nr-data.net:4317: Se a sua conta New Relic estiver na região da UE

Para modelos SAM e CloudFormation, adicione o seguinte às propriedades da sua função. Certifique-se de substituir your-license-key-here por seu chave de licençae otlp.nr-data.net:4317 pelo endpoint New Relic OpenTelemetry para sua região.

yourFunctionHere:
  Type: AWS::Serverless::Function
  Properties:
    # ...
    Environment:
      Variables:
        # ...
        NEW_RELIC_LICENSE_KEY: your-license-key-here
        NEW_RELIC_OPENTELEMETRY_ENDPOINT: otlp.nr-data.net:4317

Etapa 5: Configurar o coletor

Agora, substituiremos a OpenTelemetry configuração padrão do coletor Lambda por uma que exporte a telemetria para o New Relic OpenTelemetry endpoint. Para fazer isso, precisamos incluir um arquivo de configuração collector.yaml com nossa função.

Crie um arquivo collector.yaml no diretório raiz da sua função com o seguinte conteúdo:

receivers:
  otlp:
    protocols:
      grpc:
      http:

exporters:
  otlp:
    endpoint: ${NEW_RELIC_OPENTELEMETRY_ENDPOINT}
    headers:
      api-key: ${NEW_RELIC_LICENSE_KEY}

service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [otlp]
    metrics:
      receivers: [otlp]
      exporters: [otlp]
    logs:
      receivers: [otlp]
      exporters: [otlp]

Agrupe esse arquivo collector.yaml no diretório raiz do pacote zip da sua função e reimplante-o.

1. Abra sua função no Console do Lambda.
2. Escolha Configuration e depois Environment variables.
3. Em Environment variables, escolha Edit.
4. Escolha Add environment variable.
5. Para Key defina OPENTELEMETRY_COLLECTOR_CONFIG_FILE e defina Value como /var/task/collector.yaml.
6. Em seguida, escolha Save.

Para modelos SAM e CloudFormation, adicione isto às propriedades da sua função:

yourFunctionHere:
  Type: AWS::Serverless::Function
  Properties:
    # ...
    Environment:
      Variables:
        # ...
        OPENTELEMETRY_COLLECTOR_CONFIG_FILE: /var/task/collector.yaml

Etapa 6: visualize seus dados na interface do New Relic [view-data]

Primeiro você vai querer invocar sua função do Lambda algumas vezes para começar a gerar telemetria. A partir daí, vá para New Relic para encontrar seu trace, métrica e log.

Sua telemetria não aparecerá no New Relic Serverless. Em vez disso, você encontrará seus dados de telemetria nos New Relic OpenTelemetry Nerdlets.

Sobrecarga automática de instrumentação

O agente de instrumentação automática ADOT Lambda Layer para Java tem um impacto notável no tempo de inicialização no AWS Lambda, e geralmente você precisará usar isso junto com a simultaneidade provisionada para atender solicitações de produção sem causar tempos limite nas solicitações iniciais durante a inicialização. Recomendamos testar primeiro esta configuração em um ambiente não produção para determinar as configurações apropriadas para seu caso de uso.

Alternativamente, você pode usar o seguinte método de instrumentação manual. Por padrão, a instrumentação manual requer menos recursos na inicialização da função. No entanto, este método requer uma alteração de código na maioria dos casos.

Instrumentação manual

O método de instrumentação manual é semelhante ao procedimento de instrumentação automática neste documento. A única diferença é o ARN da camada Lambda que você especifica na etapa 1.

Para instrumentação manual, em vez de usar os ARNs de camada na Etapa 2, use um dos ARNs de camada na lista abaixo para a arquitetura da sua função:

• AMD64/X86_64: arn:aws:lambda:{region}:901920570463:layer:aws-otel-java-wrapper-amd64-ver-1-11-1:1
• ARM64: arn:aws:lambda:{region}:901920570463:layer:aws-otel-java-wrapper-arm64-ver-1-11-1:1

Substitua {region} pela sua região da AWS, como us-east-1.

Todas as outras etapas permanecem as mesmas.

Esta camada Lambda alternativa ainda envolverá sua função do Lambda como o método automático. Também instrumentará o AWS SDK automaticamente. Mas todas as outras bibliotecas que você usa exigirão que você inclua a biblioteca de instrumentação OpenTelemetry da biblioteca do repositório de instrumentação OpenTelemetry na dependência da sua função e modifique seu código para inicializá-lo.

Você pode ver um exemplo com OKHttp no GitHub.

Distributed tracing

Em alguns casos, você poderá ver rastreamento distribuído fragmentado no New Relic com esta configuração. Isso ocorre quando um trace inicia ou envolve um serviço que está fora do contexto ADOT (por exemplo, um serviço gerenciado da AWS). Os spans desse serviço são criados pelo X-Ray, não pelo OpenTelemetry, e o ADOT não os encaminha para o New Relic. Embora o rastreamento pareça fragmentado, eles ainda fornecem insights completos sobre o desempenho dentro da função do Lambda, bem como de outros serviços cujos spans foram encaminhados para a New Relic.

Mais Informações

Para obter mais informações, confira o início rápido do New Relic OpenTelemetry.