Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →
Socket
Sign inDemoInstall
Socket
Sign inDemoInstall

aws-xray-sdk

Package Overview
Dependencies
Maintainers
1
Versions
69
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

aws-xray-sdk - npm Package Compare versions

Comparing version 1.0.5-beta to 1.0.6-beta

aws-xray-sdk-1.0.6-beta.tgz

4

.eslintrc.json

@@ -23,4 +23,8 @@ {

"always"
],
"eol-last": [
"error",
"always"
]
}
}

13

CHANGELOG.md
# Changelog for AWS X-Ray SDK for JavaScript
<!--LATEST=1.0.5-beta-->
<!--LATEST=1.0.6-beta-->
<!--ENTRYINSERT-->
## 1.0.6-beta
* **BREAKING** change: added a `setContextMissingStrategy` function to the `AWSXRay` module. This allows configuration of the exception behavior exhibited when trace context is not properly propagated. The behavior can be configured in code. Alternatively, the environment variable `AWS_XRAY_CONTEXT_MISSING` can be used (overrides any modes set in code). Valid values for this environment variable are currently (case insensitive) `RUNTIME_ERROR` and `LOG_ERROR`. The default behavior is changing from `LOG_ERROR` to `RUNTIME_ERROR`, i.e. by default, an exception will be thrown on missing context.
* **BREAKING** change: Renamed the capture module's exported functions `capture`, `captureAsync`, and `captureCallback` to `captureFunc`, `captureAsyncFunc`, and `captureCallbackFunc`, respectively.
* change: Changed the behavior when loading multiple plugins to set the segment origin using the latest-loaded plugin.
* change: Removed the `Subsegment` `addRemote` setter. `Subsegment` namespaces can be set directly using the `namespace` attribute.
* change: Changed the name of the `Segment`/`Subsegment` `addThrottle` method to `addThrottleFlag`.
* change: Removed the `type` parameter from the `Segment`/`Subsegment` `addError` and `close` methods.
* feature: Added `addFaultFlag` and `addErrorFlag` methods to `Segment` and `Subsegment`.
* feature: Added additional version information to the `aws.xray` segment property.
* bugfix: Fixed issue where loading multiple plugins using `XRay.config` did not set all applicable data in the segment's `aws` attribute.
## 1.0.5-beta

@@ -6,0 +17,0 @@ * change: Changed the expected sampling file format. See README for details.

7

lib/index.js
// Convenience file to require the SDK from the root of the repository
module.exports = require('./aws-xray');
var AWSXRay = require('aws-xray-sdk-core');
AWSXRay.express = require('aws-xray-sdk-express');
AWSXRay.captureMySQL = require('aws-xray-sdk-mysql');
AWSXRay.capturePostgres = require('aws-xray-sdk-postgres');
module.exports = AWSXRay;

2

LICENSE.txt

@@ -51,2 +51,2 @@ Apache License

END OF TERMS AND CONDITIONS
END OF TERMS AND CONDITIONS

2

NOTICE.txt

@@ -1,2 +0,2 @@

AWS SDK for JavaScript
AWS X-Ray SDK for JavaScript
Copyright 2012-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved.

@@ -3,0 +3,0 @@

39

package.json
{
"name": "aws-xray-sdk",
"version": "1.0.5-beta",
"version": "1.0.6-beta",
"description": "AWS X-Ray SDK for Javascript",

@@ -13,34 +13,17 @@ "author": "Amazon Web Services",

},
"directories": {
"test": "test"
},
"dependencies": {
"continuation-local-storage": "^3.2.0",
"moment": "^2.15.2",
"pkginfo": "^0.4.0",
"semver": "^5.3.0",
"underscore": "^1.8.3",
"winston": "^2.2.0"
"aws-xray-sdk-core": "^1.0.0-beta",
"aws-xray-sdk-express": "^1.0.0-beta",
"aws-xray-sdk-mysql": "^1.0.0-beta",
"aws-xray-sdk-postgres": "^1.0.0-beta"
},
"devDependencies": {
"chai": "^3.5.0",
"eslint": "^3.10.2",
"grunt": "^1.0.1",
"grunt-contrib-clean": "^1.0.0",
"grunt-jsdoc": "^2.1.0",
"mocha": "^3.0.2",
"nock": "^8.0.0",
"sinon": "^1.17.5",
"sinon-chai": "^2.8.0"
},
"scripts": {
"test": "./node_modules/.bin/mocha --recursive ./test/ -R spec"
},
"keywords": [
"\"api\"",
"\"amazon\"",
"\"aws\"",
"\"xray\""
"amazon",
"api",
"aws",
"xray",
"x-ray",
"x ray"
],
"license": "Apache-2.0"
}

510

README.md

@@ -1,507 +0,31 @@

## Setup development environment
npm install
## Run tests
npm test
## Generate docs
grunt docs
## Requirements
AWS SDK v2.7.15 or greater.
AWS SDK v2.7.15 or greater (if using captureAWS or captureAWSClient)
Express 4.14.0 or greater (if using Express and the associated X-Ray middleware)
MySQL 2.12.0 or greater or greater (if using captureMySQL)
Postgres 6.1.0 or greater (if using capturePostgres)
## AWS X-Ray
AWS X-Ray automatically records information for incoming and outgoing requests and responses, as well as local data such as function calls, time,
variables (via metadata and annotations), even EC2 instance data. Currently only supports Express applications for auto capturing.
The AWS X-Ray SDK automatically records information for incoming and outgoing requests and responses (via middleware), as well as local data
such as function calls, time, variables (via metadata and annotations), even EC2 instance data (via plugins).
The AWS X-Ray SDK has two modes - Manual and CLS.
CLS mode uses the Continuation Local Storage package and automatically keeps track of the current segment and subsegment. This is the default mode.
Manual mode requires you pass around the segment reference.
Although the AWS X-Ray SDK was originally intended to capture request/response data on a web app, the SDK provides functionality for use cases
outside this as well. The SDK exposes the 'Segment' and 'Subsegment' objects to create your own capturing mechanisms, middleware, etc.
In CLS mode, you can get the current segment/subsegment at any time:
var segment = AWSXRay.getSegment();
This package includes all other AWS X-Ray packages.
In manual mode, you can get the base segment off the request object:
var segment = req.segment;
aws-xray-sdk-core
aws-xray-sdk-express
aws-xray-sdk-postgres
aws-xray-sdk-mysql
* In manual mode, you must pass along the reference to the current subsegment.
* If you are not using the express middleware, and you create your segment manually, you must close it with segment.close(<optional error>).
The SDK exposes the Segment and Subsegment objects to create your own capturing mechanisms, but a few are supplied.
These keep the current subsegment up to date automatically using CLS.
AWSXRay.capture - Takes a function that takes a single subsegment argument. This will create a new nested subsegment and expose it. The segment
will close automatically when the function completes executing. This will not correctly time functions with asynchronous calls, instead use
captureAsync.
AWSXRay.captureAsync - Takes a function that takes a single subsegment argument. This will create a new nested subsegment and expose it. The segment
must be closed manually using subsegment.close() or subsegment.close(error) when the asynchronous function completes.
AWSXRay.captureCallback - Takes a function to be used as a callback. Useful for capturing callback information and directly associate it to the call
that generated it. This will create a new nested subsegment and expose it by appending it onto the arguments used to call the callback. For this reason,
always call your captured callbacks with the full parameter list. The subsegment will close automatically when the function completes executing.
## Setup
### environment variables
The core package contains the base SDK functionality. Please see the aws-xray-sdk-core README.md for more details.
**Environment variables always override values set in code.**
### Support for web frameworks
AWS_XRAY_DEBUG_MODE Enables logging to console output. Logging to a file is no longer built in, see 'configure logging' below.
AWS_XRAY_TRACING_NAME For overriding the default segment name to be used with the middleware. See 'dynamic and fixed naming modes'.
XRAY_TRACING_NAME For overriding the default segment name to be used with the middleware. See 'dynamic and fixed naming modes'.
**This will be deprecated in favor of AWS_XRAY_TRACING_NAME for the GA release.
AWS_XRAY_DAEMON_ADDRESS For setting the daemon address and port. Expects 'x.x.x.x', ':yyyy' or 'x.x.x.x:yyyy' IPv4 formats.
POSTGRES_DATABASE_VERSION Sets additional data for the sql subsegment.
POSTGRES_DRIVER_VERSION Sets additional data for the sql subsegment.
MYSQL_DATABASE_VERSION Sets additional data for the sql subsegment.
MYSQL_DRIVER_VERSION Sets additional data for the sql subsegment.
### daemon configuration
By default, the SDK expects the daemon to be at 127.0.0.1 (localhost) on port 2000. You can override the address, port, or both.
This can be changed via the environment variables listed above, or through code. The same format is applicable for both.
AWSXRay.setDaemonAddress('186.34.0.23:8082');
AWSXRay.setDaemonAddress(':8082');
AWSXRay.setDaemonAddress('186.34.0.23');
### configure logging
Default logging to a file has been removed. To set up file logging, please configure a logger which responds to debug, info, warn and error functions.
To log information about configuration, make sure you set the logger before other configuration options.
AWSXRay.setLogger(logger);
### middleware
#### sampling configuration
A sampling rule defines the rate at which requests are sampled for a particular endpoint, HTTP method and URL of the incoming request.
In this way, you can change the behavior of sampling using http_method, service_name, url_path attributes to specify the route, then use
fixed_target and rate to determine sampling rates.
Fixed target refers to the maximum number of requests to sample per second. When this threshold has been reached, the sampling decision
will use the specified percentage (rate) to sample on.
The SDK comes with a default sampling file at /lib/resources/sampling_rules.js. You can choose to override this by providing one.
AWSXRay.middleware.setSamplingRules(<path to file>);
A sampling file must have a "default" defined. The default matches all routes as a fall-back, if none of the rules match.
{
"rules": [],
"default": {
"fixed_target": 10,
"rate": 0.05
},
"version": 1
}
Order of priority is determined by the spot in the rules array, top being highest priority. The default is always checked last.
Service name, URL path and HTTP method patterns are case insensitive, and use a string with wild cards as the pattern format.
A '*' represents any number of characters, while '?' represents a single character.
Description is optional.
{
"rules": [
{
"description": "Sign-in request",
"http_method": "GET",
"service_name": "*.foo.com",
"url_path": "/signin/*",
"fixed_target": 10,
"rate": 0.05
}
],
"default": {
"fixed_target": 10,
"rate": 0.05
},
"version": 1
}
#### dynamic and fixed naming modes
The SDK requires a default segment name to be set when using the middleware. If it is not set, an error will be
thrown. This value can be overridden via the AWS_XRAY_TRACING_NAME (or XRAY_TRACING_NAME) environment variable.
app.use(AWSXRay.express.openSegment('defaultName'));
The SDK defaults to a fixed naming mode. This means that each time a new segment is created for an incoming request,
the name of that segment is set to the default name.
In dynamic mode, the segment name can vary between the host header of the request or the default name.
AWSXRay.middleware.enableDynamicNaming(<pattern>);
If no pattern is provided, the host header is used as the segment name. If no host header is present, the default is used.
This is equivalent to using the pattern '*'.
If a pattern is provided, in the form of a string with wild cards (ex: '*.*.us-east-?.elasticbeanstalk.com') then the host header of the
request will be checked against it. A '*' represents any number of characters, while '?' represents a single character. If the host
header is present and matches this pattern, it is used as the segment name. Otherwise, the default name is used.
### partial subsegment streaming and the streaming threshold
By default, the SDK is configured to have a threshold of 100 subsegments per segment. This is because the UDP packet maximum size is ~65 kb, and
larger segments may trigger the 'Segment too large to send' error.
To remedy this, the SDK will automatically send the completed subsegments to the daemon when the threshold has been breached.
Additionally, subsegments that complete when over threshold automatically send themselves. If a subsegment is sent out-of-band, it
will be pruned from the segment object. The full segment will be reconstructed on the service-side. You can change the threshold as needed.
AWSXRay.setStreamingThreshold(10);
Subsegments may be marked as 'in_progress' when sent to the daemon. The SDK is telling the service to anticipate the asynchronous subsegment
to be received out-of-band when it has completed. When received, the in_progress subsegment will be discarded in favor of the completed subsegment.
### version capturing
Use the 'npm start' script to enable.
### capture all incoming HTTP requests to '/'
var app = express();
//...
var AWSXRay = require('aws-xray-sdk');
app.use(AWSXRay.express.openSegment('defaultName')); //required at the start of your routes
app.get('/', function (req, res) {
res.render('index');
});
app.use(AWSXRay.express.closeSegment()); //required at the end of your routes / first in error handling routes
### capture all outgoing AWS requests
var AWS = captureAWS(require('aws-sdk'));
//create new clients as per usual
//make sure any outgoing calls that are dependent on another async
//function are wrapped with captureAsync, otherwise duplicate segments may leak
//see usages for clients in manual and CLS modes
### configure AWSXRay to automatically capture EC2 instance data
var AWSXRay = require('aws-xray-sdk');
AWSXRay.config([AWSXRay.plugins.EC2]);
### add annotations
var key = 'hello';
var value = 'there'; // must be string, boolean or finite number
subsegment.addAnnotation(key, value);
### add metadata
var key = 'hello';
var value = 'there';
subsegment.addMetadata(key, value);
### create new subsegment
var newSubseg = subsegment.addNewSubsegment(name);
// or
var subsegment = new Subsegment(name);
## CLS Mode Examples
### capture all incoming HTTP requests to '/'
var app = express();
//...
var AWSXRay = require('aws-xray-sdk');
app.use(AWSXRay.express.openSegment('defaultName'));
app.get('/', function (req, res) {
res.render('index');
});
app.use(AWSXRay.express.closeSegment());
### capture through function calls
var AWSXRay = require('aws-xray-sdk');
app.use(AWSXRay.express.openSegment('defaultName'));
app.get('/', function (req, res) {
var host = 'samplego-env.us-east-1.elasticbeanstalk.com';
AWSXRay.captureAsync('send', function(seg) {
sendRequest(host, function() {
console.log("rendering!");
res.render('index');
seg.close();
});
});
});
app.use(AWSXRay.express.closeSegment());
function sendRequest(host, cb) {
var options = {
host: host,
path: '/',
};
var callback = function(response) {
var str = '';
response.on('data', function (chunk) {
str += chunk;
});
response.on('end', function () {
cb();
});
}
http.request(options, callback).end();
};
### capture outgoing AWS requests on a single client
var s3 = AWSXRay.captureAWSClient(new AWS.S3());
//use client as usual
//make sure any outgoing calls that are dependent on another async
//function are wrapped with captureAsync, otherwise duplicate segments may leak
### capture outgoing AWS requests on every AWS SDK client
var aws = AWSXRay.captureAWS(require('aws-sdk'));
//create new clients as per usual
//make sure any outgoing calls that are dependent on another async
//function are wrapped with captureAsync, otherwise duplicate segments may leak
### capture all outgoing HTTP/S requests
AWSXRay.captureHTTPs(http); //patching the http module will patch for https as well
var options = {
...
}
http.request(options, callback).end();
//create new requests as per usual
//make sure any outgoing calls that are dependent on another async
//function are wrapped with captureAsync, otherwise duplicate segments may leak
### capture PostgreSQL queries
var AWSXRay = require('aws-xray-sdk');
var pg = AWSXRay.capturePostgres(require('pg'));
...
var client = new pg.Client();
client.connect(function (err) {
...
client.query({name: 'moop', text: 'SELECT $1::text as name'}, ['brianc'], function (err, result) {
//automatically captures query information and error (if any)
});
});
...
var pool = new pg.Pool(config);
pool.connect(function(err, client, done) {
if(err) {
return console.error('error fetching client from pool', err);
}
var query = client.query('SELECT * FROM mytable', function(err, result) {
//automatically captures query information and error (if any)
});
});
### capture MySQL queries
var AWSXRay = require('aws-xray-sdk');
var mysql = AWSXRay.captureMySQL(require('mysql'));
var config = { ... };
...
var connection = mysql.createConnection(config);
connection.query('SELECT * FROM cats', function(err, rows) {
//automatically captures query information and error (if any)
});
...
var pool = mysql.createPool(config);
var segment = req.segment;
pool.query('SELECT * FROM cats', function(err, rows, fields) {
//automatically captures query information and error (if any)
}
## Manual Mode
Enable manual mode:
AWSXRay.enableManualMode();
### capture through function calls
var AWSXRay = require('aws-xray-sdk');
AWSXRay.enableManualMode();
app.use(AWSXRay.express.openSegment('defaultName'));
app.get('/', function (req, res) {
var segment = req.segment;
var host = 'samplego-env.us-east-1.elasticbeanstalk.com';
AWSXRay.captureAsync('send', function(seg) {
sendRequest(host, function() {
console.log("rendering!");
res.render('index');
seg.close();
});
}, segment);
});
app.use(AWSXRay.express.closeSegment());
function sendRequest(host, cb, segment) {
var options = {
host: host,
path: '/',
Segment: segment
};
var callback = function(response) {
var str = '';
//the whole response has been received, so we just print it out here
//another chunk of data has been received, so append it to `str`
response.on('data', function (chunk) {
str += chunk;
});
response.on('end', function () {
cb();
});
}
http.request(options, callback).end();
};
### capture outgoing AWS requests on a single client
var s3 = AWSXRay.captureAWSClient(new AWS.S3());
var params = {
Bucket: bucketName,
Key: keyName,
Body: 'Hello!',
Segment: subsegment //required "Segment" param
};
s3.putObject(params, function(err, data) {
...
});
### capture all outgoing AWS requests
var AWS = captureAWS(require('aws-sdk'));
//create new clients as per usual
//make sure any outgoing calls that are dependent on another async
//functions are wrapped, otherwise duplicate segments may leak.
### capture all outgoing HTTP/S requests
AWSXRay.captureHTTPs(http); //patching the http module will patch for https as well
...
//include segment/subsegment reference in options as 'Segment'
var options = {
...
Segment: subsegment
}
http.request(options, callback).end();
### capture PostgreSQL queries
var AWSXRay = require('aws-xray-sdk');
var pg = AWSXRay.capturePostgres(require('pg'));
...
var client = new pg.Client();
client.connect(function (err) {
...
client.query({name: 'moop', text: 'SELECT $1::text as name'}, ['mcmuls'], function (err, result) {
//automatically captures query information and error (if any)
});
});
...
var pool = new pg.Pool(config);
pool.connect(function(err, client, done) {
if(err) {
return console.error('error fetching client from pool', err);
}
var query = client.query('SELECT * FROM mytable', function(err, result) {
//automatically captures query information and error (if any)
}, segment));
};
### capture MySQL queries
var AWSXRay = require('aws-xray-sdk');
var mysql = AWSXRay.captureMySQL(require('mysql'));
var config = { ... };
...
var connection = mysql.createConnection(config);
connection.query('SELECT * FROM cats', function(err, rows) {
//automatically captures query information and error (if any)
});
...
var pool = mysql.createPool(config);
pool.query('SELECT * FROM cats', function(err, rows, fields) {
//automatically captures query information and error (if any)
}, segment);
A current list of supported web frameworks can be found at: http://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-nodejs-middleware.html
For more information, please see the aws-xray-sdk-express package README.md.
Gruntfile.js
lib/aws-xray.js
lib/capture.js
lib/logger.js
lib/middleware/express_mw.js
lib/middleware/mw_utils.js
lib/patchers/aws_p.js
lib/patchers/call_capturer.js
lib/patchers/http_p.js
lib/patchers/mysql_p.js
lib/patchers/postgres_p.js
lib/resources/aws_whitelist.json
lib/resources/default_sampling_rules.json
lib/sampling/sampler.js
lib/sampling/sampling_rules.js
lib/segment_emitter.js
lib/segments/attributes/aws.js
lib/segments/attributes/captured_exception.js
lib/segments/attributes/local.js
lib/segments/attributes/remote.js
lib/segments/attributes/sql_data.js
lib/segments/attributes/subsegment.js
lib/segments/plugins/beanstalk_plugin.js
lib/segments/plugins/ec2_plugin.js
lib/segments/plugins/ecs_plugin.js
lib/segments/plugins/plugin.js
lib/segments/segment_utils.js
lib/segments/segment.js
lib/utils.js
test/unit/aws-xray.test.js
test/unit/capture.test.js
test/unit/middleware/express_mw.test.js
test/unit/middleware/mw_utils.test.js
test/unit/patchers/aws_p.test.js
test/unit/patchers/call_capturer.test.js
test/unit/patchers/http_p.test.js
test/unit/patchers/mysql_p.test.js
test/unit/patchers/postgres_p.test.js
test/unit/sampling/sampler.test.js
test/unit/sampling/sampling_rules.test.js
test/unit/segment_emitter.test.js
test/unit/segments/attributes/aws.test.js
test/unit/segments/attributes/captured_exception.test.js
test/unit/segments/attributes/local.test.js
test/unit/segments/attributes/subsegment.test.js
test/unit/segments/plugins/beanstalk_plugin.test.js
test/unit/segments/plugins/ec2_plugin.test.js
test/unit/segments/plugins/ecs_plugin.test.js
test/unit/segments/plugins/plugin.test.js
test/unit/segments/segment_utils.test.js
test/unit/segments/segment.test.js
test/unit/test_utils.js
test/unit/utils.test.js
SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

About

Packages

npm

Go

Maven

PyPI

Rubygems

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc