AWS X-Ray

L'intégration Datadog/AWS Lambda X-Ray est uniquement prise en charge sur les comptes AWS commerciaux. Sans compte commercial, l'intégration Datadog/AWS Lambda X-Ray ne peut pas être utilisée sur le site gouvernemental de Datadog.

Présentation

AWS X-Ray permet aux développeurs de tracer des applications distribuées qui ont été créées à l’aide de produits AWS. Cette intégration fournit des traces pour les fonctions Lambda dans la page de détails des fonctions sans serveur. Pour en savoir plus, consultez la documentation relative à la surveillance sans serveur.

Configuration

Installation

Pour commencer, activez l’intégration AWS et assurez-vous que le document de stratégie de votre rôle AWS/Datadog comporte les autorisations suivantes :

xray:BatchGetTraces,
xray:GetTraceSummaries

L’autorisation GetTraceSummaries permet d’obtenir la liste des traces récentes, tandis que BatchGetTraces renvoie la totalité des traces.

Ensuite, activez l’intégration X-Ray dans Datadog.

Si vous utilisez une Customer Master Key (CMK) pour chiffrer les traces, ajoutez la méthode kms:Decrypt à la stratégie au sein de laquelle la ressource correspond à la CMK utilisée pour X-Ray.

Remarque : l’activation de l’intégration AWS X-Ray augmente le nombre de spans indexées. Cela peut avoir une incidence sur votre facturation.

Activer AWS X-Ray pour vos fonctions

Pour tirer le meilleur parti de l’intégration AWS X-Ray, activez-la sur vos fonctions Lambda et vos instances d’API Gateway, et installez également les bibliothèques de tracing dans vos fonctions Lambda.

Plug-in Serverless Framework

Le plug-in Serverless Framework de Datadog active automatiquement X-Ray pour vos fonctions Lambda et vos instances d’API Gateway. Il se charge également d’ajouter la couche Lambda Datadog à toutes vos fonctions Node et Python.

Pour apprendre à utiliser le plug-in Serverless Framework, lisez cet article de blog et consultez la documentation (en anglais).

Enfin, installez et importez la bibliothèque client X-Ray dans votre fonction Lambda.

Configuration manuelle

  1. Accédez à la fonction Lambda dans la console AWS que vous souhaitez instrumenter. Dans la section « Debugging and error handling », cochez la case Enable active tracing afin d’activer X-Ray pour cette fonction.
  2. Accédez à la console API Gateway. Sélectionnez votre API ainsi que l’étape. Depuis l’onglet Logs/Tracing, sélectionnez ensuite Enable X-Ray Tracing. Pour que ces changements prennent effet, accédez à Resources dans le volet de navigation sur la gauche et sélectionnez Actions, puis cliquez sur Deploy API.

Remarque : la couche Lambda Datadog et les bibliothèques client intègrent le X-Ray SDK en tant que dépendance. Vous n’avez donc pas besoin de l’installer dans vos projets.

Enfin, installez et importez la bibliothèque client X-Ray dans votre fonction Lambda.

Enrichir des segments X-Ray avec les bibliothèques Lambda de Datadog (facultatif)

Remarque : cette fonctionnalité est uniquement prise en charge pour les fonctions AWS Lambda écrites en Node.js ou Python.

Les bibliothèques Lambda de Datadog permettent d’ajouter des métadonnées supplémentaires aux segments X-Ray. Ces métadonnées sont alors consultables dans les traces de l’APM et dans la vue Serverless. Pour instrumenter vos fonctions Lambda avec les bibliothèques Lambda de Datadog, consultez les instructions détaillées pour chaque runtime et outil de déploiement ou suivez les instructions d’installation personnalisées ci-dessous :

Fonctions Lambda Python

  • Importez la bibliothèque Lambda de Datadog en tant que couche ou package en suivant les instructions détaillées.
  • Définissez le gestionnaire de votre fonction sur datadog_lambda.handler.handler.
  • Définissez la variable d’environnement DD_LAMBDA_HANDLER sur votre gestionnaire d’origine, comme myfunc.handler.
  • (Facultatif) Si vous n’utilisez pas la fusion de traces, définissez la variable d’environnement DD_TRACE_ENABLED sur false.

Fonctions Lambda Node

  • Importez la bibliothèque Lambda de Datadog en tant que couche ou package en suivant les instructions détaillées.
  • Définissez le gestionnaire de votre fonction sur /opt/nodejs/node_modules/datadog-lambda-js/handler.handler si vous utilisez la couche, ou sur node_modules/datadog-lambda-js/dist/handler.handler si vous utilisez le package.
  • Définissez la variable d’environnement DD_LAMBDA_HANDLER sur votre gestionnaire d’origine, comme myfunc.handler.
  • (Facultatif) Si vous n’utilisez pas la fusion de traces, définissez la variable d’environnement DD_TRACE_ENABLED sur false.

Installer les bibliothèques client X-Ray

La bibliothèque client X-Ray vous permet d’analyser vos requêtes HTTP envoyées aux API ainsi que les appels des services DynamoDB, S3, MySQL et PostgreSQL (auto-hébergé, Amazon RDS et Amazon Aurora), SQS et SNS.

Installez la bibliothèque, importez-la dans vos projets Lambda, puis patchez les services que vous souhaitez instrumenter.

Installer la bibliothèque de tracing X-Ray :


npm install aws-xray-sdk

# pour les utilisateurs de Yarn
yarn add aws-xray-sdk

Pour instrumenter le SDK AWS :

var AWSXRay = require('aws-xray-sdk-core');
var AWS = AWSXRay.captureAWS(require('aws-sdk'));

Pour instrumenter tous les appels HTTP et HTTPS en aval :

var AWSXRay = require('aws-xray-sdk');
AWSXRay.captureHTTPsGlobal(require('http'));
AWSXRay.captureHTTPsGlobal(require('https'));
var http = require('http');

Pour instrumenter les requêtes PostgreSQL :

var AWSXRay = require('aws-xray-sdk');
var pg = AWSXRay.capturePostgres(require('pg'));
var client = new pg.Client();

Pour instrumenter les requêtes MySQL :

var AWSXRay = require('aws-xray-sdk');
var mysql = AWSXRay.captureMySQL(require('mysql'));
//...
var connection = mysql.createConnection(config);

Pour capturer les sous-segments dans la promesse native chaînée :

AWSXRay.capturePromise();

Pour capturer toutes les requêtes Axios sortantes :

const AWSXRay = require('aws-xray-sdk');

AWSXRay.captureHTTPsGlobal(require('http'));
AWSXRay.capturePromise();

const AxiosWithXray = require('axios');

Pour en savoir plus sur la configuration, la création de sous-segments et l’enregistrement d’annotations, consultez la documentation X-Ray pour Node.js.

Installer la bibliothèque de tracing X-Ray :

pip install aws-xray-sdk

Pour patcher toutes les bibliothèques par défaut, ajoutez ce qui suit au fichier contenant vos gestionnaires de fonctions Lambda :

from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.core import patch_all
patch_all()

Remarque: le tracing de aiohttp nécessite une instrumentation spécifique.

Pour en savoir plus sur la configuration, la création de sous-segments et l’enregistrement d’annotations, consultez la documentation X-Ray pour Python.

Pour tout autre runtime, consultez la documentation sur X-Ray SDK :

Données collectées

L’intégration AWS X-Ray récupère les données de trace d’AWS et ne recueille aucune métrique ni aucun log.