Merge branch 'master' into fix_flow_errors

CONTRIBUTING.md

@@ -0,0 +1,39 @@
+# Want to contribute?
+
+Great! That's why this is an open source project. We use this project in our infrastructure at Uber, and we hope that it's useful to others as well.
+
+Before you get started, here are some suggestions:
+
+ - Check open issues for what you want.
+ - If there is an open issue, comment on it. Otherwise open an issue describing your bug or feature with use cases.
+ - Before undertaking a major change, please discuss this on the issue. We'd hate to see you spend a lot of time working on something that conflicts with other goals or requirements that might not be obvious.
+ - Write code to fix the problem, then open a pull request with tests and documentation.
+ - The pull requests gets reviewed and then merged assuming there are no problems.
+ - A new release version gets cut.
+
+## Developing
+
+ 1. `git submodule update --init`
+ 2. `npm install`
+ 3. `npm test`
+ 4. `make build-node`
+
+## Licencing
+
+ - Every file must have a licence block at the top. This is enforced using `uber-licence`
+ - If you contribute to a file in this project and are not an Uber employee, then you should
+add your name to the copyright section of the licence file.
+ - Work that you contribute must be your own.
+
+## Releases
+
+Declaring formal releases requires peer review.
+
+ - A reviewer of a pull request should recommend a new version number (patch, minor or major).
+ - Once your change is merged feel free to bump the version as recommended by the reviewer.
+ - A new version number should not be cut without peer review unless done by the project maintainer.
+
+### Cutting a new version
+
+TBD
+

README.md

@@ -1,4 +1,4 @@
-[![Build Status][ci-img]][ci] [![Coverage Status][cov-img]][cov]
+[![Build Status][ci-img]][ci] [![Coverage Status][cov-img]][cov] [![NPM Published Version][npm-img]][npm]
 
 # Jaeger Bindings for Javascript OpenTracing API
 
@@ -8,14 +8,46 @@ with Zipkin-compatible data model.
 
 **This project is currently WIP and not ready for use. Do not use it until this notice goes away.**
 
-## Developing
+## Contributing
+
+Please see [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+### Debug Traces (Forced Sampling)
+
+#### Programmatically
+
+The OpenTracing API defines a `sampling.priority` standard tag that
+can be used to affect the sampling of a span and its children:
+
+```javascript
+span.setTag(opentracing_tags.SAMPLING_PRIORITY, 1);
+```
+
+#### Via HTTP Headers
+
+Jaeger Tracer also understands a special HTTP Header `jaeger-debug-id`,
+which can be set in the incoming request, e.g.
+
+```sh
+curl -H "jaeger-debug-id: some-correlation-id" http://myhost.com
+```
+
+When Jaeger sees this header in the request that otherwise has no
+tracing context, it ensures that the new trace started for this
+request will be sampled in the "debug" mode (meaning it should survive
+all downsampling that might happen in the collection pipeline), and the 
+root span will have a tag as if this statement was executed:
+
+```javascript
+span.setTag("jaeger-debug-id", "some-correlation-id");
+```
+
+This allows using Jaeger UI to find the trace by this tag.
 
- 1. `git submodule update --init`
- 2. `npm install`
- 3. `npm test`
- 4. `make build-node`
 
   [ci-img]: https://travis-ci.org/uber/jaeger-client-node.svg?branch=master
   [cov-img]: https://coveralls.io/repos/github/uber/jaeger-client-node/badge.svg?branch=master
+  [npm-img]: https://badge.fury.io/js/jaeger-client.svg
   [ci]: https://travis-ci.org/uber/jaeger-client-node
-  [cov]: https://coveralls.io/github/uber/jaeger-client-node?branch=master
+  [cov]: https://coveralls.io/github/uber/jaeger-client-$node?branch=master
+  [npm]: https://www.npmjs.com/package/jaeger-client