v2.9.0

This version features a number of new changes:

• span.endSpan now accepts an optional Date argument to specify the end time of a span (instead of the current time)
• A few new options are now accepted for config.clsMechanism. See the inline documentation for details.
• Experimental async_hooks-based tracing has been changed in the following ways:
  • Except for PROMISE-type async resources, the triggerId field will always be used to determine the current resource's parent for context propagation purposes.
  • Root span context is now determined by the current execution ID, rather than the ID of the last async resource for which the before hook was called. In practice, this should yield no changes unless code is running after an async resource's scope has been exited, but before a new one has been entered.
    • This obviates the before hook entirely, so it has been removed.

Commits

• [be8f4e651a] - doc: clear the changelog (#756) (Kelvin Jin) #756
• [f34aac5ba6] - feat: add options to set the cls mechanism to async-hooks or async-listener (#741) (Kelvin Jin) #741
• [ebd33d802e] - refactor: address cls TODOs (#753) (Kelvin Jin) #753
• [807d4ad33f] - fix: fixup for node 8.11.2 (#755) (Kelvin Jin) #755
• [4733a68b67] - chore(package): update @types/node to version 10.0.9 (#750) (greenkeeper[bot]) #750
• [4c1797101d] - refactor: address TODOs related to spans (#749) (Kelvin Jin) #749
• [000643fe21] - feat: add singular cls option (#748) (Kelvin Jin) #748
• [319642abf5] - feat: allow timestamps to be passed to endSpan (#747) (Kelvin Jin) #747
• [908e431017] - doc: update status badges (#744) (Kelvin Jin) #744
• [6c16beb44e] - test: make it clear that some methods are test-only (#746) (Kelvin Jin) #746
• [a29b985559] - chore: fix types and stop testing on node 10 (#745) (Kelvin Jin) #745
• [0d472e6700] - test: refactor test-span-data (#743) (Kelvin Jin) #743
• [fd122a68e2] - test: update contributing guide and add require test (#738) (Kelvin Jin) #738
• [0e8c53b52b] - chore(package): update @types/is to version 0.0.20 (#742) (greenkeeper[bot]) #742
• [94e5cb2104] - refactor: make logger always last arg (#739) (Kelvin Jin) #739
• [79ab435a98] - fix: adjust async_hooks cls behavior (#734) (Kelvin Jin) #734
• [d8f36118f3] - doc: mention that tracing doesn't work oob with gcf (#735) (Kelvin Jin) #735

v2.8.1

2018-05-02, Version 2.8.1 (Beta), @kjin

This version adds missing source files in 2.8.0.

Commits

• [49a900afa6] - fix: add build/src/cls in output files (#736) (Kelvin Jin) #736

v2.8.0

2018-05-02, Version 2.8.0 (Beta), @kjin

This version adds a new configuration option, as well as minor changes to the custom span API.

Notable Changes

Configuration

• A new configuration option config.clsMechanism is available, which can be used to disable automatic trace context propagation across asynchronous boundaries. This options should be considered advanced usage, and is intended to be used in conjunction with the custom span API with all automatic tracing plugins disabled.
• A potential issue was fixed where the value of config.projectId isn't used if the environment variable GCLOUD_PROJECT is set to an empty string.

Custom Span API

• A new function createChildSpan has been added to SpanData objects passed to the user with runInRootSpan (the type of which is now RootSpanData). Under normal circumstances, creating a root span using myRootSpan.createChildSpan should be identical to traceApi.createChildSpan when myRootSpan is automatically detected from CLS to be the current root span. This API was added to facilitate creating child spans when the current root span can no longer be auto-detected from CLS because the user disabled CLS through config.clsMechanism.
• When a function passed to traceApi.runInRootSpan or traceApi.wrap throws, the trace context will correctly be reset to its original value before the function was run.

Commits

• [d0009ff5ea] - feat: add rootSpan.createChildSpan and change none CLS semantics (#731) (Kelvin Jin) #731
• [6e46ed1772] - chore: start running ci for node 10 (#729) (Kelvin Jin) #729
• [5d000e95e2] - feat: allow "disabling" cls, and relax requirements for creating root spans (#728) (Kelvin Jin) #728
• [edb8135a79] - fix: restore context when a function run with a given context throws (#727) (Kelvin Jin) #727
• [132db9b058] - fix: class-ify cls implementations (#708) (Kelvin Jin) #708
• [395a0c7b2e] - chore(package): update ts-node to version 6.0.0 (#726) (greenkeeper[bot]) #726
• [d0337fa7b0] - fix: fix log messages and ignore falsey env vars (#724) (Kelvin Jin) #724
• [e5a4d765d2] - test: fix system test (#723) (Kelvin Jin) #723

v2.7.2

2018-04-10, Version 2.7.2 (Beta), @kjin

This version adds support for completely disabling plugins by passing a non-object value (false recommended to convey intent) for config.plugins.

Commits

• [068260c595] - fix: allow non-objects for plugins to disable automatic tracing (#720) (Kelvin Jin) #720

v2.7.1

2018-04-05, Version 2.7.1 (Beta), @kjin

This version fixes an issue with tracing HTTPS client requests in Node <=8 that was introduced in 2.6.0.

Commits

• [a3ea16dc06] - fix: fix https tracing breakage in node <9 and rewrite http tests (#717) (Kelvin Jin) #717

v2.7.0

2018-04-03, Version 2.7.0 (Beta), @kjin

This version introduces support for tracing Hapi 17.

Commits

• [028032f945] - feat: hapi 17 tracing support (#710) (Kelvin Jin) #710
• [b64661184b] - build: add script to fetch plugin types (#711) (Kelvin Jin) #711

v2.6.1

2018-04-02, Version 2.6.1 (Beta), @kjin

This version fixes an issue where invalid trace labels were added when the Trace Agent auto-discovers GCP metadata from within a GCP instance.

Commits

• [1434d5db7a] - fix: treat instanceId metadata as a number (#713) (Kelvin Jin) #713

v2.6.0

2018-03-30, Version 2.6.0 (Beta), @kjin

This version introduces non-null spans, a new plugin loading mechanism, revised log messages and changes to pg tracing support (now including version 7).

Notable Changes

Non-Null Spans

SpanData objects passed by traceApi.runInRootSpan and returned by traceApi.createChildSpan are guaranteed to be non-null, whereas they previously could be null if either (1) they weren't created because of tracing policy decisions (an untraced span) or (2) an attempt to create the span was made in a place where it was impossible to determine on behalf of which incoming request they were tracing (an uncorrelated span). In other words:

const traceApi = require('@google-cloud/trace-agent').start();
traceApi.runInRootSpan({ name: 'my-custom-span' }, (rootSpan) => {
  if (!rootSpan) {
    // This code path will no longer execute.
  }
  const childSpan = traceApi.createChildSpan({ name: 'my-custom-smaller-span' });
  if (!childSpan) {
    // This code path will no longer execute.
  }
  // ...
});

Instead, "phantom" SpanData will be returned, which expose an identical, but non-functional API to that of a "real" SpanData object. The purpose of this change is to alleviate the burden of having branching code paths based on whether your code was being traced or not -- you may now assume that functions such as addLabel and endSpan are always on the given SpanData object.

If you must execute a separate code path based on whether your code is being traced or not, you may now use traceApi.isRealSpan:

const traceApi = require('@google-cloud/trace-agent').start();
traceApi.runInRootSpan({ name: 'my-custom-span' }, (rootSpan) => {
  if (!traceApi.isRealSpan(rootSpan)) {
    // Some code that should be executed because this request is not being traced.
  }
  const childSpan = traceApi.createChildSpan({ name: 'my-custom-smaller-span' });
  if (!traceApi.isRealSpan(childSpan)) {
    // Alternatively, you may directly check whether a span is untraced or uncorrelated.
    if (childSpan.type === traceApi.spanTypes.UNCORRELATED) {
      // Some code that should be executed because we lost context.
    } else if (childSpan.type === traceApi.spanTypes.UNTRACED) {
      // Some code that should be executed because the request was not sampled
      // (or otherwise disallowed by the tracing policy).
    }
  }
  // ...
});

This affects both plugins and the custom tracing API. All built-in tracing plugins have been changed correspondingly.

Log Messages

All logging output has been revised for consistency, and now include class/function names, as well as parameters in [square brackets].

Plugin Loader

The plugin loading mechanism has been completely re-written. There should be no observable changes (please file an issue if you encounter one.) The re-write fixes an issue where plugins can't patch modules with circular dependencies correctly (#618).

Tracing pg

We now support tracing for pg versions 6 - 7.

For consistency between tracing version 6 and 7, span labels in pg (when config.enhancedDatabaseReporting is enabled) now contain pre-processed query values rather than post-processed values.

Commits

• [53d2b9684f] - doc: update README.md (#706) (Kelvin Jin) #706
• [f070636eb4] - fix: add support for pg 7 changes (#702) (Kelvin Jin) #702
• [c13a3bf207] - test: privatize forceNewAgent_ (#705) (Kelvin Jin) #705
• [87de955b00] - test: rewrite google-gax test and remove datastore test (#703) (Kelvin Jin) #703
• [5e3375b58c] - chore(package): update ts-node to version 5.0.1 (#673) (greenkeeper[bot]) #673
• [0807fae7ea] - chore(package): update @types/is to version 0.0.19 (#704) (greenkeeper[bot]) #704
• [c8c5bfc616] - feat: expand version range for pg to 7.x (#701) (Matt Oakes) #701
• [4d3d54e5db] - fix: rewrite all log messages (#700) (Kelvin Jin) #700
• [1fb53a7d68] - chore(package): update @types/mocha to version 5.0.0 (#698) (greenkeeper[bot]) #698
• [fb344d665c] - fix(package): update gcp-metadata to version 0.6.3 (#672) (Kelvin Jin) #672
• [1604c48a52] - fix: rewrite plugin loader (#686) (Kelvin Jin) #686
• [dca5cc0103] - test: fixup issue stemming from testing http2 on node 9.9 (#699) (Kelvin Jin) #699
• [770ab0840a] - test: don't use exec to test preloaded modules (#696) (Kelvin Jin) #696
• [5338a9377e] - refactor: externalize singleton accessors from trace writer (#694) (Kelvin Jin) #694
• [9d56e846a8] - fix(package): update @google-cloud/common to version 0.16.2 (#692) (greenkeeper[bot]) #692
• [49b2118ab8] - feat: ensure spans are non-null (#680) (Kelvin Jin) #680
• [6b8a82b2e9] - test: stop testing plugin functionality on appveyor (#693) (Kelvin Jin) #693
• [a35d115e2c] - chore: upgrade typescript to 2.7 (#687) (Kelvin Jin) #687
• [d43c28e0a3] - chore(package): update js-green-licenses to version 0.5.0 (#685) (greenkeeper[bot]) #685
• [ea9279af40] - chore: update @types/shimmer definitions (#681) (Kelvin Jin) #681
• [d3cc125e8d] - refactor: move stack frame creation to utils (#678) (Kelvin Jin) #678
• [c8e2439863] - test: replace web framework tracing tests (#658) (Kelvin Jin) #658

v2.5.0

2018-02-23, Version 2.5.0 (Beta), @kjin

This version changes how span IDs are generated, and extends traced gRPC versions.

Notable Changes

• [ca92e9fb0e] - feat: expand grpc supported versions to <2 (#668) (Kelvin Jin) #668
• [a212d706cd] - fix: change span ID to use random bytes (#654) (Dave Raffensperger) #654

Commits

• [53614e4455] - chore(package): update mocha to version 5.0.0 (#653) (greenkeeper[bot]) #653
• [ca92e9fb0e] - feat: expand grpc supported versions to <2 (#668) (Kelvin Jin) #668
• [72b493de02] - doc: update broken references to source files (#663) (Kelvin Jin)
• [54dd734064] - fix: add web framework plugin types and script to fetch types (#621) (Kelvin Jin) #621
• [a212d706cd] - fix: change span ID to use random bytes (#654) (Dave Raffensperger) #654
• [b52cde1751] - chore: enable circleci cron and cover src/**/*.ts files only (#651) (Kelvin Jin) #651
• [b811387b6c] - doc: add details about running tests locally in CONTRIBUTING.md (#655) (Kelvin Jin) #655
• [74b9291abc] - chore(package): update js-green-licenses to version 0.4.0 (#652) (greenkeeper[bot])
• [6ef8cda919] - chore: copy cached packages in appveyor (#642) (Kelvin Jin) #642
• [0a3697934d] - refactor: types for http (#649) (Kelvin Jin) #649
• [74b0724091] - chore: add npm publish job to circle ci (#647) (Kelvin Jin) #647

v2.4.1

2018-01-12, Version 2.4.1 (Beta), @kjin

This change adds a patch to reduce the overhead introduced by the Trace Agent for outgoing HTTP requests.

Notable Changes

• [182c0cbc6f] - refactor: use setHeader to set trace context header (#643) (Kelvin Jin) #643

Commits

• [dbeae04f51] - fix: fix a failing http2 test in Node 9.4.0 (#648) (Jinwoo Lee)
• [182c0cbc6f] - refactor: use setHeader to set trace context header (#643) (Kelvin Jin) #643
• [202d4cb5b7] - chore(package): update js-green-licenses to version 0.3.1 (#641) (greenkeeper[bot])
• [4c036eaa3a] - chore(package): update @types/node to version 9.3.0 (greenkeeper[bot])
• [4003286152] - chore: Update @google-cloud/common types (#628) (Dominic Kramer) #628
• [c275079956] - chore: Update LICENSE (#635) (chenyumic)
• [ea3b26e7fe] - build: transition to circle 2 and cache test fixtures in CI (#634) (Kelvin Jin) #634
• [61f620d7e7] - chore: license check in posttest (#636) (Jinwoo Lee)