tracez votre fonction Java Lambda avec New Relic et OpenTelemetry

Ce guide explique comment utiliser OpenTelemetry Lambda pour trace votre fonction Java Lambda à l'aide des couches OpenTelemetry Lambda gérées par AWS. OpenTelemetry facilite l'instrumentation de vos fonctions, y compris l'instrumentation automatique pour de nombreuses bibliothèques populaires.

Prérequis

Ce guide suppose que vous disposez des éléments suivants :

• Un compte New Relic. Si vous n'en avez pas, créez-en un gratuitement.
• Un compte AWS. Si vous n'en avez pas, créez-en un gratuitement.
• Une fonction Java Lambda exécutée sous les environnements d'exécution java8.al2 ou java11. Si vous n'en avez pas encore, créez-en un maintenant.

(Facultatif) Activer X-Ray

Même si nous n'utilisons pas AWS X-Ray dans cette configuration, nous devons toujours activer X-Ray dans la fonction Lambda pour activer la fonctionnalité de tracing intégrée à AWS OpenDistro.

Pour activer X-ray :

1. Ouvrez votre fonction dans la console Lambda.
2. Choisissez Configuration, puis Monitoring Tools.
3. Choisissez Edit.
4. Sous X-Ray, activez Active tracing.

Alternativement, si vous utilisez des modèles SAM (Serverless Application Model) ou CloudFormation , vous pouvez activer X-Ray en ajoutant ce qui suit aux propriétés de votre fonction Lambda :

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

Étape 1 : Installer la couche

AWS publie une couche gérée qui inclut OpenTelemetry Lambda Collector,OpenTelemetry Java SDK et l'agent d'auto-instrumentation ADOT.

Pour l'installer :

1. Ouvrez votre fonction dans la console Lambda.

2. Sous Layers dans la section Designer , choisissez Add a layer.

3. Sous Specify an ARN, collez l'un des ARN de couche pour l'architecture de votre fonction dans la liste ci-dessous. Remplacez {region}par votre région AWS, par exemple us-east-1.

4. Choisissez 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

Pour les modèles SAM ou CloudFormation, ajoutez ceci aux propriétés de votre fonction :

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

Étape 2 : Configurer la couche

Pour configurer la couche, nous devons configurer un wrapper exécutable. Le wrapper exec est un script qui s'exécute lors de l'initialisation de la fonction. Dans ce cas, le script configure OpenTelemetry.

1. Ouvrez votre fonction dans la console Lambda.

2. Choisissez Configuration puis Environment variables.

3. Sous Environment variables, choisissez Edit.

4. Choisissez Add environment variable.

5. Pour le Key définissez-le sur AWS_LAMBDA_EXEC_WRAPPER et définissez le Value sur l’une des options suivantes (selon votre type de gestionnaire). Choisissez ensuite Save.

   • /opt/otel-handler: pour encapsuler des gestionnaires réguliers (implémentation de RequestHandler)
   • /opt/otel-proxy-handler: pour encapsuler les gestionnaires réguliers (implémentant RequestHandler) transmis par proxy via API Gateway, permettant la propagation du contexte HTTP
   • /opt/otel-stream-handler: pour encapsuler les gestionnaires de streaming (implémentation de RequestStreamHandler), permettant la propagation HTTP du contexte pour requestsHTTP

Pour les modèles SAM ou CloudFormation, ajoutez ceci aux propriétés de votre fonction :

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

Étape 3 : Ajouter des variables d’environnement New Relic

Pour envoyer les OpenTelemetry données que cette couche collecte à New Relic, nous devons configurer le OpenTelemetry Lambda Collector fourni avec la couche pour exporter la télémétrie qu'il reçoit vers le point de terminaison de New Relic OpenTelemetry . Avant de faire cela, nous devons d’abord définir certaines variables d’environnement dont cela dépendra.

1. Générez et copiez une New Relic clé de licenceà partir de votre compte New Relic.

2. Ouvrez votre fonction dans la console Lambda.

3. Choisissez Configuration puis Environment variables.

4. Sous Environment variables, choisissez Edit.

5. Choisissez Add environment variable.

6. Pour le Key définissez-le sur NEW_RELIC_LICENSE_KEY et définissez le Value sur la valeur de la clé de licence que vous avez générée à l'étape 1. Choisissez ensuite Save.

7. Choisissez à nouveau Add environment variable .

8. Pour le Key définissez-le sur NEW_RELIC_OPENTELEMETRY_ENDPOINT et définissez le Value sur l'une des options ci-dessous (dépend de votre région New Relic). Choisissez ensuite Save.

   • otlp.nr-data.net:4317:Si votre compte New Relic se trouve dans la région des États-Unis
   • otlp.eu01.nr-data.net:4317:Si votre compte New Relic se trouve dans la région UE

Pour les modèles SAM et CloudFormation, ajoutez les éléments suivants aux propriétés de votre fonction. Assurez-vous de remplacer your-license-key-here par votre clé de licenceet otlp.nr-data.net:4317 par le point de terminaison New Relic OpenTelemetry pour votre région.

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

Étape 4 : Configurer le Collector

Nous allons maintenant remplacer la OpenTelemetry Lambda Collector par défaut du configuration par une configuration qui exporte la télémétrie vers le OpenTelemetry point de terminaison New Relic . Pour ce faire, nous devons inclure un fichier de configuration collector.yaml avec notre fonction.

Créez un fichier collector.yaml dans le répertoire racine de votre fonction avec le contenu suivant :

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]

Regroupez ce fichier collector.yaml dans le répertoire racine du package zip de votre fonction et redéployez-le.

1. Ouvrez votre fonction dans la console Lambda.
2. Choisissez Configuration puis Environment variables.
3. Sous Environment variables, choisissez Edit.
4. Choisissez Add environment variable.
5. Pour le Key définissez OPENTELEMETRY_COLLECTOR_CONFIG_FILE et définissez le Value sur /var/task/collector.yaml.
6. Choisissez ensuite Save.

Pour les modèles SAM et CloudFormation, ajoutez ceci aux propriétés de votre fonction :

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

Étape 5 : Affichez vos données dans l'interface utilisateur de New Relic [view-data]

Tout d’abord, vous souhaiterez appeler votre fonction Lambda plusieurs fois pour commencer à générer de la télémétrie. De là, rendez-vous sur New Relic pour trouver votre trace, vos métriques et votre log.

Votre télémétrie n'apparaîtra pas sous New Relic Serverless. Au lieu de cela, vous trouverez vos données télémétriques sous les Nerdlets New Relic OpenTelemetry .

Instrumentation automatique au-dessus de la tête

L'agent d'ADOT Lambda Layer pour Java auto-instrumentation a un impact notable sur le temps de démarrage sur AWS Lambda, et vous devrez généralement l'utiliser avec la simultanéité provisionnée pour répondre de production requests sans provoquer de délais d'attente sur requests initiales pendant son initialisation. Nous vous recommandons de tester d’abord cette configuration dans un environnement hors production afin de déterminer les paramètres appropriés à votre cas d’utilisation.

Alternativement, vous pouvez utiliser la méthode d’instrumentation manuelle suivante. Par défaut, l’instrumentation manuelle nécessite moins de ressources lors de l’initialisation de la fonction. Cependant, cette méthode nécessite une modification de code dans la plupart des cas.

Instrumentation manuelle

La méthode d’instrumentation manuelle est similaire à la procédure d’instrumentation automatique décrite dans ce document. La seule différence est l’ARN de la couche Lambda que vous spécifiez à l’étape 1.

Pour l'instrumentation manuelle, au lieu d'utiliser les ARN de couche de l'étape 2, utilisez l'un des ARN de couche de la liste ci-dessous pour l'architecture de votre fonction :

• 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

Remplacez {region} par votre région AWS, par exemple us-east-1.

Toutes les autres étapes restent les mêmes.

Cette couche Lambda alternative enveloppera toujours votre fonction Lambda comme la méthode automatique. Il instrumentera également automatiquement le SDK AWS . Mais toutes les autres bibliothèques que vous utiliserez nécessiteront que vous incluiez la bibliothèque d'instrumentation OpenTelemetry du référentiel d'instrumentation OpenTelemetry dans la dépendance de votre fonction et que vous modifiiez votre code pour l'initialiser.

Vous pouvez voir un exemple avec OKHttp sur GitHub.

Tracing distribué

Dans certains cas, vous pouvez voir des traces distribuées fragmentées dans New Relic avec cette configuration. Cela se produit lorsqu'une trace démarre ou implique un service qui est en dehors du contexte ADOT (par exemple, un service géré AWS). Les portées de ce service sont créées par X-Ray, et non par OpenTelemetry, et ADOT ne les transmet pas à New Relic. Bien que les traces semblent fragmentées, elles fournissent néanmoins des informations complètes détaillées sur les performances au sein de la fonction Lambda ainsi que d'autres services dont les traces ont été transmises à New Relic.

Plus d'informations

Pour plus d'informations, consultez le démarrage rapide de New Relic OpenTelemetry.