├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.md ├── LICENSE ├── README.md ├── index.html ├── index.js ├── mysql-config.json └── package.json /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | ## Code of Conduct 2 | This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct). 3 | For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact 4 | opensource-codeofconduct@amazon.com with any additional questions or comments. 5 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing Guidelines 2 | 3 | Thank you for your interest in contributing to our project. Whether it's a bug report, new feature, correction, or additional 4 | documentation, we greatly value feedback and contributions from our community. 5 | 6 | Please read through this document before submitting any issues or pull requests to ensure we have all the necessary 7 | information to effectively respond to your bug report or contribution. 8 | 9 | 10 | ## Reporting Bugs/Feature Requests 11 | 12 | We welcome you to use the GitHub issue tracker to report bugs or suggest features. 13 | 14 | When filing an issue, please check existing open, or recently closed, issues to make sure somebody else hasn't already 15 | reported the issue. Please try to include as much information as you can. Details like these are incredibly useful: 16 | 17 | * A reproducible test case or series of steps 18 | * The version of our code being used 19 | * Any modifications you've made relevant to the bug 20 | * Anything unusual about your environment or deployment 21 | 22 | 23 | ## Contributing via Pull Requests 24 | Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that: 25 | 26 | 1. You are working against the latest source on the *master* branch. 27 | 2. You check existing open, and recently merged, pull requests to make sure someone else hasn't addressed the problem already. 28 | 3. You open an issue to discuss any significant work - we would hate for your time to be wasted. 29 | 30 | To send us a pull request, please: 31 | 32 | 1. Fork the repository. 33 | 2. Modify the source; please focus on the specific change you are contributing. If you also reformat all the code, it will be hard for us to focus on your change. 34 | 3. Ensure local tests pass. 35 | 4. Commit to your fork using clear commit messages. 36 | 5. Send us a pull request, answering any default questions in the pull request interface. 37 | 6. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation. 38 | 39 | GitHub provides additional document on [forking a repository](https://help.github.com/articles/fork-a-repo/) and 40 | [creating a pull request](https://help.github.com/articles/creating-a-pull-request/). 41 | 42 | 43 | ## Finding contributions to work on 44 | Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use the default GitHub issue labels (enhancement/bug/duplicate/help wanted/invalid/question/wontfix), looking at any 'help wanted' issues is a great place to start. 45 | 46 | 47 | ## Code of Conduct 48 | This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct). 49 | For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact 50 | opensource-codeofconduct@amazon.com with any additional questions or comments. 51 | 52 | 53 | ## Security issue notifications 54 | If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public github issue. 55 | 56 | 57 | ## Licensing 58 | 59 | See the [LICENSE](LICENSE) file for our project's licensing. We will ask you to confirm the licensing of your contribution. 60 | 61 | We may ask you to sign a [Contributor License Agreement (CLA)](http://en.wikipedia.org/wiki/Contributor_License_Agreement) for larger changes. 62 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. 2 | 3 | Permission is hereby granted, free of charge, to any person obtaining a copy of 4 | this software and associated documentation files (the "Software"), to deal in 5 | the Software without restriction, including without limitation the rights to 6 | use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of 7 | the Software, and to permit persons to whom the Software is furnished to do so. 8 | 9 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 10 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS 11 | FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR 12 | COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER 13 | IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 14 | CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 15 | 16 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # X-Ray SDK for Node.js Sample App 2 | This repository contains a sample web app built using express.js and instrumented with the X-Ray SDK for Node.js. It is intended to demonstrate the tracing capabilities of the SDK by running a local website that makes a variety of downstream requests. An HTTP downstream request, AWS SDK request, and MySQL query are demonstrated in the app. 3 | 4 | ## Prerequisites 5 | * [The X-Ray Daemon](https://docs.aws.amazon.com/xray/latest/devguide/xray-daemon.html) installed and running on your local machine 6 | * [NPM and Node 10+](https://nodejs.org/en/download/) installed 7 | 8 | ## Set Up 9 | 1. Clone this repo to your local machine 10 | 2. Navigate into the repository 11 | 3. Run `npm install` 12 | 4. Run `node index.js` to run the webapp on `localhost` 13 | 5. Go to `localhost:3000` in your browser of choice, and play around with the sample app! 14 | 15 | **NOTE:** the sample app uses the `us-west-2` region by default, but you can override that by setting the `AWS_DEFAULT_REGION` environment variable. 16 | 17 | ### Setting up MySQL Tracing Demo 18 | These steps are only necessary if you'd like to see the MySQL demo in the sample app. If you already have a MySQL environment set up, you can skip to step 4. 19 | 1. Set up a [MySQL server](https://www.mysqltutorial.org/install-mysql/) 20 | 2. Follow this [tutorial](https://www.mysqltutorial.org/mysql-create-database/) to create a MySQL database 21 | 3. Follow this [tutorial](https://www.mysqltutorial.org/mysql-create-table/) to create a table in that database 22 | 4. Populate `mysql-config.json` with the required information 23 | 5. Go to the sample app in your browser to experience the MySQL tracing demo! 24 | 25 | ## Getting Help 26 | Please consult the official [AWS Documentation](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-nodejs.html) for general questions about the X-Ray SDK for Node.js, and the [API reference](https://docs.aws.amazon.com/xray-sdk-for-nodejs/latest/reference/) for implementation-specific questions. If you notice an issue with this sample app, please [open an issue](https://github.com/aws-samples/aws-xray-sdk-node-sample/issues/new). If you notice an issue with the SDK itself, please [open an issue in its repository](https://github.com/aws/aws-xray-sdk-node/issues/new). 27 | 28 | ## License 29 | 30 | This library is licensed under the MIT-0 License. See the LICENSE file. 31 | -------------------------------------------------------------------------------- /index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | X-Ray SDK for Node.js 4 | 5 | 6 |

7 | Welcome to the sample app for the X-Ray SDK for Node.js! 8 |

9 |

View the traces generated with this sample app at any time in your X-Ray Console.

10 |

To see a traced AWS SDK request, go here.

11 |

To see a traced HTTP request, go here.

12 |

To see a traced MySQL query, go here. Ensure you've configured a database as described in the README.

13 | 14 | -------------------------------------------------------------------------------- /index.js: -------------------------------------------------------------------------------- 1 | const AWSXRay = require('aws-xray-sdk'); 2 | const XRayExpress = AWSXRay.express; 3 | const express = require('express'); 4 | 5 | // Capture all AWS clients we create 6 | const AWS = AWSXRay.captureAWS(require('aws-sdk')); 7 | AWS.config.update({region: process.env.DEFAULT_AWS_REGION || 'us-west-2'}); 8 | 9 | // Capture all outgoing https requests 10 | AWSXRay.captureHTTPsGlobal(require('https')); 11 | const https = require('https'); 12 | 13 | // Capture MySQL queries 14 | const mysql = AWSXRay.captureMySQL(require('mysql')); 15 | 16 | const app = express(); 17 | const port = 3000; 18 | 19 | app.use(XRayExpress.openSegment('SampleSite')); 20 | 21 | app.get('/', (req, res) => { 22 | const seg = AWSXRay.getSegment(); 23 | const sub = seg.addNewSubsegment('customSubsegment'); 24 | setTimeout(() => { 25 | sub.close(); 26 | res.sendFile(`${process.cwd()}/index.html`); 27 | }, 500); 28 | }); 29 | 30 | app.get('/aws-sdk/', (req, res) => { 31 | const ddb = new AWS.DynamoDB(); 32 | const ddbPromise = ddb.listTables().promise(); 33 | 34 | ddbPromise.then(function(data) { 35 | res.send(`ListTables result:\n ${JSON.stringify(data)}`); 36 | }).catch(function(err) { 37 | res.send(`Encountered error while calling ListTables: ${err}`); 38 | }); 39 | }); 40 | 41 | app.get('/http-request/', (req, res) => { 42 | const endpoint = 'https://amazon.com/'; 43 | https.get(endpoint, (response) => { 44 | response.on('data', () => {}); 45 | 46 | response.on('error', (err) => { 47 | res.send(`Encountered error while making HTTPS request: ${err}`); 48 | }); 49 | 50 | response.on('end', () => { 51 | res.send(`Successfully reached ${endpoint}.`); 52 | }); 53 | }); 54 | }); 55 | 56 | app.get('/mysql/', (req, res) => { 57 | const mysqlConfig = require('./mysql-config.json'); 58 | const config = mysqlConfig.config; 59 | const table = mysqlConfig.table; 60 | 61 | if (!config.user || !config.database || !config.password || !config.host || !table) { 62 | res.send('Please correctly populate mysql-config.json'); 63 | return; 64 | } 65 | 66 | const connection = mysql.createConnection(config); 67 | connection.query(`SELECT * FROM ${table}`, (err, results, fields) => { 68 | if (err) { 69 | res.send(`Encountered error while querying ${table}: ${err}`); 70 | return; 71 | } 72 | res.send(`Retrieved the following results from ${table}:\n${results}`); 73 | }); 74 | 75 | connection.end(); 76 | }); 77 | 78 | app.use(XRayExpress.closeSegment()); 79 | 80 | app.listen(port, () => console.log(`Example app listening on port ${port}!`)); 81 | -------------------------------------------------------------------------------- /mysql-config.json: -------------------------------------------------------------------------------- 1 | { 2 | "config": { 3 | "user": "", 4 | "database": "", 5 | "password": "", 6 | "host": "" 7 | }, 8 | "table": "" 9 | } -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "aws-xray-sdk-express-sample", 3 | "version": "1.0.0", 4 | "description": "Official Express sample application for the AWS X-Ray SDK for Node.js", 5 | "main": "index.js", 6 | "scripts": { 7 | "test": "echo \"Error: no test specified\" && exit 1" 8 | }, 9 | "keywords": [ 10 | "amazon", 11 | "aws", 12 | "sample", 13 | "xray", 14 | "x-ray", 15 | "x ray" 16 | ], 17 | "author": "Amazon Web Services", 18 | "contributors": [ 19 | "William Armiros " 20 | ], 21 | "license": "MIT-0", 22 | "dependencies": { 23 | "aws-sdk": "^2.657.0", 24 | "aws-xray-sdk": "^3.0.0", 25 | "express": "^4.17.1", 26 | "mysql": "^2.18.1" 27 | } 28 | } 29 | --------------------------------------------------------------------------------