This module implements experimental support for Google Cloud Trace for Node.js. This module is under development and is not suitable for production use at this point.
This module uses APIs there are undocumented and are not covered by any deprecation policy, and this may be subject to change without notice.
The API this module exports is experimental and is not covered by any deprecation policy, and may be changed without notice.
Prerequisites:
- You should already be familiar with deploying Node.js apps you to the Google Cloud Platform (GCP). See https://cloud.google.com/nodejs/ for getting started with deploying Node.js apps on GCP.
- You need to have created a project on GCP. You don't necessarily have to deploy your app to GCP, but traces must be attributed to a project to be viewed.
- You are using / deploying-with Node.js version 0.12 or greater.
Enable the Trace API for your project.
Install the trace agent module:
npm install --save @google/cloud-trace
Load the module as the very first thing that gets done at the startup of your application:
// Activate Google cloud trace agent (*must be first line of the app*)
require('@google/cloud-trace').start();Deploy your application to Google Cloud and send some requests towards your app.
In about 30 seconds or so, you should see trace data gathered in the Monitoring -> Traces view in your Google Cloud console:
Note: When you open on up the traces view under the monitoring header, you may see a warning saying traces are disabled (shown below). This refers to traces gathered by the app server responsible for hosting your application. These traces are gathered independently of the traces generated by our agent and carry less semantic information about the behavior of your application. We recommend you DO NOT click Enable trace at this time.
If you want to run your application locally, you will need to take two additional steps:
- Provide your project-number at the time you start the trace agent. Your project number can be found in the developer console by clicking gear in the upper left hand corner and looking at Project information:
// Activate Google cloud trace agent (*must be first line of the app*)
require('@google/cloud-trace').start({projectId: 'your-project-number-here'});- Provide credentials to authenticate with the Trace API.
- Provide credentials via the environment variable GOOGLE_APPLICATION_CREDENTIALS. The simplest way to get a credential for this purpose is to create a service account using the Google Developers Console in the section APIs & Auth, in the sub-section Credentials. Create a service account (Create New ClientID under the OAuth heading) or choose an existing one and select Generate new JSON key. Set the environment variable GOOGLE_APPLICATION_CREDENTIALS to the path of the JSON file downloaded.
The trace agent can do automatic tracing of the following http frameworks:
- express v4+
- restify v3+ (experimental)
- hapi v8 (experimental)
We will do automatic tracing of the following kinds of RPCs performed by your application:
- Outbound HTTP requests
- MongoDB v2+ (experimental)
- Redis v0.12+ (experimental)
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.
We also have an API that lets you add custom spans to the traces automatically. This can be useful if your application does sizable synchronous or asynchronous work that is not using an existing IO or RPC module.
Ensure that compute instances have been created with project API access and the follow the directions above:
If your compute engine instance has already been created and was not granted project API access, follow the steps above for running locally to authenticate using a service account key.
Our goal is for the trace agent to automatically trace all the popular Node.js web frameworks, as well as RPC and persistence layers. However, you may still want to create custom spans to add additional details if your application does sizable on- or off-CPU work inside a request. We do provide an API to enable that.
We only support custom spans inside existing top-level request-handling framework (e.g. express, hapi, etc.).
The API for creating custom spans and modifying transaction metadata is exposed through the agent returned by requiring the module:
var agent = require('@google/cloud-trace').start();Starting a new custom span. This command optionally takes an object of key value pairs which specify labels to be attached to the span:
var opaque = agent.startSpan('name', {key: 'my value'});Ending a custom span. This command optionally takes an object of key value pairs which specify labels to be attached to the span:
agent.endSpan(opaque, {key: 'my value'});Alternatively, we also support a mocha-style interface that might be a bit more convenient to use. The runInSpan method takes a function to execute inside a custom span with the provided 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.
agent.runInSpan('name', {key: 'my value'}, function() {
doSynchronousWork();
});
agent.runInSpan('name', {key: 'my value'}, function(endSpan) {
doAsyncWork(function(result) {
processResult(result);
endSpan({key2: 'my value2'});
});
});It is possible to rename the current top-level request transaction, to give it a more meaningful name. By default we use the name of the express (or hapi/restify) route as the transaction name:
agent.setTransactionName('new name');Adding a label to the current top-level request transaction:
agent.addTransactionLabel('label-key', 'label-value');-
Can I view details of traces from Google Cloud REST services (such as Cloud Datastore, etc.)? While this does not work yet, we plan to display traces from Google Cloud services as children of the transactions in your application which invoke these services.
-
Where are these /_ah/health and /_ah/background spans displaying in the UI coming from? See: https://cloud.google.com/appengine/docs/managed-vms/config#health_checking