@calebmer-airtable/lightstep-tracer
v0.24.0-no-protobuf-patch.1
Published
[![npm version](https://badge.fury.io/js/lightstep-tracer.svg)](https://badge.fury.io/js/lightstep-tracer) [![Circle CI](https://circleci.com/gh/lightstep/lightstep-tracer-javascript.svg?style=shield)](https://circleci.com/gh/lightstep/lightstep-tracer-ja
Downloads
4
Readme
lightstep-tracer
LightStep distributed tracing library for Node.js and the browser.
Installation
npm install --save lightstep-tracer opentracing
All modern browsers and Node versions >= 0.12 are supported.
Getting started
To use LightStep as the OpenTracing binding, initialize the global Tracer
with the LightStep implementation:
var opentracing = require('opentracing');
var lightstep = require('lightstep-tracer');
opentracing.initGlobalTracer(new lightstep.Tracer({
access_token : '{your_access_token}',
component_name : '{your_service_or_app_name}',
}));
The LightStep JavaScript Tracing Cookbook is a good next stop for information on how to quickly instrument your system. If you want to try something out quickly in your browser code, see the browser quick start example.
- For more information about using the OpenTracing API, see http://opentracing.io/
- See examples/browser for a complete JavaScript browser example
- See examples/node for a complete Node.js server-side example
The browser version of the code can be explicitly included using the following, which can be helpful in some browserify
(or similar) setups:
var lightstep = require('lightstep-tracer/browser');
LightStep-specific API
The OpenTracing standard JavaScript API is documented here. The following describes LightStep-specific options and methods.
LightStep
new Tracer(options)
Required options
access_token
string
required - the project access tokencomponent_name
string
required - the string identifier for the application, service, or process
Standard options
verbosity
number
optional, default=1 - controls the level of logging to the console0
- the client library will never log to the console1
- error reporting will be throttled to the first error per minute2
- all errors are logged to the console3
- all errors, warnings, and info statements are logged to the console4
- all log statements, including debugging details
collector_host
string
optional - custom collector hostnamecollector_port
number
optional - custom collector portcollector_path
string
optional - custom collector base path (if served behind a reverse proxy)collector_encryption
string
optional, default='tls'tls
- use HTTPS encrypted connectionsnone
- use HTTP plain-text connections
Browser-specific initialization options
instrument_page_load
bool
- creates a long-lived single span for the entire page view and is recommended for short-page visits in a multi-page website. For a single-page web app, this behavior may be undesirable. Defaults to false. This must be set at initialization, changes after initialization will have no effect.xhr_instrumentation
bool
- if false, disables automatic instrumentation of XMLHttpRequests (XHRs). This must be set at initialization; changes after initialization will have no effect. Defaults to false.xhr_url_inclusion_patterns
RegExp[]
- an array of regular expressions used to whitelist URLs forXMLHttpRequest
auto-instrumentation. The default value is wildcard matching all strings. For a given URL to be instrumented, it must match at least one regular expression inxhr_url_inclusion_patterns
and not match any regular expressions inxhr_url_exclusion_patterns
.xhr_url_exclusion_patterns
RegExp[]
- an array of regular expressions used to exclude URLs fromXMLHttpRequest
auto-instrumentation. The default value is an empty array. For a given URL to be instrumented, it must match at least one regular expression inxhr_url_inclusion_patterns
and not match any regular expressions inxhr_url_exclusion_patterns
.fetch_instrumentation
bool
- if false, disables automatic instrumentation ofwindow.fetch
. This must be set at initialization; changes after initialization will have no effect. Defaults to false.fetch_url_inclusion_patterns
RegExp[]
- an array of regular expressions used to whitelist URLs forwindow.fetch
auto-instrumentation. The default value is wildcard matching all strings. For a given URL to be instrumented, it must match at least one regular expression infetch_url_inclusion_patterns
and not match any regular expressions infetch_url_exclusion_patterns
.fetch_url_exclusion_patterns
RegExp[]
- an array of regular expressions used to exclude URLs fromwindow.fetch
auto-instrumentation. The default value is an empty array. For a given URL to be instrumented, it must match at least one regular expression infetch_url_inclusion_patterns
and not match any regular expressions infetch_url_exclusion_patterns
.include_cookies
bool
- if true, includes cookies in the span logs for bothwindow.fetch
andXMLHttpRequest
. Defaults to true.
node-specific initialization options
nodejs_instrumentation
bool
- if false, disables automatic instrumentation of node requests. This must be set at initialization; changes after initialization will have no effect. Defaults to false.nodejs_url_inclusion_patterns
RegExp[]
- an array of regular expressions used to whitelist URLs forXMLHttpRequest
auto-instrumentation. The default value is wildcard matching all strings. For a given URL to be instrumented, it must match at least one regular expression innodejs_url_inclusion_patterns
and not match any regular expressions innodejs_url_exclusion_patterns
.nodejs_url_exclusion_patterns
RegExp[]
- an array of regular expressions used to exclude URLs fromXMLHttpRequest
auto-instrumentation. The default value is an empty array. For a given URL to be instrumented, it must match at least one regular expression innodejs_url_inclusion_patterns
and not match any regular expressions innodejs_url_exclusion_patterns
.
Non-standard options
NOTE: Future API compatibility on non-standard options is not guaranteed.
disable_reporting_loop
bool
optional, default=false - if true, the timer that automatically sends reports to the collector will be disabled. This option is independent ofdisable_report_on_exit
.disable_report_on_exit
bool
optional, default=false - if true, the final report that is automatically sent at process exit in Node or page unload in the browser will not be sent.report_timeout_millis
number
optional, default=30000 - the default timeout value, in milliseconds, for reports to the LightStep collectorgzip_json_requests
bool
optional, default=true - if true, the reports will be gzipped before sent to the collector.default_span_tags
string
optional - an associative array of tags to add to every span started by the tracer (e.g., the active user id in a browser client)delay_initial_report_millis
int
optional, default=1000 - maximum additional delay of the initial report in addition to the normal reporting interval. A value between zero and this maximum will be selected as the actual delay. This can be useful when concurrently launching a large number of new processes and there is a desire to distribute the initial reports over a window of time.error_throttle_millis
int
optional, default=60000 - whenverbosity
is set to1
, this the minimum time between logged errors.transport
string
optional, default=proto - whentransport
is set tothrift
, the Tracer will use Thrift as its transport instead of Proto over HTTP.logger
function(level: string, message: string, payload: any): void
optional - specify a custom logger function. Possiblelevel
values aredebug
,info
,warn
anderror
. By default messages will be logged to the console.disable_meta_event_reporting
bool
optional, default=false - whendisable_meta_event_reporting
is set totrue
, the tracer will disable meta event reporting even if requested by the Satellite.propagator
dictionary
optional, defaults={opentracing.FORMAT_HTTP: LightStepPropagator, opentracing.FORMAT_TEXT_MAP: LightStepPropagator, opentracing.FORMAT_BINARY: UnsupportedPropagator}
: Allows inject/extract to use custom propagators for different formats. This package includes aB3Propagator
that supports B3 headers on text maps and http headers.DDPropagator
supports DataDog trace headers.
SpanImp
generateTraceURL()
Returns an absolute URL to the LightStep application for the trace containing this span. It is safe to call this method after finish()
.
...
span.finish();
var url = span.generateTraceURL())
console.log('View the trace for this span at:', url);
License
Copyright (c) 2016, LightStep