Support matrix

Node.js platforms

Node.js
0.8.x - 0.12.x, 4.0.0 - 6.0.0+
io.js
all

Node.js databases

mongodb
1.2.9 - 1.4.9, 2.0.9
mongodb-core
1.1.0+
Microsoft SQL via tedious
0.0.4 - 1.8.1
oracledb
0.2.4+
pg
0.13.3 - 4.1.0
mysql
0.9.0 - 2.5.3
Cassandra

Node.js caches

levelup
0.17.0 - 0.19.0
memcached
0.1.1 - 2.0.0
redis
0.6.5 - 1.x

Node.js core modules

  • crypto
  • fs
  • http
  • https
  • zlib

Other Node.js components

amqp
0.1.8 - 0.2.4
amqplib
0.2.0+

Node.js frameworks

flatiron
0.4.x+ via director
express
3.0.0-4.10.4
kraken
via express
mean
via express
coke
via express
sails
via express
hapi
1.0.0-9.x
restify
2.0.0-2.8.3
koa

Installing instrumentation

Instrumentation for node.js is provided as a package called ‘traceview’.

  1. Change directory to your app directory.
  2. Make sure build-essential is installed first.

    apt-get install build-essential
    
  3. The traceview module is hosted on npm, so you install it just like any other package.

    npm install --save traceview
    
  4. There are two options for loading the package:

    • Option 1: Require traceview in your entry point file, before any other require() calls.

      require('traceview')
      
    • Option 2: Automatically inject TraceView instrumentation at runtime without modifying your code by running a binary called node-tv instead of node itself.

      node-tv application-name.js
      

Uninstalling instrumentation

npm uninstall --save traceview

Upgrading instrumentation

npm install --save traceview@latest

Configuring instrumentation

The traceview module includes many settings that can be used to modify how TraceView behaves, control security options, or even disable individual instrumentation. You can any or all of the following methods:

  • JSON configuration—you can store configuration data in a file named ‘traceview.json’, at the root of your app, and it will get loaded when the traceview module starts up. As a starting point, you can can copy and modify the contents of the defaults.js file.
  • Programmatic configuration—you can apply settings programmatically by modifying the object returned when requiring traceview; you can do this in addition to having a JSON config file.

    var tv = require('traceview')
    tv.traceMode = 'always'
    
  • Command-line configuration—when using the optional node-tv binary to run your app, you can use several flags before you declare the entry point file in order to configure how traceview should behave. For example, to configure tracing mode, you can set –traceMode or –trace-mode to ‘always’, ‘through’ or ‘never’. Command-line options are available for global configurations only, not for component instrumentation, and you can use them in combination with the previous two config options.

    # set the host or port
    node-tv --host=127.0.0.1 --port=7831 application-name.js
    # set the tracing mode with --trace-mode or --traceMode
    node-tv --trace-mode=always application-name.js
    node-tv --traceMode=always application-name.js
    # set the tracing mode using the shortened flags
    node-tv --always application-name.js
    

Change the default config

The node.js instrumentation is composed of sub-components providing instrumentation for different parts of the node ecosystem. Each module has several tunable options.

Report backtraces

Backtraces are enabled/disabled on per-module basis and at the layer level. See complete node.js instrumentation configuration options and node.js custom layers, respectively. Regardless of these settings however, backtraces are always reported when an exception is thrown.

Tracelyzer not directly on localhost

If you need to connect to a Tracelyzer that is not available directly on localhost, in a docker container for example, you can set –host and/or –port.

Suppress reporting for sensitive data

The traceview module has the ability to sanitize sql database queries in case you don’t want query parameters displayed in TraceView. By default this functionality is disabled, but you can set sanitizeSql to ‘true’ at the component level to stop collecting and reporting query parameters.

By default url query args are reported for both incoming urls and outgoing calls to remote services. Set includeRemoteUrlParams to ‘false’ for http/https to stop collecting and reporting query args from incoming urls. Set includeRemoteUrlParams to ‘false’ for http-client/https-client to stop collecting and reporting query args from outgoing calls to remote services.

Complete config options

The following is the complete list of node.js instrumentation configuration options. Everything listed below can also be seen in the defaults.js file.

Global options


tv.host
config option
tv.host
description
Set the host ip if you need to connect to a Tracelyzer that is not available on localhost, if your app is running in a docker container for example.
possible values
host-ip
127.0.0.1
history
Introduced with the original node.js instrumentation.
example
# programmatic
tv.host = 127.0.0.1
# command-line
node-tv --host=127.0.0.1 --port=7831 application-name.js
Related options
tv.port

tv.port
config option
tv.port
description
Set the port if you need to connect to a Tracelyzer that is not available on localhost, if your app is running in a docker container for example.
possible values
port-number
Range: 1-65535; Default: 7831.
history
Introduced with the original node.js instrumentation.
example
# programmatic
tv.port= 7831
# command-line
node-tv --host=127.0.0.1 --port=7831 <em>application-name.js
Related options
tv.host

tv.traceMode
config option
tv.traceMode
description
Specify when traces should be initiated for incoming requests.
possible values
always
(Default) Continue existing traces, otherwise attempt to start a new one.
through
Continue existing traces, but never start them. This mode assumes that a higher layer makes the decision about whether to trace.
never
Never continue existing traces or start new ones.
history
Introduced with the original node.js instrumentation.
example
# programmatic
tv.traceMode = always
# command-line
node-tv --trace-mode=always application-name.js
notes
You only need to configure the tracing mode if you are not running an instrumented webserver in front of your application. In this case, set to ‘always’.

Core modules


tv.crypto
config option
tv.crypto
description
Change the default config for node.js core module crypto.
parameters
enabled
Set to ‘true’ by default. Set to ‘false’ to disable instrumentation.
collectBacktraces
Set to ‘true’ by default. Set to ‘false’ to stop collecting and reporting backtraces.
history
Introduced in version 2.2.0 with enabled and collectBacktraces.
example
var tv = require('traceview')
tv.crypto.enabled = true
tv.crypto.collectBacktraces = false
Notes
Building backtraces is a bit performance intensive in node.js, so it may be better to not turn it on for high-traffic services.

tv.http
config option
tv.http
description
Change the default config for the server-side functionality in node.js core module http.
parameters
includeRemoteUrlParams
Set to ‘true’ by default. Set to ‘false’ to stop reporting arguments within remote service calls. A remote service all might be curl, thrift, or any other rpc/http transport.
history
Introduced with includeRemoteUrlParams in version 2.2.0.
example
var tv = require('traceview')
tv.http.includeRemoteUrlParams = false

tv.https
config option
tv.https
description
Change the default config for the server-side functionality in node.js core module https.
parameters
includeRemoteUrlParams
Set to ‘true’ by default. Set to ‘false’ to stop reporting arguments within remote service calls. A remote service all might be curl, thrift, or any other rpc/http transport.
history
Introduced with includeRemoteUrlParams in version 2.2.0.
example
var tv = require('traceview')
tv.https.includeRemoteUrlParams= false

tv.http-client
config option
tv.http-client
description
Change the default config for the client-side functionality in node.js core module http.
parameters
enabled
Set to ‘true’ by default. Set to ‘false’ to disable instrumentation.
collectBacktraces
Set to ‘true’ by default. Set to ‘false’ to stop collecting and reporting backtraces.
includeRemoteUrlParams
Set to ‘true’ by default. Set to ‘false’ to stop reporting arguments within remote service calls. A remote service all might be curl, thrift, or any other rpc/http transport.
history
  • Added includeRemoteUrlParams in version 2.2.0.
  • Introduced in original node.js instrumentation with enabled and collectBacktraces.
example
var tv = require('traceview')
tv['http-client'].enabled = true
tv['http-client'].collectBacktraces = false
tv['http-client'].includeRemoteUrlParams = false
Notes
Building backtraces is a bit performance intensive in node.js, so it may be better to not turn it on for high-traffic services.

tv.https-client
config option
description
Change the default config for the client-side functionality in node.js core module https.
parameters
enabled
Set to ‘true’ by default. Set to ‘false’ to disable instrumentation.
collectBacktraces
Set to ‘true’ by default. Set to ‘false’ to stop collecting and reporting backtraces.
includeRemoteUrlParams
Set to ‘true’ by default. Set to ‘false’ to stop reporting arguments within remote service calls. A remote service all might be curl, thrift, or any other rpc/http transport.
history
  • Added includeRemoteUrlParams in version 2.2.0.
  • Introduced in original node.js instrumentation with enabled and collectBacktraces.
example
var tv = require('traceview')
tv['https-client'].enabled = true
tv['https-client'].collectBacktraces = false
tv['https-client'].includeRemoteUrlParams = false
Notes
Building backtraces is a bit performance intensive in node.js, so it may be better to not turn it on for high-traffic services.

tv.fs
config option
tv.fs
description
Change the default config for node.js core module fs.
parameters
enabled
Set to ‘true’ by default. Set to ‘false’ to disable instrumentation.
collectBacktraces
Set to ‘true’ by default. Set to ‘false’ to stop collecting and reporting backtraces.
history
Introduced in 2.1.0 with enabled and collectBacktraces.
example
var tv = require('traceview')
tv.fs.enabled = true
tv.fs.collectBacktraces = false
Notes
Building backtraces is a bit performance intensive in node.js, so it may be better to not turn it on for high-traffic services.

tv.zib
config option
tv.zib
description
Change the default config for node.js core module zlib.
parameters
enabled
Set to ‘true’ by default. Set to ‘false’ to disable instrumentation.
collectBacktraces
Set to ‘true’ by default. Set to ‘false’ to stop collecting and reporting backtraces.
history
Introduced in 2.1.0 with enabled and collectBacktraces.
example
var tv = require('traceview')
tv.zlib.enabled = true
tv.zlib.collectBacktraces = false
Notes
Building backtraces is a bit performance intensive in node.js, so it may be better to not turn it on for high-traffic services.

Third-party modules


tv.amqp
config option
tv.amqp
description
Change the default config for node.js module amqp.
parameters
enabled
Set to ‘true’ by default. Set to ‘false’ to disable instrumentation.
collectBacktraces
Set to ‘true’ by default. Set to ‘false’ to stop collecting and reporting backtraces.
history
Introduced in 2.0.0 with enabled and collectBacktraces.
example
var tv = require('traceview')
tv.amqp.enabled = true
tv.amqp.collectBacktraces = false
Notes
Building backtraces is a bit performance intensive in node.js, so it may be better to not turn it on for high-traffic services.

tv.node-cassandra-cql
config option
tv.node-cassandra-cql
description
Change the default config for node.js module node-cassandra-cql.
parameters
enabled
Set to ‘true’ by default. Set to ‘false’ to disable instrumentation.
collectBacktraces
Set to ‘true’ by default. Set to ‘false’ to stop collecting and reporting backtraces.
sanitizeSql
Set to ‘false’ by default. Set to ‘true’ to stop collecting and reporting query literals from sql statements.
history
Introduced in 1.2.0 with enabled, collectBacktraces, and sanitizeSql.
example
var tv = require('traceview')
tv['node-cassandra-cql'].enabled = true
tv['node-cassandra-cql'].collectBacktraces = false
tv['node-cassandra-cql'].sanitizeSql = true
Notes
Building backtraces is a bit performance intensive in node.js, so it may be better to not turn it on for high-traffic services.

tv.cassandra-driver
config option
tv.cassandra-driver
description
Change the default config for node.js module cassandra-driver.
parameters
enabled
Set to ‘true’ by default. Set to ‘false’ to disable instrumentation.
collectBacktraces
Set to ‘true’ by default. Set to ‘false’ to stop collecting and reporting backtraces.
sanitizeSql
Set to ‘false’ by default. Set to ‘true’ to stop collecting and reporting query literals from sql statements.
history
Introduced in 1.2.0 with enabled, collectBacktraces, and sanitizeSql.
example
var tv = require('traceview')
tv['cassandra-driver'].enabled = true
tv['cassandra-driver'].collectBacktraces = false
tv['cassandra-driver'].sanitizeSql = true
Notes
Building backtraces is a bit performance intensive in node.js, so it may be better to not turn it on for high-traffic services.

tv.director
config option
tv.director
description
Change the default config for node.js module director.
parameters
enabled
Set to ‘true’ by default. Set to ‘false’ to disable instrumentation.
collectBacktraces
Set to ‘true’ by default. Set to ‘false’ to stop collecting and reporting backtraces.
history
Introduced in 2.2.0 with enabled and collectBacktraces.
example
var tv = require('traceview')
tv.director.enabled = true
tv.director.collectBacktraces = false
Notes
Building backtraces is a bit performance intensive in node.js, so it may be better to not turn it on for high-traffic services.

tv.hapi
config option
tv.hapi
description
Change the default config for node.js module hapi.
parameters
enabled
Set to ‘true’ by default. Set to ‘false’ to disable instrumentation.
collectBacktraces
Set to ‘true’ by default. Set to ‘false’ to stop collecting and reporting backtraces.
history
Introduced in 1.4.0.
example
var tv = require('traceview')
tv.hapi.enabled = true
tv.hapi.collectBacktraces = false
Notes
Building backtraces is a bit performance intensive in node.js, so it may be better to not turn it on for high-traffic services.

tv.levelup
config option
tv.levelup
description
Change the default config for node.js module levelup.
parameters
enabled
Set to ‘true’ by default. Set to ‘false’ to disable instrumentation.
collectBacktraces
Set to ‘true’ by default. Set to ‘false’ to stop collecting and reporting backtraces.
history
Introduced in 1.5.0 with enabled and collectBacktraces.
example
var tv = require('traceview')
tv.levelup.enabled = true
tv.levelup.collectBacktraces = false
Notes
Building backtraces is a bit performance intensive in node.js, so it may be better to not turn it on for high-traffic services.

tv.memcached
config option
tv.memcached
description
Change the default config for node.js module memcached.
parameters
enabled
Set to ‘true’ by default. Set to ‘false’ to disable instrumentation.
collectBacktraces
Set to ‘true’ by default. Set to ‘false’ to stop collecting and reporting backtraces.
history
Introduced in 1.3.0 with enabled and collectBacktraces.
example
var tv = require('traceview')
tv.memcached.enabled = true
tv.memcached.collectBacktraces = false
Notes
Building backtraces is a bit performance intensive in node.js, so it may be better to not turn it on for high-traffic services.

tv.mongodb
config option
tv.mongodb
description
Change the default config for node.js module mongodb.
parameters
enabled
Set to ‘true’ by default. Set to ‘false’ to disable instrumentation.
collectBacktraces
Set to ‘true’ by default. Set to ‘false’ to stop collecting and reporting backtraces.
history
Introduced in the original node.js instrumentation with enabled and collectBacktraces.
example
var tv = require('traceview')
tv.mongodb.enabled = true
tv.mongodb.collectBacktraces = false
Notes
Building backtraces is a bit performance intensive in node.js, so it may be better to not turn it on for high-traffic services.

tv.mysql
config option
tv.mysql
description
Change the default config for node.js module mysql.
parameters
enabled
Set to ‘true’ by default. Set to ‘false’ to disable instrumentation.
collectBacktraces
Set to ‘true’ by default. Set to ‘false’ to stop collecting and reporting backtraces.
sanitizeSql
Set to ‘false’ by default. Set to ‘true’ to stop collecting and reporting query literals from sql statements.
history
Introduced in 1.2.0 with enabled, collectBacktraces, and sanitizeSql.
example
var tv = require('traceview')
tv.mysql.enabled = true
tv.mysql.collectBacktraces = false
tv.mysql.sanitizeSql = true
Notes
Building backtraces is a bit performance intensive in node.js, so it may be better to not turn it on for high-traffic services.

tv.oracledb
config option
tv.oracledb
description
Change the default config for node.js module oracledb.
parameters
enabled
Set to ‘true’ by default. Set to ‘false’ to disable instrumentation.
collectBacktraces
Set to ‘true’ by default. Set to ‘false’ to stop collecting and reporting backtraces.
sanitizeSql
Set to ‘false’ by default. Set to ‘true’ to stop collecting and reporting query literals from sql statements.
history
Introduced in 1.8.0 with enabled, collectBacktraces, and sanitizeSql.
example
var tv = require('traceview')
tv.oracledb.enabled = true
tv.oracledb.collectBacktraces = false
tv.oracledb.sanitizeSql = true
Notes
Building backtraces is a bit performance intensive in node.js, so it may be better to not turn it on for high-traffic services.

tv.pg
config option
tv.pg
description
Change the default config for node.js module pg.
parameters
enabled
Set to ‘true’ by default. Set to ‘false’ to disable instrumentation.
collectBacktraces
Set to ‘true’ by default. Set to ‘false’ to stop collecting and reporting backtraces.
sanitizeSql
Set to ‘false’ by default. Set to ‘true’ to stop collecting and reporting query literals from sql statements.
history
Introduced in 1.4.0 with enabled, collectBacktraces, and sanitizeSql.
example
var tv = require('traceview')
tv.pg.enabled = true
tv.pg.collectBacktraces = false
tv.pg.sanitizeSql = true
Notes
Building backtraces is a bit performance intensive in node.js, so it may be better to not turn it on for high-traffic services.

tv.raw-body
config option
tv.raw-body
description
Change the default config for node.js module raw-body.
parameters
enabled
Set to ‘true’ by default. Set to ‘false’ to disable instrumentation.
collectBacktraces
Set to ‘true’ by default. Set to ‘false’ to stop collecting and reporting backtraces.
history
Introduced in 1.7.1 with enabled and collectBacktraces.
example
var tv = require('traceview')
tv['raw-body'].enabled = true
tv['raw-body'].collectBacktraces = false
Notes
Building backtraces is a bit performance intensive in node.js, so it may be better to not turn it on for high-traffic services.

tv.redis
config option
tv.redis
description
Change the default config for node.js module redis.
parameters
enabled
Set to ‘true’ by default. Set to ‘false’ to disable instrumentation.
collectBacktraces
Set to ‘true’ by default. Set to ‘false’ to stop collecting and reporting backtraces.
history
Introduced in the original node.js instrumentation with enabled and collectBacktraces.
example
var tv = require('traceview')
tv.redis.enabled = true
tv.redis.collectBacktraces = false
Notes
Building backtraces is a bit performance intensive in node.js, so it may be better to not turn it on for high-traffic services.

tv.restify
config option
tv.restify
description
Change the default config for node.js module restify.
parameters
enabled
Set to ‘true’ by default. Set to ‘false’ to disable instrumentation.
collectBacktraces
Set to ‘true’ by default. Set to ‘false’ to stop collecting and reporting backtraces.
history
Introduced in 1.4.0 with enabled and collectBacktraces.
example
var tv = require('traceview')
tv.restify.enabled = true
tv.restify.collectBacktraces = false
Notes
Building backtraces is a bit performance intensive in node.js, so it may be better to not turn it on for high-traffic services.

tv.tedious
config option
tv.tedious
description
Change the default config for node.js module tedious.
parameters
enabled
Set to ‘true’ by default. Set to ‘false’ to disable instrumentation.
collectBacktraces
Set to ‘true’ by default. Set to ‘false’ to stop collecting and reporting backtraces.
sanitizeSql
Set to ‘false’ by default. Set to ‘true’ to stop collecting and reporting query literals from sql statements.
history
Introduced in 1.6.0 with enabled, collectBacktraces, and sanitizeSql.
example
var tv = require('traceview')
tv.tedious.enabled = true
tv.tedious.collectBacktraces = false
tv.tedious.sanitizeSql = true
Notes
Building backtraces is a bit performance intensive in node.js, so it may be better to not turn it on for high-traffic services.

Customizing instrumentation

To write your own custom instrumentation the only function you need is tv.instrument(...), which takes the following form.

syntax
tv.instrument(layerName, runner [, options] [, done])
arguments
layerName
The first argument can be either a layer name or a builder function that returns a new layer.
runner
This is the function you want traced. For synchronous code, it takes no arguments. For asynchronous code, simply add a callback argument and call the callback wherever you want the layer to end.
options
(Optional) If any options are included, ‘enabled’ must also be included.
enabled
A boolean that toggles on tracing for the code you are instrumenting.
collectBacktraces
A boolean that includes a backtrace for the reported layer. Note that building backtraces is a bit performance intensive in node.js, so it may be better to not turn it on for high-traffic services.
done
(Optional) This function is only used when tracing an asynchronous runner.

Custom layers

By default, the node.js instrumentation creates a layer for the code itself, e.g., ‘nodejs’, ‘redis’, ‘mongodb’. If these layers don’t provide enough visibility, you can further divide your code into sub-layers. How you segment your application modules and sub-systems into layers is entirely up to you. For example the out-of-box instrumentation might not recognize calls to external processes, so you could use the API to manually create layers for them. Similarly, multi-threaded apps can have individual layers for each of its asynchronous operations. You have two options for creating a custom layer: either enter a layer name as the first argument of tv.instrument(...), or enter a builder function that receives the current layer and returns a new layer. The latter give you to opportunity to attach additional key-value pairs which will be reported on the trace details page.

 1 # method 1: layer name
 2 function functionToInstrument () {
 3   return tv.instrument('customLayerName', function () {
 4     //your code goes here
 5   })
 6 }
 7 
 8 # method 2: builder function
 9 tv.instrument(function builder (last) {
10   return last.descend('customLayerName', {
11     key1: 'value1',
12     key2: 'value2'
13   })
14 }, functionToInstrument, {
15   // config options. if any are present enabled must also be included
16   enabled: 'true',
17   collectBacktraces: 'true'
18 })

Function profiling

For most situations where you want to analyze a specific region of code, it will be easiest and more informative to use our function profiling interface. The alternative is custom layers, which should generally be reserved for calls to external services that our instrumentation would not normally recognize as needing their own layer.

A function profile enables you to drill down on the performance of a specific region of code within the language layer of your app, seeing how often they are hit, in what calls and traces, and how long they take. For example, you might use function profiles to track the performance of different template renders or to profile a particular segment of your critical path. To create a function profile simply replace the first argument of tv.instrument(...) with a function that receives the current layer and returns a new layer. The function is then treated as its own sub-item within a layer, much like queries in a mysql layer or cache requests in a memcache layer.

 1 tv.instrument(function builder (last) {
 2   return last.profile('profileName', {
 3     key1: 'value1',
 4     key2: 'value2'
 5   })
 6 }, functionToInstrument, {
 7   // config options. if any are present enabled must also be included
 8   enabled: 'true',
 9   collectBacktraces: 'true'
10 })

Controller filter

Node.js instrumentation supports these frameworks. If we don’t support your framework, add controller/action information by reporting an info event with the ‘controller’ and ‘action’ keys. Even if your framework doesn’t have a conventional notion of controllers and actions, you can still take advantage of this filtering capability by simply attaching whatever values that make sense to you.

1 tv.reportInfo({ Controller: 'some-controller', Action: 'some-action' })

Tracing asynchronous operations

For asynchronous operations, you must add a callback to the runner function. After the runner function is finished but before the callback is triggered, instrumentation ends the layer by creating an exit event. Since the runner callback supplants the callback you would have normally given to the instrumented code, tv.instrument takes a done option. It’s an opportunity to cleanly pass a callback to the code you are instrumenting, instead of having to nest it, which could get ugly. It receives all arguments passed into the callback of the runner function.

1 function readFile (file, done) {
2   tv.instrument('read-file', function (callback) {
3     fs.readFile(file, callback)
4   }, done)
5 }

Add info events

There are two reasons you might want to create an info event: the first is to simply to attach any meta data that may be of interest to you during later analysis of a trace. The other reason is to take full advantage of TraceView filtering capability. In short, you can classify extents by attaching a pre-defined set of specified key/value pairs. Then from the dashboard, you can filter for traces with that extent type. See special interpretation, for more on this. To add info to an extent, call .reportInfo() anywhere within it. You may do this at multiple points if necessary. The information events are displayed on the raw span data tab on the trace details page. If all of the key/value pairs for special interpretation are present, the extent type is reflected in the span details tab.

1 tv.reportInfo({ Foo: bar })

Partitions

With hundreds of traces flowing into your dashboard, you need a way to keep them organized. For this, TraceView provides ‘partitions’, a programmatic way of classifying traces. For example, you can place traces into the following user-defined classes: anonymous, authenticated, and administrator. On the dashboard, partitions appear as a filter on the same level as urls and controller/action pairs, so in this example you could choose to limit the display to just requests of authenticated users. Traces are not assigned to any partition by default, and you are free to partition requests however you need to feel that your app is logically arranged. To assign a trace to a partition, just fire an info event anywhere within the trace and attach the partition key/value pair. Partition names may have a maximum length of 40 characters, anything longer is truncated to 40. They’re also limited to alphanumeric characters, or underscores. Any characters that don’t fit this criteria are silently converted to underscores.

1 tv.reportInfo({ Partition: authenticated })

Report errors

Create an error event for an exception, including a backtrace. Error events are marked on the in the trace view 50x50_trans.png and corresponding information is in the errors panel.

1 // the given error must be an instance of the Error type
2 var error = new Error(Authentication Error: You cant do that!)
3 tv.reportError(error)

Start or continue a trace

If the current code path is not already traced, you can call tv.startOrContinueTrace() to start tracing at that point. To continue a trace that started elsewhere in your distributed application, specify a trace id as the first argument. To get the x-trace id at any given point in a request, or other code path defined by custom instrumentation, access the tv.traceId property.

1 tv.startOrContinueTrace(xtraceId, function (last) {
2   return last.descend('my-custom-entry-layer')
3 }, function (done) {
4   // Do some stuff and then call the callback to mark the layer as done
5   setImmediate(done, 1, 2, 3)
6 }, function (a, b, c) {
7   console.log('a, b, c is', a, b, c)
8 })

Real user monitoring

Do you have an instrumented webserver?

These instructions involve enabling RUM via your page template files. If apache or nginx sits in front of your app, you don’t need to enable RUM here. It’s already provided at the web server level via our auto-rum support.

TraceView provides optional javascript-based client-side performance data via real user monitoring (RUM). In order to gather real user timing data from the browser, you’ll need to insert two scripts into your express page layouts via helper methods that automatically generate the required javascript.

  1. Place ‘rumHeader’ just after any <meta&gt tags in your <head> block. It should be the first non-meta tag inside <head>.
  2. Place ‘rumFooter’ immediately before the closing </body> tag.
Embedding RUM js in EJS templates
 1 <head>
 2 <meta ... >
 3 <%- typeof rumHeader !== 'undefined' ? rumHeader : '' %>
 4 ...
 5 </head>
 6 
 7 <body>
 8 ...
 9 <%- typeof rumFooter !== 'undefined' ? rumFooter : '' %>
10 </body>
Embedding RUM js in mustache templates
 1 <head>
 2 <meta ... >
 3 
 4 ...
 5 </head>
 6 
 7 <body>
 8 ...
 9 
10 </body>
Embedding RUM js in jade templates
1 doctype html
2 html(lang="en")
3   head
4     block head
5     | #{rumHeader}
6   body
7     block content
8     | #{rumFooter}