Node.js Serverless Tracer API

This page describes how to fine-tune your configuration with the Node.js Serverless Tracer API.

Create or Modify Exit Calls

If your function uses ES6 or includes exit calls other than HTTP or inter-AWS lambda calls, you need to create an exit call.

The following code snippet demonstrates how to create an exit call for an AWS Lambda function that calls a MySQL database:

// Use the exit call API in your AWS Lambda handler function
 
module.exports.myLambdaHandler = async function () {
  const queryPromise = new Promise(function (resolve, reject) {
    const dbConfig = {
      host: '127.0.0.1', // The host where MySQL server runs
      port: 3306, // Note that this is not an identifying property. Identifying properties must be strings
      user: 'root',
      database: 'movies'
    };
    const mysql = require('mysql');
    const mysqlClient = mysql.createPool(dbConfig);
    mysqlClient.getConnection(function (err, connection) {
      if (err) {
        reject({
          statusCode: 500,
          body: 'Couldn\'t make the connection to mysql client.'
        });
        return;
      }
      // Create an Exit Call
      var exitCall = tracer.startExitCall({
        exitType: 'DB',
        exitSubType: 'DB',
        identifyingProperties: {
          'HOST': '127.0.0.1', // The host where MySQL server runs
          'PORT': '3306', 
          'DATABASE': 'movies',
          'VENDOR': 'MYSQL'
        }
      });
      connection.query('SELECT * FROM ClassicHits', function (err, results) {
        connection.release();
        if (err) {
          reject({
            statusCode: 500,
            body: 'Mysql query failed'
          });
          return;
        }
 
		// Stop the Exit Call
        tracer.stopExitCall(exitCall);
        resolve({
          statusCode: 200,
          body: JSON.stringify(results)
        });
      });
    });
  });
  return queryPromise;
}

JS

Exit Call Types and Identifying Properties

Each exit call in the Controller has a distinct type determined by a set of identifying properties. The exit call types, subtypes, and identifying properties are listed below. For exit call subtypes, you can use the examples in the table or an empty string. Identifying properties must be strings.

Exit Call Type	Exit Call Subtype	Identifying Properties
HTTP	HTTP	`HOST` `PORT` `URL` `QUERY STRING`
DB	DB	`URL` `HOST` `PORT` `DATABASE` `VERSION` `VENDOR`
CACHE	CACHE	`VENDOR` `SERVER POOL`
CUSTOM	CASSANDRA CQL COUCHBASE AMAZON WEB SERVICES MONGODB	Any user-defined set of properties.

The following interceptors are supported and do not require manual instrumentation in CommonJS:

aws_sdk for lambda.invoke and lambda.invokeAsync
http and https libraries

Transaction Correlation through API-defined Exits

If you manually create an exit call for the Node.js Serverless Tracer, you need to locate the correlation header. This is required if your function does not use HTTP or inter-AWS Lambda exit calls.

The code snippet below demonstrates how you can create the correlation header:

module.exports.myLambdaHandler = function () {
    // Start Exit Call
    var exitCall = tracer.startExitCall({
      // Fill in with the exit call information
    });

    //Get your correlation header
    if (exitCall) {
        var correlationHeader = tracer.createCorrelationInfo(exitCall);
    }

    /*
     * Your exit call code. 
     * Pass the correlation header in the exit call for downstream correlation.
     */

    // Stop the exit call
    if (exitCall) {
        tracer.stopExitCall(exitCall);
    }
}

JS

Transaction Error Reports

By default, exceptions are automatically detected by the tracer. If your business logic defines the transaction as "in error" for any other reason, you can customize the error report method to mark the transaction in error.

The following code snippet demonstrates how to create a transaction error report:

// Transaction Error Report
module.exports.apiTransactionErrorReport = function(event, context, callback) {
  setTimeout(function () {
    tracer.reportTransactionError(new Error('API Error'));
    callback(null, {
      statusCode: 200,
      body: 'Transaction Error Reported'
    });
  }, 100);
}

JS

Exit Call Error Reports

By default, the tracer automatically discovers exit calls passed over HTTP or inter-AWS Lambda calls. Use the reportExitCallError method to report errors and exceptions that occur during exit call execution.

The following code snippet demonstrates how to create an exit call error report:

// Use the Exit Call API in your AWS Lambda handler function
  
module.exports.myLambdaHandler = async function () {
  const queryPromise = new Promise(function (resolve, reject) {
    const dbConfig = {
      host: '127.0.0.1', // The host where your MySQL server runs
      port: 3306, // Note that this is not an identifying property. Identifying properties must be strings
      user: 'root',
      database: 'movies'
    };
    const mysql = require('mysql');
    const mysqlClient = mysql.createPool(dbConfig);
    mysqlClient.getConnection(function (err, connection) {
      if (err) {
        reject({
          statusCode: 500,
          body: 'Couldn\'t make the connection to mysql client.'
        });
        return;
      }
      // Create an Exit Call
      var exitCall = tracer.startExitCall({
        exitType: 'DB',
        exitSubType: 'DB',
        identifyingProperties: {
          'HOST': '127.0.0.1', // The host where your MySQL server runs
          'PORT': '3306',
          'DATABASE': 'movies',
          'VENDOR': 'MYSQL'
        }
      });
      connection.query('SELECT * FROM ClassicHits', function (err, results) {
        connection.release();
 
		//Create an Exit Call error report
        if (err) {
          tracer.reportExitCallError(exitCall, 'MYSql error', 'Failed in making the query');
          reject({
            statusCode: 500,
            body: 'Mysql query failed'
          });
          return;
        }
        resolve({
          statusCode: 200,
          body: JSON.stringify(results)
        });
      });
    });
  });
  return queryPromise;
}

JS

Override the Tracer's Default Behavior

If you prefer to customize the function/business transaction names or keep the tracer settings in your source code, override the environment variables to retrieve values at runtime from any desired source.

The following code snippet demonstrates how to override the default behavior of the tracer:

tracer.init({
  controllerHostName: 'controllerHost',
  controllerPort: 8080,
  accountAccessKey: 'controllerAccountAccessKey',
  accountName: 'controllerAccountName',
  applicationName: 'applicationName',
  tierName: 'tierName',
  serverlessApiEndpoint: 'serverlessApiEndpoint',
  proxyHost: 'proxyHost',
  proxyPort: '80',
  proxyUser: 'proxyUser',
  proxyPassword: 'proxyPassword',
  certificateFile: 'proxyCertFile',
  debug: true
});

JS

_{Amazon Web Services, the AWS logo, AWS, and any other AWS Marks used in these materials are trademarks of}_Amazon.com_{, Inc. or its affiliates in the United States and/or other countries.}