diff --git a/.travis.yml b/.travis.yml index 53fb0471a..44d33682b 100644 --- a/.travis.yml +++ b/.travis.yml @@ -15,7 +15,7 @@ before_install: - mysql -e "create database IF NOT EXISTS test;" -uroot env: - - GCLOUD_PROJECT_NUM=0 CXX=g++-4.8 + - GCLOUD_PROJECT=0 CXX=g++-4.8 script: - ./bin/run-test.sh -c diff --git a/README.md b/README.md index 423075e50..a06376f3b 100644 --- a/README.md +++ b/README.md @@ -8,14 +8,14 @@ > *This module is experimental, and should be used by early adopters. This module uses APIs there may be undocumented and may be subject to change without notice.* -This module provides StackDriver Trace support for Node.js applications. [StackDriver Trace](https://cloud.google.com/cloud-trace/) is a feature of [Google Cloud Platform](https://cloud.google.com/) that collects latency data (traces) from your applications and displays it in near real-time in the [Google Cloud Console](https://console.cloud.google.com/?_ga=1.258049870.576536942.1443543237). +This module provides StackDriver Trace support for Node.js applications. [StackDriver Trace](https://cloud.google.com/cloud-trace/) is a feature of [Google Cloud Platform](https://cloud.google.com/) that collects latency data (traces) from your applications and displays it in near real-time in the [Google Cloud Console][cloud-console]. ![StackDriver Trace Overview](doc/images/cloud-trace-overview-page.png) ## Prerequisites 1. Your application will need to be using Node.js version 0.12 or greater. -1. You will need a project in the [Google Developers Console](https://console.cloud.google.com/project?_ga=1.258049870.576536942.1443543237). Your application can run anywhere, but the trace data is associated with a particular project. +1. You will need a project in the [Google Developers Console][cloud-console]. Your application can run anywhere, but the trace data is associated with a particular project. 1. [Enable the Trace API](https://console.cloud.google.com/flows/enableapi?apiid=cloudtrace) for your project. ## Installation @@ -24,17 +24,24 @@ This module provides StackDriver Trace support for Node.js applications. [StackD npm install --save @google/cloud-trace -2. Include and start the library at the *top of the main script of your application*. It's important that the trace agent is the first thing executed so that it can accurately gather data: +2. Set the GCLOUD_PROJECT environment variable. You can find your Project ID in the [Google Cloud Developers Console][cloud-console], or by running the command `gcloud projects list`. You can ensure this environment variable is set at startup time by placing it in your startup script in `package.json`: - require('@google/cloud-trace').start({projectId: 'your-project-id'}); + "scripts": { + "start": "GCLOUD_PROJECT= node server.js", + }, -Your project ID is visible in the [Google Cloud Console Console](https://console.cloud.google.com/project?_ga=1.258049870.576536942.1443543237), it may be something like `particular-future-12345`. If your application is [running on Google Cloud Platform](running-on-google-cloud-platform), you don't need to specify the project ID. +3. Include and start the library at the *as the very first action in your application*: + + require('@google/cloud-trace').start(); + +If you use `--require` in your start up command, make sure that the trace agent is --required first. +If you are running somewhere other than the Google Cloud Platform, see [running elsewhere](#running-elsewhere). ## Configuration See [the default configuration](config.js) for a list of possible configuration options. These options can be passed to the agent through the object argument to the start command shown above: - require('@google/cloud-trace').start({projectId: 'your-project-id', samplingRate: 500}); + require('@google/cloud-trace').start({samplingRate: 500}); Alternatively, you can provide configuration through a config file. This can be useful if you want to load our module using `--require` on the command line instead of editing your main script. You can start by copying the default config file and modifying it to suit your needs. The `GCLOUD_DIAGNOSTICS_CONFIG` environment variable should point to your configuration file. @@ -48,7 +55,7 @@ If you are using [Google App Engine flexible environment](https://cloud.google.c ### Google Compute Engine -Your VM instances need to be created with `cloud-platform` scope if created via [gcloud](https://cloud.google.com/sdk) or the 'Allow API access' checkbox selected if created via the [console](https://console.cloud.google.com) (see screenshot). +Your VM instances need to be created with `cloud-platform` scope if created via [gcloud](https://cloud.google.com/sdk) or the 'Allow API access' checkbox selected if created via the [console][cloud-console] (see screenshot). ![GCE API](doc/images/gce.png?raw=true) @@ -64,7 +71,7 @@ If your application is running outside of Google Cloud Platform, such as locally 1. You will need to specify your project ID when starting the trace agent. - require('@google/cloud-trace').start({projectId: 'your-project-id'}); + GCLOUD_PROJECT=particular-future-12345 node myapp.js 2. You will need to provide service account credentials to your application. The recommended way is via [Application Default Credentials](https://developers.google.com/identity/protocols/application-default-credentials). These can be provisioned by executing the following command: @@ -177,7 +184,7 @@ You can add additional labels using `agent.addTransactionLabel`: * See [LICENSE](LICENSE) - +[cloud-console]: https://console.cloud.google.com [npm-image]: https://badge.fury.io/js/%40google%2Fcloud-trace.svg [npm-url]: https://npmjs.org/package/@google/cloud-trace [travis-image]: https://travis-ci.org/GoogleCloudPlatform/cloud-trace-nodejs.svg?branch=master diff --git a/index.js b/index.js index 29bafa6ca..5c846edeb 100644 --- a/index.js +++ b/index.js @@ -80,8 +80,8 @@ var initConfig = function(projectConfig) { if (process.env.hasOwnProperty('GCLOUD_TRACE_DISABLE')) { config.enabled = false; } - if (process.env.hasOwnProperty('GCLOUD_PROJECT_NUM')) { - config.projectId = process.env.GCLOUD_PROJECT_NUM; + if (process.env.hasOwnProperty('GCLOUD_PROJECT')) { + config.projectId = process.env.GCLOUD_PROJECT; } return config; }; diff --git a/test/hooks/common.js b/test/hooks/common.js index 501b17a56..7a04c6eb1 100644 --- a/test/hooks/common.js +++ b/test/hooks/common.js @@ -15,8 +15,8 @@ */ 'use strict'; -if (!process.env.GCLOUD_PROJECT_NUM) { - console.log('The GCLOUD_PROJECT_NUM environment variable must be set.'); +if (!process.env.GCLOUD_PROJECT) { + console.log('The GCLOUD_PROJECT environment variable must be set.'); process.exit(1); } diff --git a/test/non-interference/express-e2e.js b/test/non-interference/express-e2e.js index 7b5eb25a8..d0ca930ee 100644 --- a/test/non-interference/express-e2e.js +++ b/test/non-interference/express-e2e.js @@ -26,11 +26,11 @@ var semver = require('semver'); var SUPPORTED_VERSIONS = '<4.x'; if (process.argv.length === 4 && process.argv[2] === '-p') { - process.env.GCLOUD_PROJECT_NUM = process.argv[3]; + process.env.GCLOUD_PROJECT = process.argv[3]; } -if (!process.env.GCLOUD_PROJECT_NUM) { +if (!process.env.GCLOUD_PROJECT) { console.log('Project number must be provided with the -p flag or' + - ' the GCLOUD_PROJECT_NUM environment variable must be set.'); + ' the GCLOUD_PROJECT environment variable must be set.'); process.exit(1); } if (!semver.satisfies(process.version, SUPPORTED_VERSIONS)) { diff --git a/test/non-interference/http-e2e.js b/test/non-interference/http-e2e.js index 0fe9a4737..fa372078b 100644 --- a/test/non-interference/http-e2e.js +++ b/test/non-interference/http-e2e.js @@ -25,11 +25,11 @@ var tmp = require('tmp'); var semver = require('semver'); if (process.argv.length === 4 && process.argv[2] === '-p') { - process.env.GCLOUD_PROJECT_NUM = process.argv[3]; + process.env.GCLOUD_PROJECT = process.argv[3]; } -if (!process.env.GCLOUD_PROJECT_NUM) { +if (!process.env.GCLOUD_PROJECT) { console.log('Project number must be provided with the -p flag or' + - ' the GCLOUD_PROJECT_NUM environment variable must be set.'); + ' the GCLOUD_PROJECT environment variable must be set.'); process.exit(1); } diff --git a/test/non-interference/mongo-e2e.js b/test/non-interference/mongo-e2e.js index 63f67c163..c86a4d11c 100644 --- a/test/non-interference/mongo-e2e.js +++ b/test/non-interference/mongo-e2e.js @@ -22,11 +22,11 @@ var path = require('path'); var tmp = require('tmp'); if (process.argv.length === 4 && process.argv[2] === '-p') { - process.env.GCLOUD_PROJECT_NUM = process.argv[3]; + process.env.GCLOUD_PROJECT = process.argv[3]; } -if (!process.env.GCLOUD_PROJECT_NUM) { +if (!process.env.GCLOUD_PROJECT) { console.log('Project number must be provided with the -p flag or' + - ' the GCLOUD_PROJECT_NUM environment variable must be set.'); + ' the GCLOUD_PROJECT environment variable must be set.'); process.exit(1); } @@ -48,7 +48,7 @@ glob('google-cloud-trace-*.tgz', function(err, files) { build.on('close', function(code) { if (!code) { var test = cp.spawn('docker', ['run', '-w', '/mongo', '-t', 'test', 'node', - 'test/runner.js', '-e', 'GCLOUD_PROJECT_NUM=' + process.env.GCLOUD_PROJECT_NUM, + 'test/runner.js', '-e', 'GCLOUD_PROJECT=' + process.env.GCLOUD_PROJECT, '-t', 'functional']); test.stdout.on('data', function(data) { console.log(data.toString()); }); test.stderr.on('data', function(data) { console.log(data.toString()); }); diff --git a/test/non-interference/restify-e2e.js b/test/non-interference/restify-e2e.js index 28e2faaec..32da6af84 100644 --- a/test/non-interference/restify-e2e.js +++ b/test/non-interference/restify-e2e.js @@ -26,11 +26,11 @@ var semver = require('semver'); var SUPPORTED_VERSIONS = '<4.x'; if (process.argv.length === 4 && process.argv[2] === '-p') { - process.env.GCLOUD_PROJECT_NUM = process.argv[3]; + process.env.GCLOUD_PROJECT = process.argv[3]; } -if (!process.env.GCLOUD_PROJECT_NUM) { +if (!process.env.GCLOUD_PROJECT) { console.log('Project number must be provided with the -p flag or' + - ' the GCLOUD_PROJECT_NUM environment variable must be set.'); + ' the GCLOUD_PROJECT environment variable must be set.'); process.exit(1); } if (!semver.satisfies(process.version, SUPPORTED_VERSIONS)) { diff --git a/test/standalone/test-agent-metadata.js b/test/standalone/test-agent-metadata.js index c74a4c210..c7b4fa28f 100644 --- a/test/standalone/test-agent-metadata.js +++ b/test/standalone/test-agent-metadata.js @@ -23,7 +23,7 @@ var traceLabels = require('../../lib/trace-labels.js'); nock.disableNetConnect(); -delete process.env.GCLOUD_PROJECT_NUM; +delete process.env.GCLOUD_PROJECT; describe('agent interaction with metadata service', function() { @@ -69,9 +69,9 @@ describe('agent interaction with metadata service', function() { it('should not query metadata service when env. var. is set', function() { nock.disableNetConnect(); - process.env.GCLOUD_PROJECT_NUM=0; + process.env.GCLOUD_PROJECT=0; agent.start({logLevel: 0}); - delete process.env.GCLOUD_PROJECT_NUM; + delete process.env.GCLOUD_PROJECT; }); it('should attach hostname to spans when provided', function(done) { diff --git a/test/standalone/test-agent-stopped.js b/test/standalone/test-agent-stopped.js index e9cf94588..be7d77486 100644 --- a/test/standalone/test-agent-stopped.js +++ b/test/standalone/test-agent-stopped.js @@ -19,7 +19,7 @@ var assert = require('assert'); var http = require('http'); -process.env.GCLOUD_PROJECT_NUM = 0; +process.env.GCLOUD_PROJECT = 0; describe('express', function() { it('should not break if no project number is found', function(done) { diff --git a/test/standalone/test-env-project-id.js b/test/standalone/test-env-project-id.js index 27b82ea10..784525a30 100644 --- a/test/standalone/test-env-project-id.js +++ b/test/standalone/test-env-project-id.js @@ -16,13 +16,13 @@ 'use strict'; -process.env.GCLOUD_PROJECT_NUM = 1729; +process.env.GCLOUD_PROJECT = 1729; var assert = require('assert'); var agent = require('../..'); describe('should respect environment variables', function() { - it('should respect GCLOUD_PROJECT_NUM', function() { + it('should respect GCLOUD_PROJECT', function() { agent.start(); assert.equal(agent.private_().config_.projectId, 1729); agent.stop(); diff --git a/test/standalone/test-hooks-no-project-num.js b/test/standalone/test-hooks-no-project-num.js index c0da3726a..0c1ebd81b 100644 --- a/test/standalone/test-hooks-no-project-num.js +++ b/test/standalone/test-hooks-no-project-num.js @@ -15,7 +15,7 @@ */ 'use strict'; -delete process.env.GCLOUD_PROJECT_NUM; +delete process.env.GCLOUD_PROJECT; var assert = require('assert'); diff --git a/test/standalone/test-index.js b/test/standalone/test-index.js index bdcada765..23bf91d0a 100644 --- a/test/standalone/test-index.js +++ b/test/standalone/test-index.js @@ -16,8 +16,8 @@ 'use strict'; -if (!process.env.GCLOUD_PROJECT_NUM) { - console.log('The GCLOUD_PROJECT_NUM environment variable must be set.'); +if (!process.env.GCLOUD_PROJECT) { + console.log('The GCLOUD_PROJECT environment variable must be set.'); process.exit(1); } diff --git a/test/standalone/test-invalid-project-id.js b/test/standalone/test-invalid-project-id.js index 782bdcbfc..8d0a2f492 100644 --- a/test/standalone/test-invalid-project-id.js +++ b/test/standalone/test-invalid-project-id.js @@ -16,7 +16,7 @@ 'use strict'; -delete process.env.GCLOUD_PROJECT_NUM; +delete process.env.GCLOUD_PROJECT; var assert = require('assert'); var agent = require('../..'); diff --git a/test/standalone/test-no-self-tracing.js b/test/standalone/test-no-self-tracing.js index db175d730..02b6d8a45 100644 --- a/test/standalone/test-no-self-tracing.js +++ b/test/standalone/test-no-self-tracing.js @@ -29,7 +29,7 @@ nock.disableNetConnect(); describe('test-no-self-tracing', function() { it('should not trace metadata queries', function(done) { - delete process.env.GCLOUD_PROJECT_NUM; + delete process.env.GCLOUD_PROJECT; var scope = nock('http://metadata.google.internal') .get('/computeMetadata/v1/instance/hostname').reply(200) .get('/computeMetadata/v1/instance/id').reply(200) @@ -47,7 +47,7 @@ describe('test-no-self-tracing', function() { }); it('should not trace publishes', function(done) { - process.env.GCLOUD_PROJECT_NUM = 0; + process.env.GCLOUD_PROJECT = 0; var metadataScope = nock('http://metadata.google.internal') .get('/computeMetadata/v1/instance/hostname').reply(200) .get('/computeMetadata/v1/instance/id').reply(200); diff --git a/test/standalone/test-trace-writer.js b/test/standalone/test-trace-writer.js index 73dd4a9e2..acfe45954 100644 --- a/test/standalone/test-trace-writer.js +++ b/test/standalone/test-trace-writer.js @@ -27,7 +27,7 @@ nock.disableNetConnect(); var uri = 'https://cloudtrace.googleapis.com'; var path = '/v1/projects/0/traces'; -process.env.GCLOUD_PROJECT_NUM = 0; +process.env.GCLOUD_PROJECT = 0; var queueSpans = function(n, privateAgent) { for (var i = 0; i < n; i++) { diff --git a/test/test-span-data.js b/test/test-span-data.js index 74e790759..f5cff43a1 100644 --- a/test/test-span-data.js +++ b/test/test-span-data.js @@ -16,8 +16,8 @@ 'use strict'; -if (!process.env.GCLOUD_PROJECT_NUM) { - console.log('The GCLOUD_PROJECT_NUM environment variable must be set.'); +if (!process.env.GCLOUD_PROJECT) { + console.log('The GCLOUD_PROJECT environment variable must be set.'); process.exit(1); } diff --git a/test/test-trace-agent.js b/test/test-trace-agent.js index f79406c9e..861e6555a 100644 --- a/test/test-trace-agent.js +++ b/test/test-trace-agent.js @@ -18,8 +18,8 @@ var constants = require('../lib/constants.js'); -if (!process.env.GCLOUD_PROJECT_NUM) { - console.log('The GCLOUD_PROJECT_NUM environment variable must be set.'); +if (!process.env.GCLOUD_PROJECT) { + console.log('The GCLOUD_PROJECT environment variable must be set.'); process.exit(1); }