Skip to content
This repository was archived by the owner on Nov 21, 2025. It is now read-only.

Commit 6e96bf4

Browse files
kjinkjin
authored
0.6.3 Release Proposal (#445)
PR-URL: #445
1 parent a75752e commit 6e96bf4

File tree

2 files changed

+8
-238
lines changed

2 files changed

+8
-238
lines changed

‎CHANGELOG.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,12 @@
11
# Node.js Agent for Google Cloud Trace ChangeLog
22

3+
## 2017-03-20, Version 0.6.3 (Deprecated), @kjin
4+
5+
This module has been renamed to [@google-cloud/trace-agent](https://www.npmjs.com/package/@google-cloud/trace-agent). No more releases will be made with the old
6+
module name.
7+
8+
The renamed module contains a number of semver-major changes, specifically in the custom span API. Please refer to the [changelog](https://github.com/GoogleCloudPlatform/cloud-trace-nodejs/blob/545c9ae118269b8bf95b1f97270cd0a308f376a1/CHANGELOG.md#2017-02-28-version-100-rc1-experimental-matthewloring) for the renamed module for a full summary of changes.
9+
310
## 2017-02-07, Version 0.6.2 (Experimental), @kjin
411

512
### Notable changes

‎README.md‎

Lines changed: 1 addition & 238 deletions
Original file line numberDiff line numberDiff line change
@@ -1,240 +1,3 @@
11
# Stackdriver Trace for Node.js
22

3-
[![NPM Version][npm-image]][npm-url]
4-
[![Build Status][travis-image]][travis-url]
5-
[![Test Coverage][coveralls-image]][coveralls-url]
6-
[![Dependency Status][david-image]][david-url]
7-
[![devDependency Status][david-dev-image]][david-dev-url]
8-
[![Known Vulnerabilities][snyk-image]][snyk-url]
9-
10-
> *This module is experimental, and should be used by early adopters. This module uses APIs that may be undocumented and subject to change without notice.*
11-
12-
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].
13-
14-
![Stackdriver Trace Overview](doc/images/cloud-trace-overview-page.png)
15-
16-
## Prerequisites
17-
18-
1. Your application will need to be using Node.js version 0.12 or greater.
19-
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.
20-
1. [Enable the Trace API](https://console.cloud.google.com/flows/enableapi?apiid=cloudtrace) for your project.
21-
22-
## Installation
23-
24-
1. Install with [`npm`](https://www.npmjs.com) or add to your [`package.json`](https://docs.npmjs.com/files/package.json#dependencies).
25-
26-
npm install --save @google/cloud-trace
27-
28-
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`:
29-
30-
"scripts": {
31-
"start": "GCLOUD_PROJECT=<YOUR_PROJECT_ID> node server.js",
32-
},
33-
34-
3. Include and start the library *as the very first action in your application*:
35-
36-
require('@google/cloud-trace').start();
37-
38-
If you use `--require` in your start up command, make sure that the trace agent is --required first.
39-
40-
4. If you are running your application locally, or on a machine where you are using the [Google Cloud SDK][gcloud-sdk], make sure to log in with the application default credentials:
41-
42-
gcloud beta auth application-default login
43-
44-
If you are running somewhere other than the Google Cloud Platform, see [running elsewhere](#running-elsewhere).
45-
46-
## Configuration
47-
48-
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:
49-
50-
require('@google/cloud-trace').start({samplingRate: 500});
51-
52-
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.
53-
54-
## Running on Google Cloud Platform
55-
56-
There are three different services that can host Node.js application to Google Cloud Platform.
57-
58-
### Google App Engine flexible environment
59-
60-
If you are using [Google App Engine flexible environment](https://cloud.google.com/appengine/docs/flexible/), you do not have to do any additional configuration.
61-
62-
### Google Compute Engine
63-
64-
Your VM instances need to be created with the `https://www.googleapis.com/auth/trace.append` scope if created via the [gcloud](https://cloud.google.com/sdk) CLI or the Google Cloud Platform API, or with the 'Allow API access' checkbox selected if created via the [console][cloud-console] (see screenshot).
65-
66-
![GCE API](doc/images/gce.png?raw=true)
67-
68-
If you already have VMs that were created without API access and do not wish to recreate it, you can follow the instructions for using a service account under [running elsewhere](#running-elsewhere).
69-
70-
### Google Container Engine
71-
72-
Container Engine nodes need to also be created with the `https://www.googleapis.com/auth/trace.append` scope, which is configurable during cluster creation. Alternatively, you can follow the instructions for using a service account under [running elsewhere](#running-elsewhere). It's recommended that you store the service account credentials as [Kubernetes Secret](http://kubernetes.io/v1.1/docs/user-guide/secrets.html).
73-
74-
## Running elsewhere
75-
76-
If your application is running outside of Google Cloud Platform, such as locally, on-premise, or on another cloud provider, you can still use Stackdriver Trace.
77-
78-
1. You will need to specify your project ID when starting the trace agent.
79-
80-
GCLOUD_PROJECT=particular-future-12345 node myapp.js
81-
82-
2. You need to provide service account credentials to your application. The recommended way is via [Application Default Credentials][app-default-credentials].
83-
84-
1. [Create a new JSON service account key][service-account].
85-
2. Copy the key somewhere your application can access it. Be sure not to expose the key publicly.
86-
3. Set the environment variable `GOOGLE_APPLICATION_CREDENTIALS` to the full path to the key. The trace agent will automatically look for this environment variable.
87-
88-
If you are running your application on a development machine or test environment where you are using the [`gcloud` command line tools][gcloud-sdk], and are logged using `gcloud beta auth application-default login`, you already have sufficient credentials, and a service account key is not required.
89-
90-
Alternatively, you may set the `keyFilename` or `credentials` configuration field to the full path or contents to the key file, respectively. Setting either of these fields will override either setting `GOOGLE_APPLICATION_CREDENTIALS` or logging in using `gcloud`. (See the [default configuration](config.js) for more details.)
91-
92-
## Viewing your traces
93-
94-
Run your application and start sending some requests towards your application. In about 30 seconds or so, you should see trace data gathered in the [STACKDRIVER -> Traces -> Trace List](https://console.cloud.google.com/traces/overview) in the console:
95-
96-
![Trace List](doc/images/tracelist.png?raw=true)
97-
98-
This is the trace list that shows a sampling of the incoming requests your application is receiving. You can click on a URI to drill down into the details. This will show you the RPCs made by your application and their associated latency:
99-
100-
![Trace View](doc/images/traceview.png?raw=true)
101-
102-
## What gets traced
103-
104-
The trace agent can do automatic tracing of HTTP requests when using these frameworks:
105-
* [express](https://www.npmjs.com/package/express) version 4
106-
* [hapi](https://www.npmjs.com/package/hapi) versions 8 - 16
107-
* [restify](https://www.npmjs.com/package/restify) versions 3 - 4 (experimental)
108-
109-
The agent will also automatic trace of the following kinds of RPCs:
110-
* Outbound HTTP requests
111-
* [MongoDB-core](https://www.npmjs.com/package/mongodb-core) version 1
112-
* [Mongoose](https://www.npmjs.com/package/mongoose) version 4
113-
* [Redis](https://www.npmjs.com/package/redis) versions 0.12 - 2
114-
* [MySQL](https://www.npmjs.com/package/mysql) version ^2.9
115-
116-
You can use the [Custom Tracing API](#custom-tracing-api) to trace other processes in your application.
117-
118-
We are working on expanding the types of frameworks and services we can do automatic tracing for. We are also interested in hearing your feedback on what other frameworks, or versions, you would like to see supported. This would help us prioritize support going forward. If you want support for a particular framework or RPC, please file a bug or +1 an existing bug.
119-
120-
## Advanced trace configuration
121-
122-
The trace agent can be configured by passing a configurations object to the agent `start` method. This configuration option accepts all values in the [default configuration](config.js).
123-
124-
One configuration option of note is `enhancedDatabaseReporting`. Setting this option to `true` will cause database operations for redis and MongoDB to record query summaries and results as labels on reported trace spans.
125-
126-
## Disabling the trace agent
127-
128-
The trace agent can be turned off by either setting the `GCLOUD_TRACE_DISABLE` environment variable or specifying `enabled: false` in your configuration file.
129-
130-
## Trace batching and sampling
131-
132-
The aggregation of trace spans before publishing can be configured using the `flushDelaySeconds` and `bufferSize` [options](config.js). The spans recorded for each incoming requests are placed in a buffer after the request has completed. Spans will be published to the UI in batch when the spans from `bufferSize` requests have been queued in the buffer or after `flushDelaySeconds` have passed since the last publish, whichever comes first.
133-
134-
The trace configuration additionally exposes the `samplingRate` option which sets an upper bound on the number of traced requests captured per second. Some Google Cloud environments may override this sampling policy.
135-
136-
## Custom Tracing API
137-
138-
The custom tracing API can be used to add custom spans to trace. A *span* is a particular unit of work within a trace, such as an RPC request. Spans may be nested; the outermost span is called a *root span*, even if there are no nested child spans. Root spans typically correspond to incoming requests, while *child spans* typically correspond to outgoing requests, or other work that is triggered in response to incoming requests.
139-
140-
For any of the web frameworks listed above (`express`, `hapi`, and `restify`), a root span is automatically started whenever an incoming request is received (in other words, all middleware already runs within a root span). If you wish to record a span outside of any of these frameworks, any traced code must run within a root span that you create yourself.
141-
142-
The API is exposed by the `agent` returned by a call to `start`:
143-
144-
```javascript
145-
var agent = require('@google/cloud-trace').start();
146-
```
147-
148-
For child spans, you can either use the `startSpan` and `endSpan` API, or use the `runInSpan` function that uses a callback-style. For root spans, you must use `runInRootSpan`.
149-
150-
### Start & end
151-
152-
To start a new child span, use `agent.startSpan`. Each span requires a name, and you can optionally specify labels.
153-
154-
```javascript
155-
var span = agent.startSpan('name', {label: 'value'});
156-
```
157-
158-
Once your work is complete, you can end a child span with `agent.endSpan`. You can again optionally associate labels with the span:
159-
160-
```javascript
161-
agent.endSpan(span, {label2: 'value'});
162-
```
163-
164-
Note that the labels parameter must be an object. Other types (e.g. string) will be silently ignored.
165-
166-
### Run in span
167-
168-
`agent.runInSpan` takes a function to execute inside a custom child span with the given name. The function may be synchronous or asynchronous. If it is asynchronous, it must accept a 'endSpan' function as an argument that should be called once the asynchronous work has completed.
169-
170-
```javascript
171-
agent.runInSpan('name', {label: 'value'}, function() {
172-
doSynchronousWork();
173-
});
174-
175-
agent.runInSpan('name', {label: 'value'}, function(endSpan) {
176-
doAsyncWork(function(result) {
177-
processResult(result);
178-
endSpan({label2: 'value'});
179-
});
180-
});
181-
```
182-
183-
### Run in root span
184-
185-
`agent.runInRootSpan` behaves similarly to `agent.runInSpan`, except that the function is run within a root span.
186-
187-
```javascript
188-
agent.runInRootSpan('name', {label: 'value'}, function() {
189-
// You can record child spans in here
190-
doSynchronousWork();
191-
});
192-
agent.runInRootSpan('name', {label: 'value'}, function(endSpan) {
193-
// You can record child spans in here
194-
doAsyncWork(function(result) {
195-
processResult(result);
196-
endSpan({label2: 'value'});
197-
});
198-
});
199-
```
200-
201-
### Changing trace properties
202-
203-
It is possible to rename and add labels to current trace. This can be used to give it a more meaningful name or add additional metadata.
204-
205-
By default we use the name of the express (or hapi/restify) route as the transaction name, but it can be changed using `agent.setTransactionName`:
206-
207-
```javascript
208-
agent.setTransactionName('new name');
209-
```
210-
211-
You can add additional labels using `agent.addTransactionLabel`:
212-
213-
```javascript
214-
agent.addTransactionLabel('label', 'value');
215-
```
216-
217-
## Contributing changes
218-
219-
* See [CONTRIBUTING.md](CONTRIBUTING.md)
220-
221-
## Licensing
222-
223-
* See [LICENSE](LICENSE)
224-
225-
[cloud-console]: https://console.cloud.google.com
226-
[gcloud-sdk]: https://cloud.google.com/sdk/gcloud/
227-
[app-default-credentials]: https://developers.google.com/identity/protocols/application-default-credentials
228-
[service-account]: https://console.developers.google.com/apis/credentials/serviceaccountkey
229-
[npm-image]: https://badge.fury.io/js/%40google%2Fcloud-trace.svg
230-
[npm-url]: https://npmjs.org/package/@google/cloud-trace
231-
[travis-image]: https://travis-ci.org/GoogleCloudPlatform/cloud-trace-nodejs.svg?branch=master
232-
[travis-url]: https://travis-ci.org/GoogleCloudPlatform/cloud-trace-nodejs
233-
[coveralls-image]: https://coveralls.io/repos/GoogleCloudPlatform/cloud-trace-nodejs/badge.svg?branch=master&service=github
234-
[coveralls-url]: https://coveralls.io/github/GoogleCloudPlatform/cloud-trace-nodejs?branch=master
235-
[david-image]: https://david-dm.org/GoogleCloudPlatform/cloud-trace-nodejs.svg
236-
[david-url]: https://david-dm.org/GoogleCloudPlatform/cloud-trace-nodejs
237-
[david-dev-image]: https://david-dm.org/GoogleCloudPlatform/cloud-trace-nodejs/dev-status.svg
238-
[david-dev-url]: https://david-dm.org/GoogleCloudPlatform/cloud-trace-nodejs?type=dev
239-
[snyk-image]: https://snyk.io/test/github/GoogleCloudPlatform/cloud-trace-nodejs/badge.svg
240-
[snyk-url]: https://snyk.io/test/github/GoogleCloudPlatform/cloud-trace-nodejs
3+
***This module has been renamed to [@google-cloud/trace-agent](https://www.npmjs.com/package/@google-cloud/trace-agent). Please use that module instead.***

0 commit comments

Comments
 (0)