@google-cloud/trace-agent
Advanced tools
@google-cloud/trace-agent is a Node.js client library for Google Cloud Trace, which allows you to automatically collect latency data from your applications and visualize it in the Google Cloud Console. This helps in monitoring and diagnosing performance issues in your applications.
Automatic Tracing
Automatically traces incoming requests and outgoing HTTP calls, capturing latency data without requiring manual instrumentation.
const tracer = require('@google-cloud/trace-agent').start();Custom Spans
Allows you to create custom spans to measure the latency of specific sections of your code.
const tracer = require('@google-cloud/trace-agent').start();
const span = tracer.createChildSpan({ name: 'custom-span' });
// Do some work
span.endSpan();Context Propagation
Ensures that trace context is propagated across asynchronous boundaries, allowing you to get a complete picture of a request's lifecycle.
const tracer = require('@google-cloud/trace-agent').start();
tracer.runInRootSpan({ name: 'root-span' }, rootSpan => {
// Do some work
rootSpan.endSpan();
});Elastic APM is an application performance monitoring system built on the Elastic Stack. It provides similar tracing capabilities but is designed to work seamlessly with Elasticsearch and Kibana.
Datadog APM provides end-to-end distributed tracing and is part of the Datadog observability platform. It offers more integrations and features like real-time analytics and anomaly detection.
Node.js Support for StackDriver Trace
Read more about the client libraries for Cloud APIs, including the older Google APIs Client Libraries, in Client Libraries Explained.
Table of contents:
npm install @google-cloud/trace-agent
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 8+.
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:
require('@google-cloud/trace-agent').start();
// ...
Optionally, you can pass a configuration object to the start() function as follows:
require('@google-cloud/trace-agent').start({
samplingRate: 5, // sample 5 traces per second, or at most 1 every 200 milliseconds.
ignoreUrls: [ /^\/ignore-me/ ] // ignore the "/ignore-me" endpoint.
ignoreMethods: [ 'options' ] // ignore requests with OPTIONS method (case-insensitive).
});
// ...
The object returned by start() may be used to create custom trace spans:
const tracer = require('@google-cloud/trace-agent').start();
// ...
app.get('/', async () => {
const customSpan = tracer.createChildSpan({name: 'my-custom-span'});
await doSomething();
customSpan.endSpan();
// ...
});
The trace agent can do automatic tracing of the following web frameworks:
The agent will also automatically trace RPCs from the following modules:
http, https, and http2 core modulesYou can use the Custom Tracing API to trace other modules in your application.
To request automatic tracing support for a module not on this list, please file an issue. Alternatively, you can write a plugin yourself.
To load an additional plugin, specify it in the agent's configuration:
require('@google-cloud/trace-agent').start({
plugins: {
// You may use a package name or absolute path to the file.
'my-module': '@google-cloud/trace-agent-plugin-my-module',
'another-module': path.join(__dirname, 'path/to/my-custom-plugins/plugin-another-module.js')
}
});
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.
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. This means that root spans shouldn't be created in a context where a root span already exists; a child span is more suitable here. Instead, root spans should be created to track work that happens outside of the request lifecycle entirely, such as periodically scheduled work. To illustrate:
const tracer = require('@google-cloud/trace-agent').start();
// ...
app.get('/', (req, res) => {
// We are in an automatically created root span corresponding to a request's
// lifecycle. Here, we can manually create and use a child span to track the
// time it takes to open a file.
const readFileSpan = tracer.createChildSpan({ name: 'fs.readFile' });
fs.readFile('/some/file', 'utf8', (err, data) => {
readFileSpan.endSpan();
res.send(data);
});
});
// For any significant work done _outside_ of the request lifecycle, use
// runInRootSpan.
tracer.runInRootSpan({ name: 'init' }, rootSpan => {
// ...
// Be sure to call rootSpan.endSpan().
});
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.
Calling the start function returns an instance of Tracer, which provides an interface for tracing:
const tracer = require('@google-cloud/trace-agent').start();
It can also be retrieved by subsequent calls to get elsewhere:
// after start() is called
const tracer = require('@google-cloud/trace-agent').get();
A Tracer object is guaranteed to be returned by both of these calls, even if the agent is disabled.
A fully detailed overview of the Tracer object is available here.
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 async_hooks to keep track of the "trace context" across asynchronous boundaries.
async_hooks works well in most cases. However, it does have some limitations that can prevent us from being able to properly propagate trace context:
async_hooks API has issues tracking context around await-ed "thenables" (rather than real promises). Requests originating from the body of a then implementation in such a user-space "thenable" may not get traced. This is largely an unconventional case but is present in the knex module, which monkeypatches the Bluebird Promise's prototype to make database calls. If you are using knex (esp. the raw function), see #946 for more details on whether you are affected, as well as a suggested workaround.unsupported
The Trace Agent does not support bundled server code, so bundlers like webpack or @zeit/ncc will not work.
Samples are in the samples/ directory. The samples' README.md
has instructions for running the samples.
| Sample | Source Code | Try it |
|---|---|---|
| App | source code |  |
| Snippets | source code | |
The Stackdriver Trace Node.js Client API Reference documentation also contains samples.
Our client libraries follow the Node.js release schedule. Libraries are compatible with all current active and maintenance versions of Node.js.
Client libraries targetting some end-of-life versions of Node.js are available, and
can be installed via npm dist-tags.
The dist-tags follow the naming convention legacy-(version).
Legacy Node.js versions are supported as a best effort:
legacy-8: install client libraries from this dist-tag for versions
compatible with Node.js 8.This library follows Semantic Versioning.
This library is considered to be in beta. This means it is expected to be mostly stable while we work toward a general availability release; however, complete stability is not guaranteed. We will address issues and requests against beta libraries with a high priority.
More Information: Google Cloud Platform Launch Stages
Contributions welcome! See the Contributing Guide.
Please note that this README.md, the samples/README.md,
and a variety of configuration files in this repository (including .nycrc and tsconfig.json)
are generated from a central template. To edit one of these files, make an edit
to its template in this
directory.
Apache Version 2.0
See LICENSE
5.0.0 (2020-06-04)
FAQs
Node.js Support for StackDriver Trace
The npm package @google-cloud/trace-agent receives a total of 87,680 weekly downloads. As such, @google-cloud/trace-agent popularity was classified as popular.
We found that @google-cloud/trace-agent demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
A developer is accusing Tencent of violating the GPL by modifying a Python utility and changing its license to BSD, highlighting the importance of copyleft compliance.
Security News
In an open letter, JavaScript community leaders urge Oracle to give up the JavaScript trademark, arguing that it has been effectively abandoned through nonuse.
Security News
The initial version of the Socket Python SDK is now on PyPI, enabling developers to more easily interact with the Socket REST API in Python projects.