open-telemetry/opentelemetry-js

OpenTelemetry JavaScript Client

---

Getting Started   •   API and SDK Reference

Contributing   •   Examples

---

About this project

This is the JavaScript version of OpenTelemetry, a framework for collecting traces, metrics, and logs from applications.

Quick Start

The following describes how to set up tracing for a basic web application. For more detailed documentation, see the website at https://opentelemetry.io/docs/instrumentation/js/.

Installation

Dependencies with the latest tag on NPM should be compatible with each other. See the version compatibility matrix below for more information.

npm install --save @opentelemetry/api
npm install --save @opentelemetry/sdk-node
npm install --save @opentelemetry/auto-instrumentations-node

Note: auto-instrumentations-node is a meta package from opentelemetry-js-contrib that provides a simple way to initialize multiple Node.js instrumentations.

Set up Tracing

// tracing.js

'use strict'

const process = require('process');
const opentelemetry = require('@opentelemetry/sdk-node');
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
const { ConsoleSpanExporter } = require('@opentelemetry/sdk-trace-base');
const { Resource } = require('@opentelemetry/resources');
const { SemanticResourceAttributes } = require('@opentelemetry/semantic-conventions');

// configure the SDK to export telemetry data to the console
// enable all auto-instrumentations from the meta package
const traceExporter = new ConsoleSpanExporter();
const sdk = new opentelemetry.NodeSDK({
  resource: new Resource({
    [SemanticResourceAttributes.SERVICE_NAME]: 'my-service',
  }),
  traceExporter,
  instrumentations: [getNodeAutoInstrumentations()]
});

// initialize the SDK and register with the OpenTelemetry API
// this enables the API to record telemetry
sdk.start();

// gracefully shut down the SDK on process exit
process.on('SIGTERM', () => {
  sdk.shutdown()
    .then(() => console.log('Tracing terminated'))
    .catch((error) => console.log('Error terminating tracing', error))
    .finally(() => process.exit(0));
});

Run Your Application

node -r ./tracing.js app.js

The above example will emit auto-instrumented telemetry about your Node.js application to the console. For a more in-depth example, see the Getting Started Guide. For more information about automatic instrumentation see @opentelemetry/sdk-trace-node, which provides auto-instrumentation for Node.js applications. If the automatic instrumentation does not suit your needs, or you would like to create manual traces, see @opentelemetry/sdk-trace-base

Library Author

If you are a library author looking to build OpenTelemetry into your library, please see the documentation. As a library author, it is important that you only depend on properties and methods published on the public API. If you use any properties or methods from the SDK that are not officially a part of the public API, your library may break if an Application Owner uses a different SDK implementation.

Supported Runtimes

Platform Version	Supported
Node.JS v22	✔️
Node.JS v20	✔️
Node.JS v18	✔️
Node.JS v16	✔️
Node.JS v14	✔️
Older Node Versions	See Node Support
Web Browsers	See Browser Support below

Node Support

Only Node.js Active or Maintenance LTS versions are supported. Previous versions of node may work, but they are not tested by OpenTelemetry and they are not guaranteed to work. Note that versions of Node.JS v8 prior to v8.12.0 will NOT work, because OpenTelemetry Node depends on the perf_hooks module introduced in v8.5.0 and performance.timeOrigin that is set correctly starting in v8.12.0.

Browser Support

Important

Client instrumentation for the browser is experimental and mostly unspecified. If you are interested in helping out, get in touch with the Client Instrumentation SIG.

There is currently no list of officially supported browsers. OpenTelemetry is developed using standard web technologies and aims to work in currently supported versions of major browsers.

Package Version Compatibility

OpenTelemetry is released as a set of distinct packages in 3 categories: API, stable SDK, and experimental. The API is located at /api, the stable SDK packages are in the /packages directory, and the experimental packages are listed in the /experimental/packages directory. There may also be API packages for experimental signals in the experimental directory. All stable packages are released with the same version, and all experimental packages are released with the same version. The below table describes which versions of each set of packages are expected to work together.

Stable Packages	Experimental Packages
1.21.x	0.48.x
1.20.x	0.47.x
1.19.x	0.46.x
1.18.x	0.45.x
1.17.x	0.44.x

Older version compatibility matrix

Stable Packages	Experimental Packages
1.16.x	0.42.x
1.15.x	0.41.x
1.14.x	0.40.x
1.13.x	0.39.x
1.12.x	0.38.x
1.11.x	0.37.x
1.10.x	0.36.x
1.9.x	0.35.x
1.8.x (this and later versions require API >=1.3.0 for metrics)	0.34.x
1.7.x	0.33.x
1.6.x	0.32.x
1.5.x	0.31.x
1.4.x	0.30.x
1.3.x	0.29.x
1.2.x	0.29.x
1.1.x	0.28.x
1.0.x	0.27.x
1.0.x (this and later versions require API >=1.0.0 for traces)	0.26.x

Versioning

The current version for each package can be found in the respective package.json file for that module. For additional details see the versioning and stability document in the specification.

Feature Status

Signal	API Status	SDK Status
Tracing	Stable	Stable
Metrics	Stable	Stable
Logs	Development	Development

For a more detailed breakdown of feature support see the specification compliance matrix.

Contributing

We'd love your help!. Use tags up-for-grabs and good first issue to get started with the project. For instructions to build and make changes to this project, see the CONTRIBUTING guide.

We have a weekly SIG meeting! See the community page for meeting details and notes.

Community members

Maintainers (@open-telemetry/javascript-maintainers)

• Amir Blum, Keyval
• Chengzhong Wu, Bloomberg
• Daniel Dyla, Dynatrace
• Marc Pichler, Dynatrace

Find more about the maintainer role in the community repository.

Approvers (@open-telemetry/javascript-approvers)

• Gerhard Stöbich, Dynatrace
• Haddas Bronfman, Cisco
• Hector Hernandez, Microsoft
• Jamie Danielson, Honeycomb
• Martin Kuba, Lightstep
• Matthew Wear, LightStep
• Naseem K. Ullah, Transit
• Neville Wylie, Microsoft
• Purvi Kanal, Honeycomb
• Svetlana Brennan, New Relic
• Trent Mick, Elastic

Find more about the approver role in the community repository.

Triager (@open-telemetry/javascript-triagers)

• David Luna, Elastic

Find more about the triager role in the community repository.

Emeriti

• Bartlomiej Obecny, LightStep, Maintainer
• Daniel Khan, Dynatrace, Maintainer
• Mayur Kale, Google, Maintainer
• Rauno Viskus, Maintainer
• Valentin Marchaud, Maintainer
• Brandon Gonzalez, LightStep, Approver
• Roch Devost, DataDog, Approver
• John Bley, Splunk, Approver
• Mark Wolff, Microsoft, Approver
• Olivier Albertini, Ville de Montréal, Approver

Find more about the emeritus role in community repository.

Thanks to all the people who already contributed

Packages

API

Package	Description
@opentelemetry/api	This package provides TypeScript interfaces, enums and no-op implementations for the OpenTelemetry core trace and metrics model. It is intended for use both on the server and in the browser.
@opentelemetry/core	This package provides default and no-op implementations of the OpenTelemetry api for trace and metrics. It's intended for use both on the server and in the browser.

Implementation / SDKs

Package	Description
@opentelemetry/sdk-trace-base	This module provides a full control over instrumentation and span creation. It doesn't load async_hooks or any instrumentation by default. It is intended for use both on the server and in the browser.
@opentelemetry/sdk-metrics	This module provides instruments and meters for reporting of time series data.
@opentelemetry/sdk-trace-node	This module provides automatic tracing for Node.js applications. It is intended for use on the server only.
@opentelemetry/sdk-trace-web	This module provides automated instrumentation and tracing for Web applications. It is intended for use in the browser only.

Compatible Exporters

OpenTelemetry is vendor-agnostic and can upload data to any backend with various exporter implementations. Even though, OpenTelemetry provides support for many backends, vendors/users can also implement their own exporters for proprietary and unofficially supported backends.

See the OpenTelemetry registry for a list of exporters available.

Instrumentations

OpenTelemetry can collect tracing data automatically using instrumentations.

To request automatic tracing support for a module not on this list, please file an issue. Alternatively, Vendor/Users can write an instrumentation yourself.

Currently, OpenTelemetry supports automatic tracing for:

Node Instrumentations

Core

• @opentelemetry/instrumentation-grpc
• @opentelemetry/instrumentation-http

Contrib

These instrumentations are hosted at https://github.com/open-telemetry/opentelemetry-js-contrib/tree/master/plugins/node

Web Instrumentations

Core

• @opentelemetry/instrumentation-xml-http-request
• @opentelemetry/instrumentation-fetch

Contrib

These instrumentations are hosted at https://github.com/open-telemetry/opentelemetry-js-contrib/tree/master/plugins/web

Shims

Package	Description
@opentelemetry/shim-opentracing	OpenTracing shim allows existing OpenTracing instrumentation to report to OpenTelemetry

Useful links

• Upgrade guidelines: Upgrade Guide
• For more information on OpenTelemetry, visit: https://opentelemetry.io/
• For help or feedback on this project, join us in GitHub Discussions

License

Apache 2.0 - See LICENSE for more information.

opentelemetry-js's Issues

Update base tsconfig.json to disable all compiler options except type checking

As previously discussed, TypeScript compilation supports many compilation features to alter code depending on the ECMAScript and environment targets. This is problematic since many different targets must be supported with a single build output. It also makes testing much more difficult since in some cases it may make a specific language construct completely unavailable.

Any feature not related to types should be disabled. If shims are needed, they should be manually imported and used depending on specific conditions.

Create an @opentelemetry org on npm

Came across this, while reviewing #25.

I think we should create a dedicated @opentelemetry org on npm.
opentelemetry-types would then become @opentelemetry/types.
As many projects (like Babel) chose this route, this looks like a good practice.

Allow `span` type along with `SpanContext` everywhere

This avoids the caller having to always call span.context() if they are referencing a span.

Originates from: #55 (comment) and #31 (comment)

Proposal: Package Structure

This is my initial proposal to kick of the discussion on npm packages for OpenTelemetry Node.

• opentelemetry/types
  A separate package with only TS interfaces and enums. Originates from #3

• opentelemetry or opentelemetry/api or opentelemetry/core
  This is the core npm package for OpenTelemetry. It contains the public API which is used by the various plugins. Also contains interfaces for traces, metrics, tags, etc.
  Q: What do we want to name the new packages: opentelemetry or opentelemetry/api or opentelemetry/core?

• opentelemetry/basic-tracer
  With this users will have a full control over instrumentation and span creation. The base package doesn't load Continuation Local Storage (CLS) or any instrumentation plugin by default. Originates from census-instrumentation/opencensus-node#495 (comment)

• opentelemetry/context-propagation or opentelemetry/context-cls
  Separate package for CLS (Continuation Local Storage). The primary objective of CLS is to implement a transparent context API, that is, we don't need to pass around a ctx variable everywhere in application code.
  Q: What do we want to name the new packages: opentelemetry/context-propagation or opentelemetry/context-cls?

• opentelemetry/cls-tracer or opentelemetry/automatic-tracer
  Automatic tracer with CLS: opentelemetry/basic-tracer wrapped with opentelemetry/context-propagation.
  Q: What do we want to name the new packages: opentelemetry/cls-tracer or opentelemetry/automatic-tracer?

• opentelemetry/exporter-*
  Contains standard trace and stats exporters. For instance, Jaeger, Zipkin, Stackdriver, Instana, Prometheus, oc-agent, z-pages etc.

• opentelemetry/instrumentation-*
  mongodb, redis, ioredis, express, hapi etc.

• opentelemetry/transport-*
  gRPC, HTTP/2/s, kafka etc.

• opentelemetry/propagation-*
  B3, BinaryFormat, TraceContext

• opentelemetry/resource-util
  It contains a collection of utilities for auto detecting monitored resource when exporting stats, based on the environment where the application is running.

Any thoughts about this?

---

New update (29th May):
Changes as compared to OC:

• api and sdk (basic-tracer and automatic-tracer) are separate packages
• stats has been merged into metrics

---

New Update (30th May)

• opentelemetry/core (2 votes)
• opentelemetry/automatic-tracer (2 votes)

Review file and folder structure casing and relationship

Is your feature request related to a problem? Please describe.

Right now it's not easy to correlate a file with its content. A usual TypeScript project has the name of the file match what it exports. For example: https://github.com/microsoft/TypeScript-Node-Starter/tree/master/src

Describe the solution you'd like

There should be a TSLint rule if possible with the below rules:

• Class and interfaces files should be UpperCamelCase.
• Singleton files should be name like what they export (usually camelCase).
• Files with multiple exports should be kebab-case with a description of the group of exports they represent.
• I'm not sure what the standard is for folders, but I would use the as the above (kebab-case in this proposal).

Add DistributedContext API

Specs: https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/distributedcontext-api.md

Add Tracer API

Specs: https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/tracing-api.md#tracing-api

The API should also include no-op implementations for some classes, see the java client for details.

Change license from Apache-2.0 to MIT or BSD

Is your feature request related to a problem? Please describe.

The Apache-2.0 license is basically non-existent in the Node and JavaScript communities. Most projects use MIT and some commercial vendors prefer to use the slightly more strict BSD family of licenses. There are almost no JS projects using Apache-2.0. This could result in issues since most of the community won't know the implications, which could result in confusion at best and in scaring people off at worst.

Describe the solution you'd like

We should go with a more permissive and less invasive license. Basically the most permissive possible given any restrictions from CNCF. I personally propose using MIT which is used by probably over 99% of community-driven Node and JavaScript projects.

Describe alternatives you've considered

Additional context

I don't know why Apache-2.0 was used and maybe there is a good reason. If that's the case, it should be well explained why the choice was to use such a restrictive license.

Use V8 builtin coverage reporting

🚀 Feature Request

V8 provides a native way of getting code coverage.

Here's a blog post about it.

Motivation

Make coverage 2-3x faster than nyc.

Configure CircleCI workflows

Originates from #39 (Adds CircleCI configuration).

I opted to not set up workflows considering that the repository is still pretty simple and I imagine build/test times will be short for a while. I'll happily spend more time on it when testing parallelization is needed.

Add Metrics API

Specs: open-telemetry/opentelemetry-specification#137

Metrics proposal doc: https://docs.google.com/document/d/1-oFRwkaHVlLM8hTB8NPy-rTcfCZFX5PR4PhZCiK4rCE/edit

supported node versions

The opencensus-node only support node 8 and newer. The opentracing/basictracer-javascript does not specify what are the node versions supported in package.json nor documentation. There are implicit versions supported in the Travis file : https://github.com/opentracing/basictracer-javascript/blob/master/.travis.yml#L3

The current status of Node versions:

Need to decide and document supported node versions.

Add Context-* package and implementation

Add separate packages for Context Propagation/Continues Local Storage (CLS). The primary objective of CLS is to implement a transparent context API, that is, we don't need to pass around a ctx variable everywhere in application code.

In today's (06-19-19) SIG meeting, we have decided to implement generic API, so that it can be used outside OpenTelemetry project.

opentelemetry/context-base
The base implementation that doesn't propagate the context, but handles things like binding.

opentelemetry/context-async-hooks
Implement Async Hooks - async_hooks (since we will be targeting Node 8+).

OpenTracing work on ScopeManager: opentracing/opentracing-javascript#113

OpenCensus work: https://github.com/census-instrumentation/opencensus-node/blob/master/packages/opencensus-core/src/internal/cls-ah.ts

Package Manager: npm or yarn

Decide which package manager to use. Both OpenCensuse Node and opentracing-javascript are using npm.

Originates from #2 (comment)

Add resources API

Specs: https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/resources-api.md

Rename to `opentelemetry-js`?

@rochdev had this idea in #6 (comment)

I would like us to make sure the core packages are compatible with the browser, and I think it will be easier to have Node + browser instrumentation code all living in the same repo to make it easier to keep everything up to date when refactorings happen.

I think the rename would be good for that purpose and to make it clear we are shooting for the broader JS community and not just Node, though Node will be the primary initial implementation target.

Separate Context Propagation from Tracer API

Context

Context Propagation/Continues Local Storage (CLS) is not part of the language, JavaScript or the runtime Node's offering. Although there is some work in Node Core to support distributed tracing use-cases, the solutions today like node-continuation-local-storage come with significant performance overhead and issues, especially with using third-party libraries and a larger amount of async operations like Promises in user-land.

The current practice among APM providers is to hook the Node's module system, monkey patch core modules and bind async primitives via CLS in Node to achieve one line automatic tracing for their customers. This solution is acceptable for most of the Node users, but not for everyone, it's also not compatible with browser environments.

I believe the new OpenTelemetry initiative would give us the opportunity to create a simple synchronous tracer API like OpenTracing and the ability to handle CLS as a separate extension of this API.

Example API

(based on current OpenCensus APIs)

Synchronous Tracer APIs:

  /**
   * Start a new RootSpan to currentRootSpan
   * @param options Options for tracer instance
   * @returns {Span} A root span
   */
  startRootSpan(options: TraceOptions): Span;

  /**
   * Start a new Span instance to the currentRootSpan
   * @param childOf Span
   * @param [options] A TraceOptions object to start a root span.
   * @returns The new Span instance started
   */
  startChildSpan(options?: SpanOptions): Span;

CLS interface to set the context (must be async):

  /**
   * Sets span to current context
   * @param span Span to setup in context.
   * @param fn A callback function that runs after context setup.
   */
  withSpan<T>(span: Span, fn: () => T): T;

Tracer API combined with CLS:

  /**
   * Starts a root span and sets it to context.
   * @param options Options for tracer instance
   * @param fn A callback function to run after starting a root span.
   */
  startWithRootSpan<T>(options: TraceOptions, fn: (root: Span) => T): T;

  /**
   * Start a new Span instance to the currentRootSpan
   * @param childOf Span
   * @param [options] A TraceOptions object to start a root span.
   * @param fn A callback function to run after starting a root span.
   */
  startWithChildSpan<T>(options: TraceOptions, fn: (root: Span) => T): T;

An additional benefit of this API is that using withSpan developer could chain spans in CLS and client RPCs like gRPC would start from the correct contextual child span. OpenCensus today doesn't support context propagation for child spans.

census-instrumentation/opencensus-node#498

Request: separate package with only TS interfaces and enums

I've been working on the OpenCensus Web project, which uses types from OpenCensus Node. However, one of the challenges we ran into is that the @opencensus/core NPM package that had the core trace/stats model types also imported Node-specific libraries like continuation-local-storage, etc. That made it hard to pull in the types only to make a web-specific implementation of them (I ended up writing a copy script).

I think having a clean package with no dependencies besides TypeScript and maybe proto files would be a nice way to make the Node and Web implementations share an API but be free to diverge in the specifics.

We could also try to have a shared core that is common between Node and Web environments, but even simple things like getting a high-resolution timestamp or generating a secure random number are done differently in Node vs. the browser. There are also different tradeoffs like Node wanting raw performance vs. the browser wanting small code size. So I think separate implementations is OK, but we should share common types.

Update links from README.md

Current Behaviour

• Readme (at https://github.com/open-telemetry/opentelemetry-js/blob/master/README.md) contains a broken anchor on the community page link. https://github.com/open-telemetry/community#nodejs-sdk.
• Readme (at https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-types) contains a deprecated useful link (For more about OpenTelemetry Node: https://github.com/open-telemetry/opentelemetry-node)

Expected behaviour

• Community page link should be https://github.com/open-telemetry/community#javascript-sdk
• Useful link should be : For more about OpenTelemetry JS: https://github.com/open-telemetry/opentelemetry-js

Add opentelemetry/basic-tracer package and implementation

Originates from #6

With this user will have a full control over the instrumentation and span creation. The base package doesn't load Continuation Local Storage (CLS) or any instrumentation plugin by default.

Getting 'Cannot find module 'crypto'.' on bootstrapping

Please answer these questions before submitting a bug report.

What version of OpenTelemetry are you using?

Current master branch

What version of Node are you using?

10.16

What did you do?

If possible, provide a recipe for reproducing the error.
npm run bootstrap

What did you expect to see?

Successful bootstrap

What did you see instead?

> lerna bootstrap

lerna notice cli v3.15.0
lerna info Bootstrapping 2 packages
lerna info Symlinking packages and binaries
lerna info lifecycle @opentelemetry/[email protected]~prepare: @opentelemetry/[email protected]

> @opentelemetry/[email protected] prepare /Users/absi/opentelemetry/opentelemetry-js/packages/opentelemetry-core
> yarn run compile:release

yarn run v1.7.0
$ tsc -p tsconfig-release.json
src/common/util/id.ts:17:25 - error TS2307: Cannot find module 'crypto'.

17 import * as crypto from 'crypto';
                           ~~~~~~~~


Found 2 errors.

error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.
lerna info lifecycle @opentelemetry/[email protected]~prepare: Failed to exec prepare script
lerna ERR! lifecycle "prepare" errored in "@opentelemetry/core", exiting 1
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! [email protected] bootstrap: `lerna bootstrap`
npm ERR! Exit status 1
npm ERR! 
npm ERR! Failed at the [email protected] bootstrap script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

npm ERR! A complete log of this run can be found in:
npm ERR!     /Users/absi/.npm/_logs/2019-06-21T08_50_57_808Z-debug.log

Additional context

Using macos 10.12

SDK: Add Plugin Loader

Follow up of #110

Add a PluginLoader (or similar) class providing functionality to hook into module loading and apply plugins to enable tracing.

IMO this should get called in automatic tracer constructor to load all default/configured (ex: http, grpc, express, mysql etc) plugins.

Configure CircleCI

Same as open-telemetry/opentelemetry-python#6

Reference: census-instrumentation/opencensus-node#536

Optimize traceId and spanId generator for performance and factor out server/browser specific apis

As discussed on #35 there a ways to create those random ids in a more performant way. Additionally, we should make it browser/server agnostic by factoring out the individual random id generation.

Bootstrap special interest group

Since it doesn't seem like a special interest group has been formally set up for the node repo, I'd like to propose setting up a SIG similarly to how the dotnet group did theirs. This means setting up a weekly 30 minute sync up, each meeting with a proposed agenda, and a publicly viewable document with meeting notes.

An example of a first meeting's agenda (stolen from dotnet's first meeting):

1. About this meeting
2. High-level plan
3. How to contribute
4. Areas of work

Thoughts and opinions? What day and time should the meeting take place?

Add no-op implementations of Tracer API

Dependency on #85 (review)

.NET Reference: https://github.com/open-telemetry/opentelemetry-dotnet/blob/master/src/OpenTelemetry/Trace/NoopTracer.cs

Java Reference: https://github.com/open-telemetry/opentelemetry-java/blob/master/api/src/main/java/io/opentelemetry/trace/DefaultTracer.java

Add Sampling API

https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/sampling-api.md

Typescript vs Pure Javascript

Originates from #3 (comment)

Add setAttributes to make it easier to add them in bulk.

Is your feature request related to a problem? Please describe.

In JavaScript, it's much easier to use a map-style object to add multiple attributes at once. Having to call setAttribute multiple times is thus unnecessary and requires more code, especially if copying from an existing object.

Describe the solution you'd like

It should be possible to add multiple attributes using a single call.

For example:

span.setAttributes({
  'http.method': 'GET',
  'http.path': '/foo/bar'
})

span.setAttributes(existingObject)

TypeScript Guideline

Originates from #2 (comment)

Codecov: file prefix missing leads to 404

What did you do?

If possible, provide a recipe for reproducing the error.
$ yarn codecov
Viewing a source file at https://codecov.io/gh/open-telemetry/opentelemetry-js/tree/master/src leads to 404 because it is missing a packages/opentelemetry-<package>/ prefix.

What did you expect to see?

Files are viewable from codecov.io

Additional context

Can be solved by simply publishing the reports scoped from the root of the repo, instead of at the package level as it is now.

Also this is probably more of an enhancement instead of a bug

TraceState : validate maximum number of items

Based on https://w3c.github.io/trace-context/#tracestate-field, there can be a maximum of 32 list-members in a list. We have decided to truncate the list instead of throwing exception/error when the defined limit is crossed.

TODOs:
https://github.com/open-telemetry/opentelemetry-js/blob/master/packages/opentelemetry-core/src/trace/TraceState.ts#L19

https://github.com/open-telemetry/opentelemetry-js/blob/master/packages/opentelemetry-core/src/trace/TraceState.ts#L68

Enable code coverage

Setup Codecov(https://codecov.io/) for unit tests, and enforce minimum threshold to >= 80%.

Exposing tracer property on spans

Span has a private tracer property, NoRecordSpan doesn't. I'd prefer to make tracer always available on Span like in OpenTracing. Coming from OpenTracing, I found it challenging not having tracer available on spans, especially that first I assumed it is and started to use it, then my code broke one NoRecordSpan(s).

Add TSLint rule to enforce Apache headers in every file

Is your feature request related to a problem? Please describe.

As discussed in #33, the license should be added automatically to every file to avoid users forgetting to add it, or add it in an inconsistent way.

Describe the solution you'd like

TSLint can be used for this purpose with the file-header rule. The header should also be reduced to a minimal copyright notice to avoid polluting every file with a large block of license at the top.

Describe alternatives you've considered

Alternatively, we could use a license that doesn't strongly suggest a per-file license. Unfortunately, right now Apache-2.0 is enforced by CNCF so this will need to be discussed outside the scope of this project.

Add API to get and init GlobalTracer

This API provides a static global accessor for telemetry objects Tracer and Meter (this may be later).

Specs on Obtaining a tracer.

OpenTelemetry-java also has a global OpenTelemetry instance that, among other things, holds a reference to a global tracer: https://github.com/open-telemetry/opentelemetry-java/blob/fb0f5339cd1d665a98996806f45c60c65f47d7b6/api/src/main/java/io/opentelemetry/OpenTelemetry.java#L49-L58

OpenTracing javascript has same kind of code for global tracer object:
https://github.com/opentracing/opentracing-javascript/blob/master/src/global_tracer.ts#L51

Add CONTRIBUTING guide

Set/Define guidelines for repository contributors.

Should ending a span force its children to end by default?

Howdy y'all, I've been combing through the opencensus-node code in preparation of the node merger happening.

In opencensus-node, there's this interesting bit of code in (Span).end that forces all children spans to end when the parent span ends. I don't think this should be default behavior as I've seen many valid situations where the parent ends before the child, particularly in follows from situations where you have async processes. I do like the debug statement being there, and I like the idea of adding an option to force child spans to end.

Should child span truncation continue to be default behavior?
For opencensus folk, what was the rationale behind it?

Optional strict mode to help surface issues around correctness

Is your feature request related to a problem? Please describe.

We have already made some tradeoffs around accepting incorrect configuration or data without blowing the SDK up. For example using getCurrentSpan with NopScopeManager or passing different format to inject(). I expect we will log warnings or errors about these edge cases, but I could imagine an extra strict (default: false) option that would throw instead of logging and could be used for testing.

In OpenCensus I found challenging sometimes to figure out why my traces are broken when I did something wrong.

Describe the solution you'd like
strict option (default: false) that would throw instead of logging.

logInconsistency(msg) {
  if (this.config.strict) {
    throw new Error(msg)
  }

  this.logger.error(msg);
}

getCurrentSpan(): types.Span {
   if (this.scopeManager instanceof NopScopeManager) {
      this.logInconsistency('NopScopeManager does not support getCurrentSpan()');
   }
   return TracerBase.defaultSpan;
}

Describe alternatives you've considered
Just logging.

Add browser unit tests for `@opentelemetry/core`

Since the @opentelemetry/core package is intended to have shared code that should be usable in either Node or the browser, we should create browser tests for it.

Initially I suggest unit tests with Karma. Longer term, it would be great to use Sauce Labs to do genuine cross-browser functional testing, likely just for the master branch.

How to represent timestamps?

The OpenCensus Node project used Date for span start/end times (code link). That has the downside of only only having millisecond accuracy. OpenTracing JS uses number for milliseconds since the epoch (code link), which currently has ~microsecond accuracy - you can confirm that by testing Date.now() + 0.001 vs. Date.now() + 0.0001.

I think microsecond accuracy is pretty good, but perhaps for some high performance processes you might want higher accuracy, and I think since we are designing this from the ground up, we should ask the question.

Here's an alternative: we use timestamps from the performance.now() clock, which Node 8+ supports, and which also has broad browser support even from IE 10+.

Those timestamps can have nanosecond accuracy for processes that have been running for less than about 90 days (try running 90*365*24*3600*1000 + 1e-6 to check the accuracy).

We would need to convert those timestamps into a format that the exporter expects in a careful way to preserve the accuracy, see for example [this function]
(https://github.com/census-instrumentation/opencensus-web/blob/82464ed231ad829a7a8a72eab17e95577aa813d0/packages/opencensus-web-core/src/common/time-util.ts#L37) that converts a high-accuracy performance.now timestamp and a high-accuracy origin time into a nano-second accuracy ISO date string.

If we just want to do number as millis since the epoch, I'm fine with that too! But wanted to at least open this for discussion. I think use of performance.now as a clock function would be nice either way since it's one less incompatibility between Node and the browser we have to think about.

Add opentelemetry/node-tracer package and implementation

Originates from #6.

Add an automatic tracer (automatically patches well-known modules) with CLS or https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-context-async-hooks package.

OpenCensus implementation: https://github.com/census-instrumentation/opencensus-node/tree/master/packages/opencensus-nodejs-base/src/trace

Support 64bit integers for metrics

The metrics specification calls for two different types of measures: Long and Double. JavaScript has equivalents for these: BigInt and Number respectively, howeverBigInt is still a fairly new addition to ecmascript specification so it isn't supported by older browsers and seems like it was added to node 10.

Rather than having something like

export interface Measure {
  createDoubleMeasurement(value: double): Measurement;
  createLongMeasurement(value: long): Measurement;
}

should opentelemetry-node only support number? The measure interface would look like

export interface Measure {
  createMeasurement(value: number): Measurement;
}

Managing packages with Lerna?

Background: OpenCensus Node uses Lerna to organize codebase into multi-package repositories. Lerna give us the ability to build libraries and apps in a single repo without forcing us to publish to npm or other registries. This results in faster code-test-debug cycles by sharing components locally.

https://hackernoon.com/the-highs-and-lows-of-using-lerna-to-manage-your-javascript-projects-ff5c5cd82a99 -> mentioned some highs and lows of using lerna.

@draffensperger shared below article with me (offline).
https://gist.github.com/nolanlawson/457cdb309c9ec5b39f0d420266a9faa4

Enable renovate on this repo

Let's make sure our dependencies are up to date.

census-instrumentation/opencensus-node#233

Casing of names

I just saw that Event.ts and Sampler.ts are uppercase while we stick to lowercase for the rest.
Do we have a convention for that?

Add Span API

Specs: https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/tracing-api.md#span

Update README.md with high level description, useful links, license info etc.

Similar to https://github.com/open-telemetry/opentelemetry-js/blob/master/packages/opentelemetry-types/README.md

Packages:

• opentelemetry-core
• opentelemetry-types
• opentelemetry-scope-base
• opentelemetry-context-async-hooks
• opentelemetry-basic-tracer
• opentelemetry-node-tracer

Separate `core` package Node/browser specific code into `platform` folders

There is a de-factor standard for a "browser" field in the package.json (see package-browser-field-spec) that webpack, Rollup, etc. respect.

It allows us to specify replacement modules for when the package is used in the browser instead of Node. So we could structure things like this:

// src/platform/index.ts
export * from './node'; // Use Node platform by default

// src/platform/node/index.ts
export * from './id'; // Has Node specific `randomSpanId`

// src/platform/browser/index.ts
export * from './id'; // Has browser specific `randomSpanId`

Then in our package.json for opentelemetry-core we have this:

// packages/opentelemetry-core/package.json
{
   ...
   "browser": {
       "./src/platform/index.ts": "./src/platform/browser/index.ts"
   },
   ...
}

Add opentelemetry/types package

A separate package with only TS interfaces and enums. This is based on #3 and discussion in SIGs meeting. This is also useful if some vendors want to use only types and build their API/Implementations.

It would be nice to split this ask in multiple PRs. Maybe, first PR is to add initial package structure with README, package.json, LICENSE etc (same as https://github.com/open-telemetry/opentelemetry-node/pull/2/files) and incremental PRs to add interfaces and enums.