Merge remote-tracking branch 'upstream/master' into ioredis-example-2

.circleci/config.yml

@@ -73,6 +73,7 @@ cache_2: &cache_2
     - packages/opentelemetry-plugin-mysql/node_modules
     - packages/opentelemetry-exporter-collector/node_modules
     - packages/opentelemetry-plugin-xml-http-request/node_modules
+    - packages/opentelemetry-exporter-stackdriver-trace/node_modules
 
 node_unit_tests: &node_unit_tests
   steps:

.gitignore

@@ -71,6 +71,7 @@ docs
 
 #lerna
 .changelog
+package.json.lerna_backup
 
 # OS generated files
 .DS_Store

README.md

@@ -9,11 +9,21 @@ This is the JavaScript version of [OpenTelemetry](https://opentelemetry.io/), a
 
 > This project is currently in Alpha stage. Its APIs can change at any time and it is not intended to be used in production scenarios!
 
+## Documentation
+
+For detailed documentation of the OpenTelemetry API, see [the documentation][docs].
+
 ## Quick start
 
-To get started tracing your own application, see the [Getting Started Guide](getting-started/README.md).
+### Application Owner
+
+To get started tracing your own application, see the [Getting Started Guide](getting-started/README.md). For more information about automatic instrumentation see [@opentelemetry/node][otel-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/tracing][otel-tracing]
 
-For more information, see [@opentelemetry/tracing](https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-tracing) for an SDK that supports creating traces through manual instrumentation or [@opentelemetry/node](https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-node) which provides auto-instrumentation for Node.js applications.
+For more information, see [@opentelemetry/tracing][otel-tracing] for an SDK that supports creating traces through manual instrumentation or [@opentelemetry/node][otel-node] which provides auto-instrumentation for Node.js applications.
+
+### Library Author
+
+If you are a library author looking to build OpenTelemetry into your library, please see [the documentation][docs]. 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](#application-owner) uses a different SDK implementation.
 
 ## Release Schedule
 
@@ -52,10 +62,10 @@ Future release targets include:
 
 | Component                   | Version    | Target Date        |
 | --------------------------- | ---------- | ------------------ |
-| Support for Tags/Baggage    | Alpha v0.4 | December 31 2019   |
-| Metrics Aggregation         | Alpha v0.4 | December 31 2019   |
-| Metrics SDK (Complete)      | Alpha v0.4 | December 31 2019   |
-| OpenCensus Bridge           | Alpha v0.4 | December 31 2019   |
+| Support for Tags/Baggage    | Alpha v0.4 | January 31 2020    |
+| Metrics Aggregation         | Alpha v0.4 | January 31 2020    |
+| Metrics SDK (Complete)      | Alpha v0.4 | January 31 2020    |
+| OpenCensus Bridge           | Alpha v0.4 | January 31 2020    |
 
 ## Contributing
 We'd love your help!. Use tags [up-for-grabs][up-for-grabs-issues] and
@@ -68,7 +78,7 @@ Approvers ([@open-telemetry/js-approvers](https://github.com/orgs/open-telemetry
 
 - [Roch Devost](https://github.com/rochdev), DataDog
 - [Brandon Gonzalez](https://github.com/bg451), LightStep
-- [Olivier Albertini](https://github.com/OlivierAlbertini), VilledeMontreal
+- [Olivier Albertini](https://github.com/OlivierAlbertini), Ville de Montréal
 - [Valentin Marchaud](https://github.com/vmarchaud), Open Source Contributor
 - [Mark Wolff](https://github.com/markwolff), Microsoft
 - [Bartlomiej Obecny](https://github.com/obecny), LightStep
@@ -88,57 +98,59 @@ Maintainers ([@open-telemetry/js-maintainers](https://github.com/orgs/open-telem
 
 | Package                 | Description |
 | ----------------------- | -----------------|
-| [@opentelemetry/types](https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-types) | This package provides TypeScript interfaces and enums for the OpenTelemetry core trace and metrics model. It is intended for use both on the server and in the browser. |
-| [@opentelemetry/core](https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-core) | This package provides default and no-op implementations of the OpenTelemetry types for trace and metrics. It's intended for use both on the server and in the browser. |
+| [@opentelemetry/types][otel-types] | This package provides TypeScript interfaces and enums for the OpenTelemetry core trace and metrics model. It is intended for use both on the server and in the browser. |
+| [@opentelemetry/core][otel-core] | This package provides default and no-op implementations of the OpenTelemetry types for trace and metrics. It's intended for use both on the server and in the browser. |
 
 ### Implementation / SDKs
 
 | Package                 | Description |
 | ----------------------- | -----------------|
-| [@opentelemetry/tracing](https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-tracing) | This module provides a full control over instrumentation and span creation. It doesn't load [`async_hooks`](https://nodejs.org/api/async_hooks.html) or any instrumentation plugin by default. It is intended for use both on the server and in the browser. |
-| [@opentelemetry/metrics](https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-metrics) | This module provides instruments and meters for reporting of time series data. |
-| [@opentelemetry/node](https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-node) | This module provides automatic tracing for Node.js applications. It is intended for use on the server only. |
-| [@opentelemetry/web](https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-web) | This module provides automated instrumentation and tracing for Web applications. It is intended for use in the browser only. |
-| [@opentelemetry/base](https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-base) | This package provides base code for the SDK packages (tracing and metrics). |
+| [@opentelemetry/tracing][otel-tracing] | This module provides a full control over instrumentation and span creation. It doesn't load [`async_hooks`](https://nodejs.org/api/async_hooks.html) or any instrumentation plugin by default. It is intended for use both on the server and in the browser. |
+| [@opentelemetry/metrics][otel-metrics] | This module provides instruments and meters for reporting of time series data. |
+| [@opentelemetry/node][otel-node] | This module provides automatic tracing for Node.js applications. It is intended for use on the server only. |
+| [@opentelemetry/web][otel-web] | This module provides automated instrumentation and tracing for Web applications. It is intended for use in the browser only. |
+| [@opentelemetry/base][otel-base] | This package provides base code for the SDK packages (tracing and metrics). |
 
 ### 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. Currently, OpenTelemetry supports:
 
 #### Trace Exporters
-- [@opentelemetry/exporter-jaeger](https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-exporter-jaeger)
-- [@opentelemetry/exporter-zipkin](https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-exporter-zipkin)
+- [@opentelemetry/exporter-jaeger][otel-exporter-jaeger]
+- [@opentelemetry/exporter-zipkin][otel-exporter-zipkin]
+- [@opentelemetry/exporter-stackdriver-trace][otel-exporter-stackdriver-trace]
+- [@opentelemetry/exporter-collector][otel-exporter-collector]
 
 #### Metric Exporters
-- [@opentelemetry/exporter-prometheus](https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-exporter-prometheus)
+- [@opentelemetry/exporter-prometheus][otel-exporter-prometheus]
 
 ### Plugins
 
 OpenTelemetry can collect tracing data automatically using plugins. Vendors/Users can also create and use their own. Currently, OpenTelemetry supports automatic tracing for:
 
 #### Node Plugins
-- [@opentelemetry/plugin-grpc](https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-plugin-grpc)
-- [@opentelemetry/plugin-http](https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-plugin-http)
-- [@opentelemetry/plugin-https](https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-plugin-https)
-- [@opentelemetry/plugin-mongodb](https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-plugin-mongodb)
-- [@opentelemetry/plugin-mysql](https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-plugin-mysql)
-- [@opentelemetry/plugin-pg](https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-plugin-postgres/opentelemetry-plugin-pg)
-- [@opentelemetry/plugin-pg-pool](https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-plugin-postgres/opentelemetry-plugin-pg-pool)
-- [@opentelemetry/plugin-redis](https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-plugin-redis)
-- [@opentelemetry/plugin-ioredis](https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-plugin-ioredis)
-- [@opentelemetry/plugin-dns](https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-plugin-dns) - By default, this plugin is not loaded [#612](https://github.com/open-telemetry/opentelemetry-js/issues/612)
+- [@opentelemetry/plugin-grpc][otel-plugin-grpc]
+- [@opentelemetry/plugin-http][otel-plugin-http]
+- [@opentelemetry/plugin-https][otel-plugin-https]
+- [@opentelemetry/plugin-mongodb][otel-plugin-mongodb]
+- [@opentelemetry/plugin-mysql][otel-plugin-mysql]
+- [@opentelemetry/plugin-pg][otel-plugin-pg]
+- [@opentelemetry/plugin-pg-pool][otel-plugin-pg-pool]
+- [@opentelemetry/plugin-redis][otel-plugin-redis]
+- [@opentelemetry/plugin-ioredis][otel-plugin-ioredis]
+- [@opentelemetry/plugin-dns][otel-plugin-dns] - By default, this plugin is not loaded [#612](https://github.com/open-telemetry/opentelemetry-js/issues/612)
 
 #### Web Plugins
-- [@opentelemetry/plugin-document-load](https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-plugin-document-load)
-- [@opentelemetry/plugin-xml-http-request](https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-plugin-xml-http-request)
+- [@opentelemetry/plugin-document-load][otel-plugin-document-load]
+- [@opentelemetry/plugin-xml-http-request][otel-plugin-xml-http-request]
 
 To request automatic tracing support for a module not on this list, please [file an issue](https://github.com/open-telemetry/opentelemetry-js/issues). Alternatively, you can [write a plugin yourself](https://github.com/open-telemetry/opentelemetry-js/blob/master/doc/plugin-guide.md).
 
 ### Shims
 
 | Package                 | Description |
 | ----------------------- | -----------------|
-| [@opentelemetry/shim-opentracing](https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-shim-opentracing) | OpenTracing shim allows existing OpenTracing instrumentation to report to OpenTelemetry |
+| [@opentelemetry/shim-opentracing][otel-shim-opentracing] | OpenTracing shim allows existing OpenTracing instrumentation to report to OpenTelemetry |
 
 
 ## Useful links
@@ -159,3 +171,31 @@ Apache 2.0 - See [LICENSE][license-url] for more information.
 [codecov-image]: https://codecov.io/gh/open-telemetry/opentelemetry-js/branch/master/graph/badge.svg
 [codecov-url]: https://codecov.io/gh/open-telemetry/opentelemetry-js/branch/master/
 [license-image]: https://img.shields.io/badge/license-Apache_2.0-green.svg?style=flat
+
+[docs]: https://open-telemetry.github.io/opentelemetry-js
+
+[otel-base]: https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-base
+[otel-exporter-collector]: https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-exporter-collector
+[otel-exporter-jaeger]: https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-exporter-jaeger
+[otel-exporter-prometheus]: https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-exporter-prometheus
+[otel-exporter-stackdriver-trace]: https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-exporter-stackdriver-trace
+[otel-exporter-zipkin]: https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-exporter-zipkin
+[otel-metrics]: https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-metrics
+[otel-node]: https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-node
+[otel-plugin-dns]: https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-plugin-dns
+[otel-plugin-document-load]: https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-plugin-document-load
+[otel-plugin-grpc]: https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-plugin-grpc
+[otel-plugin-http]: https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-plugin-http
+[otel-plugin-https]: https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-plugin-https
+[otel-plugin-ioredis]: https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-plugin-ioredis
+[otel-plugin-mongodb]: https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-plugin-mongodb
+[otel-plugin-mysql]: https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-plugin-mysql
+[otel-plugin-pg-pool]: https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-plugin-postgres/opentelemetry-plugin-pg-pool
+[otel-plugin-pg]: https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-plugin-postgres/opentelemetry-plugin-pg
+[otel-plugin-redis]: https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-plugin-redis
+[otel-plugin-xml-http-request]: https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-plugin-xml-http-request
+[otel-shim-opentracing]: https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-shim-opentracing
+[otel-tracing]: https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-tracing
+[otel-web]: https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-web
+[otel-types]: https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-types
+[otel-core]: https://github.com/open-telemetry/opentelemetry-js/tree/master/packages/opentelemetry-core

RELEASING.md

@@ -2,14 +2,42 @@
 
 This document explains how to publish all OT modules at version x.y.z. Ensure that you’re following semver when choosing a version number.
 
+Release Process:
+
+* [Update to latest locally](#update-to-latest-locally)
+* [Create a new branch](#create-a-new-branch)
+* [Prepare each package for release](#prepare-each-package-for-release)
+* [Use the Changelog to create a GitHub Release](#use-the-changelog-to-create-a-github-release)
+* [Create a new PR](#create-a-new-pr)
+* [Merge and pull](#merge-and-pull)
+* [Publish all packages](#publish-all-packages)
+* [Publish the GitHub Release](#publish-the-github-release)
+* [Update CHANGELOG](#update-changelog)
+
+## Update to latest locally
+
+Use `git fetch` and `git checkout origin/master` to ensure you’re on the latest commit. Make sure you have no unstaged changes. Ideally, also use `git clean -dfx` to remove all ignored and untracked files.
+
+## Create a new branch
+
+Create a new branch called `x.y.z-proposal` from the current commit.
+
+## Prepare each package for release
+
+Decide on the next `major.minor.patch` release number based on [semver](http://semver.org/) guidelines.
+
+* Use `npm install` command to initialize all package directories
+* Use `lerna publish --skip-npm --no-git-tag-version --no-push` to bump the version in all `package.json`
+* Use `npm run bootstrap` to generate latest `version.ts` files
+
 ## Use the Changelog to create a GitHub Release
 
 ### Generate the changelog with lerna
 
 Since we use `lerna`, we can use [lerna-changelog](https://github.com/lerna/lerna-changelog#lerna-changelog)
 
 #### How to use
-Pass your [github token](https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line) to generate the changelog automatically. 
+Pass your [github token](https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line) to generate the changelog automatically.
 For security reasons, when you create a Github token, select the permissions: under **repo**, select **Access public repositories**, **commit status**.
 
 In your terminal, execute the following command:
@@ -41,3 +69,43 @@ GITHUB_AUTH=xxxxx lerna-changelog --from=v1.0.0 --to=v2.0.0
 #### Update Changelog file
 
 From what `lerna-changelog` has generated, starts new Unreleased label. Follow the example set by recent Released label.
+
+On [GitHub Releases](https://github.com/open-telemetry/opentelemetry-js/releases), follow the example set by recent releases to populate a summary of changes, as well as a list of commits that were applied since the last release. Save it as a draft, don’t publish it. Don’t forget the tag -- call it `vx.y.z` and leave it pointing at `master` for now (this can be changed as long as the GitHub release isn’t published).
+
+## Create a new PR
+
+Create a pull request titled `chore: x.y.z release proposal`. The commit body should just be a link to the draft notes. Someone who can access draft notes should approve it, looking in particular for test passing, and whether the draft notes are satisfactory.
+
+## Merge and pull
+
+Merge the PR, and pull the changes locally (using the commands in the first step). Ensure that `chore: x.y.z release proposal` is the most recent commit.
+
+## Publish all packages
+
+Go into each directory and use `npm publish` (requires permissions) to publish the package. You can use the following script to automate this.
+
+```bash
+#!/bin/bash
+
+for dir in $(ls packages); do
+ pushd packages/$dir
+ npm publish
+ popd
+done
+```
+
+Check your e-mail and make sure the number of “you’ve published this module” emails matches the number you expect.
+
+## Publish the GitHub Release
+Publish the GitHub release, ensuring that the tag points to the newly landed commit corresponding to release proposal `x.y.z`.
+
+## Update CHANGELOG
+
+* After releasing is done, update the [CHANGELOG.md](https://github.com/open-telemetry/opentelemetry-js/blob/master/CHANGELOG.md) and start new Unreleased label.
+* Create a new commit with the exact title: `Post Release: update CHANGELOG.md`.
+* Go through PR review and merge it to GitHub master branch.
+
+
+## Known Issues
+
+* The `examples/` and `getting-started/` folders are not part of lerna packages, we need to manually bump the version in `package.json`.