// 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')
);