Stackdriver Trace Agent for Node.js
Beta. This is a Beta release of the Stackdriver Trace agent for Node.js. These libraries might be changed in backward-incompatible ways and are not subject to any SLA or deprecation policy.
This module provides automatic tracing for Node.js applications with Stackdriver Trace. Stackdriver Trace is a feature of Google Cloud Platform that collects latency data (traces) from your applications and displays it in near real-time in the Google Cloud Console.
The Trace Agent supports Node 4+.
Note: Using the Trace Agent requires a Google Cloud Project with the Stackdriver Trace API enabled and associated credentials. These values are auto-detected if the application is running on Google Cloud Platform. If your application is not running on GCP, you will need to specify the project ID and credentials either through the configuration object, or with environment variables. See Setting Up Stackdriver Trace for Node.js for more details.
Note: The Trace Agent does not currently work out-of-the-box with Google Cloud Functions (or Firebase Cloud Functions). See #725 for a tracking issue and details on how to work around this.
Simply require and start the Trace Agent as the first module in your application:
Optionally, you can pass a configuration object to the
start() function as follows:
startsamplingRate: 500 // sample one trace every half-second.ignoreUrls: /^\/ignore-me#/ // ignore the "/ignore-me" endpoint.;// ...
The object returned by
start() may be used to create custom trace spans:
const traceApi = start;traceApi;
What gets traced
The trace agent can do automatic tracing of the following web frameworks:
- express (version 4)
- gRPC server (version ^1.1)
- hapi (versions 8 - 16)
- koa (version 1)
- restify (versions 3 - 6)
The agent will also automatically trace RPCs from the following modules:
- Outbound HTTP requests through
- grpc client (version ^1.1)
- mongodb-core (version 1 - 3)
- mongoose (version 4 - 5)
- mysql (version ^2.9)
- mysql2 (version 1)
- pg (versions 6 - 7)
- redis (versions 0.12 - 2)
You can use the Custom Tracing API to trace other modules in your application.
Tracing Additional Modules
To load an additional plugin, specify it in the agent's configuration:
startplugins:// You may use a package name or absolute path to the file.'my-module': '@google-cloud/trace-agent-plugin-my-module''another-module': path;
This list of plugins will be merged with the list of built-in plugins, which will be loaded by the plugin loader. Each plugin is only loaded when the module that it patches is loaded; in other words, there is no computational overhead for listing plugins for unused modules.
Custom Tracing API
The custom tracing API can be used to create custom trace spans. 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.
For any of the web frameworks for which we provide built-in plugins, 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.
Accessing the API
start function returns an instance of
TraceApi, which provides an interface for tracing:
const traceApi = start;
It can also be retrieved by subsequent calls to
// after start() is calledconst traceApi = ;
TraceApi object is guaranteed to be returned by both of these calls, even if the agent is disabled.
A fully detailed overview of the
TraceApi object is available here.
How does automatic tracing work?
The Trace Agent automatically patches well-known modules to insert calls to functions that start, label, and end spans to measure latency of RPCs (such as mysql, redis, etc.) and incoming requests (such as express, hapi, etc.). As each RPC is typically performed on behalf of an incoming request, we must make sure that this association is accurately reflected in span data. To provide a uniform, generalized way of keeping track of which RPC belongs to which incoming request, we rely on the
continuation-local-storage module to keep track of the "trace context" across asynchronous boundaries.
continuation-local-storage, which relies on
async-listener to preserve continuations over asynchronous boundaries, works great in most cases. However, it does have some limitations that can prevent us from being able to properly propagate trace context:
- Presently, it is not possible for
async-listenerto keep track of transitions across
await-ed lines in ES7
asyncfunctions that are available with Node 7.6+. If your application uses untranspiled
asyncfunctions, we will not be properly track RPCs.
Starting in module version 2.2, the Trace Agent ships with an experimental implementation (using the Node 8
async_hooks API) that supports
await. To enable this implementation, run your application with the environmental variable
# Requires Node 8+$ GCLOUD_TRACE_NEW_CONTEXT=1 npm start
We are actively looking for feedback on this new implementation. Please file an issue if you encounter unexpected or unwanted behavior.
- See CONTRIBUTING.md
- See LICENSE