blob: 48e8d7a7994e0189953ad0d710c15447a3376615 [file] [log] [blame]
// Copyright 2015 The Vanadium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
/**
* @summary Namespace vtrace defines a system for collecting debugging
* information about operations that span a distributed system.
* @description
* <p> Namespace vtrace defines a system for collecting debugging
* information about operations that span a distributed system. We
* call the debugging information attached to one operation a Trace.
* A Trace may span many processes on many machines.</p>
*
* <p>Traces are composed of a hierarchy of Spans. A span is a named
* timespan, that is, it has a name, a start time, and an end time.
* For example, imagine we are making a new blog post. We may have to
* first authentiate with an auth server, then write the new post to a
* database, and finally notify subscribers of the new content. The
* trace might look like this:</p>
*
* <pre>
* Trace:
* <---------------- Make a new blog post ----------->
* | | |
* <- Authenticate -> | |
* | |
* <-- Write to DB --> |
* <- Notify ->
* 0s 1.5s 3s
* </pre>
*
* <p>Here we have a single trace with four Spans. Note that some
* Spans are children of other Spans. Vtrace works by attaching data
* to a Context, and this hierarchical structure falls directly out
* of our building off of the tree of Contexts. When you derive a new
* context using withNewSpan(), you create a Span that's a child of the
* currently active span in the context. Note that spans that share a
* parent may overlap in time.</p>
*
* <p>In this case the tree would have been created with code like this:</p>
*
* <pre>
* function makeBlogPost(ctx) {
* var authCtx = vtrace.withNewSpan(ctx, "Authenticate")
* authenticate(authCtx).then(function() {
* var writeCtx = vtrace.withNewSpan(ctx, "Write To DB")
* write(writeCtx)
* }).then(function() {
* var notifyCtx = vtrace.withNewSpan(ctx, "Notify")
* notify(notifyCtx)
* });
* }
* </pre>
*
* <p>Just as we have Spans to represent time spans we have Annotations
* to attach debugging information that is relevant to the current
* moment. You can add an annotation to the current span by calling
* the Span's Annotate method:</p>
*
* <pre>
* var span = vtrace.getSpan(ctx)
* span.annotate("Just got an error")
* </pre>
*
* <p>When you make an annotation we record the annotation and the time
* when it was attached.</p>
*
* <p>Traces can be composed of large numbers of spans containing data
* collected from large numbers of different processes. Always
* collecting this information would have a negative impact on
* performance. By default we don't collect any data. If a
* particular operation is of special importance you can force it to
* be collected by calling a Spans forceCollect method. You can also
* call:
* <pre>
* vtrace.getStore(ctx).setCollectRegexp("regular.*expression")
* </pre>
* which causes us to record any matching trace.</p>
*
* <p>If your trace has collected information you can retrieve the data
* collected so far with the Store's traceRecord and traceRecords methods.</p>
*
* <p>By default contexts obtained from runtime.getContext() or from
* the first parameter of a server method implementation already have
* an initialized Trace. The functions in this package allow you to
* add data to existing traces or start new ones.</p>
* @namespace
* @name vtrace
* @memberof module:vanadium
*/
var extend = require('xtend');
module.exports = extend(
require('./vtrace'),
require('../gen-vdl/v.io/v23/vtrace')
);