- Creating trace spans and add labels to them.

- Getting information about how the trace agent was configured in the current application.

- Parsing and serializing trace contexts to support distributed tracing between microservices.

- Binding callbacks and event emitters in order to propagate trace contexts across asynchronous boundaries.

These functions provide the capability to create trace spans, add labels to them, and close them.

* `options`: [`TraceOptions`](#trace-span-options)

* `fn`: `function(Span): any`

* Returns `any` (return value of `fn`)

* Creates a root span and runs the given callback, passing it a `Span` object. In some instances, this `Span` object doesn't correspond to an actual trace span; this can be checked by consulting the value of `Span#type`:

* The trace policy, as specified by the user-given configuration, disallows a root span from being created under the current circumstances.

* The trace agent is disabled, either because it wasn't started at all, started in disabled mode, or encountered an initialization error.

* The incoming request had headers that explicitly specified that this request shouldn't be traced.

* **Note:** You must call `endSpan` on the span object provided as an argument for the span to be recorded.

* `options`: [`TraceOptions`](#trace-span-options)

* Returns `Span`

* Creates a child `Span` object and returns it. In some instances, this `Span` object doesn't correspond to an actual trace span; this can be checked by consulting the value of `Span#type`:

* A root span wasn't created beforehand because `runInRootSpan` was not called at all. This likely indicates a programmer error, because child spans should always be nested within a root span.

* A root span was created beforehand, but context was lost between then and now. This may also be a programmer error, because child spans should always be created within the context of a root span. See [`Context Propagation`](#context-propagation) for details on properly propagating root span context.

* **Note:** You must call `endSpan` on the returned span object for the span to be recorded.

* An enumeration of the types of spans: `ROOT`, `CHILD`, `UNTRACED`, `UNCORRELATED`

* `Span#addLabel(key, value)`

* `key`: `string`

* Returns `boolean`

* Returns whether the trace agent was started with an enhanced level of reporting. See the [configuration][config-js] object definition for more details.

Plugins that trace incoming HTTP requests (in other words, web frameworks) should support cross-service tracing by reading serialized trace context from the `'x-cloud-trace-context'` header, and supplying it as the [`traceContext` option](#trace-span-options) when creating a new root span. The trace agent will automatically deserialize the trace context and associate any new spans with it.

It is highly recommended for plugins to set this header field in responses, _if_ the incoming request has this header. The trace context that should be written can be obtained with the following function:

* `incomingTraceContext`: `string`

* `isTraced`: `boolean`

* Returns `string`

UNTRACED = 'UNTRACED',

/**

ROOT = 'ROOT',

/**

CHILD = 'CHILD'

import * as extend from 'extend';

import * as path from 'path';

import * as PluginTypes from './plugin-types';

import {Constants} from './constants';

export {Config, PluginTypes};

const normalizedConfig = initConfig(config || {});

// Determine the preferred context propagation mechanism, as

// continuation-local-storage should be loaded before any modules that do I/O.

}

if (!traceAgent) {

}

try {

if (!traceAgent) {

}

return traceAgent;

import {Constants, SpanType} from './constants';

traceContext?: string|null;

/**

};

file?: string;

versions?: string;

unpatch?: (module: T) => void;

export interface Intercept<T> {

file?: string;

versions?: string;

import {IncomingMessage, ServerResponse} from 'http';

import {parse as urlParse} from 'url';

import {PluginTypes} from '..';

return headerValue;

connect_3.NextHandleFunction {

return function middleware(req: Request, res, next) {

const options = {

const SUPPORTED_VERSIONS = '4.x';

const labels = api.labels;

function middleware(

req: express_4.Request, res: express_4.Response,

versions: SUPPORTED_VERSIONS,

patch: patchModuleRoot,

unpatch: unpatchModuleRoot

export = plugin;

import {Client, MethodDefinition, ServerReadableStream, ServerUnaryCall, StatusObject} from 'grpc';

import * as shimmer from 'shimmer';

type Metadata = grpcModule.Metadata&{

let MetadataModuleValue: MetadataModule;

// metadata is the value of module.exports of src/node/src/metadata.js

MetadataModuleValue = metadata;

// So it's safe to provide a no-op unpatch function.

/**

shimmer.unwrap(client, 'makeClientConstructor');

/**

function instrument<T>(

continueCb: () => T): T {

const req = request.raw.req;

const res = request.raw.res;

unpatch: (hapi) => {

shimmer.unwrap(hapi.Server.prototype, 'connection');

}

/**

Request.prototype._execute = Request.prototype._execute[ORIGINAL]!;

}

}

export = plugin;

import * as shimmer from 'shimmer';

import * as url from 'url';

type HttpModule = typeof httpModule;

type HttpsModule = typeof httpsModule;

return options && options.headers &&

!!options.headers[api.constants.TRACE_AGENT_REQUEST_HEADER];

function makeRequestTrace(

// On Node 8+ we use the following function to patch both request and get.

// Here `request` may also happen to be `get`.

return function requestTrace(options, callback): ClientRequest {

};

shimmer.wrap(http, 'request', (request) => {

return makeRequestTrace('http:', request, api);

});

shimmer.wrap(https, 'request', (request) => {

return makeRequestTrace('https:', request, api);

});