import * as path from 'path';
const pluginDirectory = path.join(
path.resolve(__dirname, '..'),
'src',
'plugins'
);
export type CLSMechanism =
| 'async-hooks'
| 'async-listener'
| 'auto'
| 'none'
| 'singular';
export type ContextHeaderBehavior = 'default' | 'ignore' | 'require';
export interface RequestDetails {
/**
* The request timestamp.
*/
timestamp: number;
/**
* The request URL.
*/
url: string;
/**
* The request method.
*/
method: string;
/**
* The parsed trace context, if it exists.
*/
traceContext: {traceId: string; spanId: string; options: number} | null;
/**
* The original options object used to create the root span that corresponds
* to this request.
*/
options: {};
}
export interface TracePolicy {
shouldTrace: (requestDetails: RequestDetails) => boolean;
}
export interface GetHeaderFunction {
getHeader: (key: string) => string[] | string | undefined;
}
export interface SetHeaderFunction {
setHeader: (key: string, value: string) => void;
}
export interface OpenCensusPropagation {
extract: (getHeader: GetHeaderFunction) => {
traceId: string;
spanId: string;
options?: number;
} | null;
inject: (
setHeader: SetHeaderFunction,
traceContext: {
traceId: string;
spanId: string;
options?: number;
}
) => void;
}
/**
* Available configuration options. All fields are optional. See the
* defaultConfig object defined in this file for default assigned values.
*/
export interface Config {
/**
* Log levels: 0=disabled, 1=error, 2=warn, 3=info, 4=debug
* The value of GCLOUD_TRACE_LOGLEVEL takes precedence over this value.
*/
logLevel?: number;
/**
* If set to true, prevents a warning from being emitted if modules are
* required before the Trace Agent.
*/
disableUntracedModulesWarning?: boolean;
/**
* Whether to enable to Trace Agent or not.
* Once enabled, the Trace Agent may not be disabled.
*/
enabled?: boolean;
/**
* If true, additional information about query parameters and results will be
* attached (as labels) to spans representing database operations.
*/
enhancedDatabaseReporting?: boolean;
/**
* A value that can be used to override names of root spans. If specified as
* a string, the string will be used to replace all such span names; if
* specified as a function, the function will be invoked with the request path
* as an argument, and its return value will be used as the span name.
*/
rootSpanNameOverride?: string | ((name: string) => string);
/**
* The trace context propagation mechanism to use. The following options are
* available:
* - 'async-hooks' uses an implementation of CLS on top of the Node core
* `async_hooks` module in Node 8+. This option should not be used if the
* Node binary version requirements are not met.
* - 'async-listener' uses an implementation of CLS on top of the
* `continuation-local-storage` module.
* - 'auto' behaves like 'async-hooks' on Node 8+, and 'async-listener'
* otherwise.
* - 'none' disables CLS completely.
* - 'singular' allows one root span to exist at a time. This option is meant
* to be used internally by Google Cloud Functions, or in any other
* environment where it is guaranteed that only one request is being served
* at a time.
* The 'auto' mechanism is used by default if this configuration option is
* not explicitly set.
*/
clsMechanism?: CLSMechanism;
/**
* The number of local spans per trace to allow before emitting an error log.
* An unexpectedly large number of spans per trace may suggest a memory leak.
* This value should be 1-2x the estimated maximum number of RPCs made on
* behalf of a single incoming request.
*/
spansPerTraceSoftLimit?: number;
/**
* The maximum number of local spans per trace to allow in total. Creating
* more spans in a single trace will cause the agent to log an error, and such
* spans will be dropped. (This limit does not apply when using a RootSpan
* instance to create child spans.)
* This value should be greater than spansPerTraceSoftLimit.
*/
spansPerTraceHardLimit?: number;
/**
* The maximum number of characters reported on a label value. This value
* cannot exceed 16383, the maximum value accepted by the service.
*/
maximumLabelValueSize?: number;
/**
* A list of trace plugins to load. Each field's key in this object is the
* name of the module to trace, and its value is the require-friendly path
* to the plugin. (See the default configuration below for examples.)
* Any user-provided value will be used to extend its default value.
* To disable a plugin in this list, you may override its path with a falsy
* value. Disabling any of the default plugins may cause unwanted behavior,
* so use caution.
*/
plugins?: {[pluginName: string]: string};
/**
* The max number of frames to include on traces; pass a value of 0 to
* disable stack frame limits.
*/
stackTraceLimit?: number;
/**
* URLs that partially match any regex in ignoreUrls will not be traced.
* In addition, URLs that are _exact matches_ of strings in ignoreUrls will
* also not be traced (this is deprecated behavior and will be removed in v3).
* URLs should be expected to be in the form of:
* /componentOne/componentTwo...
* For example, having an ignoreUrls value of ['/'] will ignore all URLs,
* while having an ignoreUrls value of ['^/$'] will ignore only '/' URLs.
* Health checker probe URLs (/_ah/health) are ignored by default.
*/
ignoreUrls?: Array<string | RegExp>;
/**
* Request methods that match any string in ignoreMethods will not be traced.
* matching is *not* case-sensitive (OPTIONS == options == OptiONs)
*
* No methods are ignored by default.
*/
ignoreMethods?: string[];
/**
* An upper bound on the number of traces to gather each second. If set to 0,
* sampling is disabled and all traces are recorded. Sampling rates greater
* than 1000 are not supported and will result in at most 1000 samples per
* second. Some Google Cloud environments may further limit this rate.
*/
samplingRate?: number;
/**
* Specifies whether to trace based on the 'traced' bit specified on incoming
* trace context headers. The following options are available:
* 'default' -- Don't trace incoming requests that have a trace context
* header with its 'traced' bit set to 0.
* 'require' -- Don't trace incoming requests that have a trace context
* header with its 'traced' bit set to 0, or incoming requests without a
* trace context header.
* 'ignore' -- The 'traced' bit will be ignored. In other words, the context
* header isn't used to determine whether a request will be traced at all.
* This might be useful for aggregating traces generated by different cloud
* platform projects.
*/
contextHeaderBehavior?: ContextHeaderBehavior;
/**
* For advanced usage only.
* If specified, overrides the built-in trace policy object.
* Note that if any of ignoreUrls, ignoreMethods, samplingRate, or
* contextHeaderBehavior is specified, an error will be thrown when start()
* is called.
*/
tracePolicy?: TracePolicy;
/**
* If specified, the Trace Agent will use this context header propagation
* implementation instead of @opencensus/propagation-stackdriver, the default
* trace context header format.
*/
propagation?: OpenCensusPropagation;
/**
* Buffer the captured traces for `flushDelaySeconds` seconds before
* publishing to the Stackdriver Trace API, unless the buffer fills up first.
* Also see `bufferSize`.
*/
flushDelaySeconds?: number;
/**
* The number of spans in buffered traces needed to trigger a publish of all
* traces to the Stackdriver Trace API, unless `flushDelaySeconds` seconds
* has elapsed first.
*/
bufferSize?: number;
/**
* Specifies the behavior of the trace agent in the case of an uncaught
* exception. Possible values are:
* `ignore`: Take no action. The process may terminate before all the traces
* currently buffered have been flushed to the network.
* `flush`: Handle the uncaught exception and attempt to publish the traces
* to the API. Note that if you have other uncaught exception
* handlers in your application, they may choose to terminate the
* process before the buffer has been flushed to the network. Also,
* if you have no other terminating uncaught exception handlers in
* your application, the error will get swallowed and the
* application will keep on running. You should use this option if
* you have other uncaught exception handlers that you want to be
* responsible for terminating the application.
* `flushAndExit`: Handle the uncaught exception, make a best effort attempt
* to publish the traces to the API, and then terminate the
* application after a delay. Note that the presence of other
* uncaught exception handlers may choose to terminate the
* application before the buffer has been flushed to the network.
*/
onUncaughtException?: string;
/**
* The ID of the Google Cloud Platform project with which traces should
* be associated. The value of GCLOUD_PROJECT takes precedence over this
* value; if neither are provided, the trace agent will attempt to retrieve
* this information from the GCE metadata service.
*/
projectId?: string;
/**
* The contents of a key file. If this field is set, its contents will be
* used for authentication instead of your application default credentials.
*/
credentials?: {client_email?: string; private_key?: string};
/**
* A path to a key file relative to the current working directory. If this
* field is set, the contents of the pointed file will be used for
* authentication instead of your application default credentials.
* If credentials is also set, the value of keyFilename will be ignored.
*/
keyFilename?: string;
/**
* Specifies the service context with which traces from this application
* will be associated. This may be useful in filtering traces originating
* from a specific service within a project. These fields will automatically
* be set through environment variables on Google App Engine.
*/
serviceContext?: {
service?: string;
version?: string;
minorVersion?: string;
};
}
/**
* Default configuration. For fields with primitive values, any user-provided
* value will override the corresponding default value.
* For fields with non-primitive values (plugins and serviceContext), the
* user-provided value will be used to extend the default value.
*/
export const defaultConfig = {
logLevel: 1,
disableUntracedModulesWarning: false,
enabled: true,
enhancedDatabaseReporting: false,
rootSpanNameOverride: (name: string) => name,
clsMechanism: 'auto' as CLSMechanism,
spansPerTraceSoftLimit: 200,
spansPerTraceHardLimit: 1000,
maximumLabelValueSize: 512,
plugins: {
// enable all by default
bluebird: path.join(pluginDirectory, 'plugin-bluebird.js'),
connect: path.join(pluginDirectory, 'plugin-connect.js'),
express: path.join(pluginDirectory, 'plugin-express.js'),
'generic-pool': path.join(pluginDirectory, 'plugin-generic-pool.js'),
grpc: path.join(pluginDirectory, 'plugin-grpc.js'),
hapi: path.join(pluginDirectory, 'plugin-hapi.js'),
'@hapi/hapi': path.join(pluginDirectory, 'plugin-hapi.js'),
http: path.join(pluginDirectory, 'plugin-http.js'),
http2: path.join(pluginDirectory, 'plugin-http2.js'),
koa: path.join(pluginDirectory, 'plugin-koa.js'),
mongodb: path.join(pluginDirectory, 'plugin-mongodb.js'),
'mongodb-core': path.join(pluginDirectory, 'plugin-mongodb-core.js'),
mongoose: path.join(pluginDirectory, 'plugin-mongoose.js'),
mysql: path.join(pluginDirectory, 'plugin-mysql.js'),
mysql2: path.join(pluginDirectory, 'plugin-mysql2.js'),
pg: path.join(pluginDirectory, 'plugin-pg.js'),
redis: path.join(pluginDirectory, 'plugin-redis.js'),
restify: path.join(pluginDirectory, 'plugin-restify.js'),
},
stackTraceLimit: 10,
flushDelaySeconds: 30,
ignoreUrls: ['/_ah/health'],
ignoreMethods: [],
samplingRate: 10,
contextHeaderBehavior: 'default',
bufferSize: 1000,
onUncaughtException: 'ignore',
serviceContext: {},
};