Merge 5967f37 into a836170

CHANGELOG.rst

@@ -3,10 +3,27 @@
 History
 -------
 
+0.12.1 (2016-08-23)
+-------------------
+
+ **Contains API breaking changes for both library users and tracing implementations**
+
+- The package no longer exports the singleton, global tracer by default. `globalTracer()` should be used to access the global tracer
+- Implementation no longer use a `TracerImp` object. Implementations should instead subclass from `opentracing.Tracer`, `opentracing.Span`, etc.
+- The removal of the `TracerImp` object implies there is no longer an `imp()` method. Implementation-specific methods now exist in undifferentiated form on the tracer object.  Note: the OpenTracing library no longer forces the user to be explicit when calling implementation-specific methods; this has the downside that it is less obvious when an application becomes dependent on a specific tracing implementation.
+- `initNewTracer()` has been removed. The Tracer implementation object should be created directly by the library user.
+- The default no-op `Tracer.extract()` implementation now returns an empty SpanContext rather than null
+
+*Non-breaking changes*
+
+- A `MockTracer` implementation has been added to the source code
+- Adds a naive example, runnable via `make example`
+
+
 0.12.0 (2016-08-22)
 -------------------
 
-* Renamed the browser global symbol from `Tracer` to `opentracing`
+- Renamed the browser global symbol from `Tracer` to `opentracing`
 
 0.10.3 (2016-06-12)
 -------------------

Makefile

@@ -63,6 +63,13 @@ test: build
 	node node_modules/eslint/bin/eslint.js --color src
 	npm test
 
+# A target that runs the unit tests without code coverage testing, as the code
+# coverage testing throws off the source code line number information - making
+# failures more difficult to debug.
+.PHONY: test-no-coverage
+test-no-coverage: build
+	NODE_ENV=debug node ./node_modules/.bin/_mocha test/unittest.js --check-leaks --color
+
 .PHONY: test_all
 test_all: build
 	scripts/docker_test.sh latest
@@ -72,3 +79,7 @@ test_all: build
 	scripts/docker_test.sh 4.4
 	scripts/docker_test.sh 4.0
 	scripts/docker_test.sh 0.12
+
+.PHONY: example
+example: build
+	NODE_ENV=debug node ./lib-debug/examples/demo/demo.js

README.md

@@ -17,13 +17,39 @@ Install the package using `npm`:
 npm install --save opentracing
 ```
 
+### Example
+
+The package contains a example using a naive `MockTracer` implementation. To run the example:
+
+```bash
+make example
+```
+
+The output should look something like:
+
+```
+Spans:
+    parent_span - 1521ms
+        tag 'custom':'tag value'
+        tag 'alpha':'1000'
+    child_span - 503ms
+        tag 'alpha':'200'
+        tag 'beta':'50'
+```
+
+### Code snippet
+
 In your JavaScript code, add instrumentation to the operations to be tracked. This is composed primarily of using "spans" around operations of interest and adding log statements to capture useful data relevant to those operations.
 
 ```js
 var http = require('http');
-var Tracer = require('opentracing');
+var opentracing = require('opentracing');
+
+// NOTE: the default OpenTracing tracer does not record any tracing information.
+// Replace this line with the tracer implementation of your choice.
+var tracer = new opentracing.Tracer();
 
-var span = Tracer.startSpan('http_request');
+var span = tracer.startSpan('http_request');
 var opts = {
     host : 'example.com',
     method: 'GET',
@@ -46,26 +72,32 @@ http.request(opts, function (res) {
 }).end();
 ```
 
-The default behavior of the `opentracing` package is to act as a "no-op" implementation.
-
-To capture and make the tracing data actionable, the `Tracer` object should be initialized with the OpenTracing implementation of your choice as in the pseudo-code below:
+As noted in the source snippet, the default behavior of the `opentracing` package is to act as a "no op" implementation. To capture and make the tracing data actionable, the `tracer` object should be initialized with the OpenTracing implementation of your choice as in the pseudo-code below:
 
 ```js
-var Tracer = require('opentracing');
-var TracingBackend = require('tracing-implementation-of-your-choice');
-
-Tracer.initGlobalTracer(TracingBackend.create());
+var CustomTracer = require('tracing-implementation-of-your-choice');
+var tracer = new CustomTracer();
 ```
 
-*Note: the underlying implementation object is shared between all inclusions of the `opentracing` package, so `initGlobalTracer` needs to only be called once during initialization.*
-
 ### Usage in the browser
 
 The package contains two bundles built with webpack that can be included using a standard `<script>` tag. The library will be exposed under the global `opentracing` symbol:
 
 * `dist/opentracing-browser.min.js` - minified, no runtime checks
 * `dist/opentracing-browser.js` - debug version with runtime checks
 
+### Global tracer
+
+The library also provides a global singleton tracer for convenience. This can be set and accessed via the following:
+
+```javascript
+opentracing.initGlobalTracer(new CustomTracer());
+
+var tracer = opentracing.globalTracer();
+```
+
+Note: `globalTracer()` returns a wrapper on the actual tracer object. This is done for convenience of use as it ensures that the function will always return a non-null object.  This can be helpful in cases where it is difficult or impossible to know precisely when `initGlobalTracer` is called (for example, when writing a utility library that does not control the initialization process).  For more precise control, individual `Tracer` objects can be used instead of the global tracer.
+
 ### Node.js debug version
 
 ```javascript
@@ -78,25 +110,24 @@ Requiring `opentracing/debug` will include a version of the library with additio
 
 There is a hosted copy of the current generated [ESDoc API Documentation here](https://doc.esdoc.org/github.com/opentracing/opentracing-javascript/).
 
-## Development Information
+## Contributing & developer information
 
-*I.e., information for developers working on this package.*
+See the [OpenTracing website](http://opentracing.io) for general information on contributing to OpenTracing.
 
-#### Building the library
+The project is built using a `Makefile`. Run:
 
 * `make build` creates the compiled, distributable code
 * `make test` runs the tests
 
-## JavaScript OpenTracing Implementations
-
-*I.e. information for developers wanting to create an OpenTracing-compatible JavaScript implementation.*
+## OpenTracing tracer implementations
 
-The API layer uses a [bridge pattern](https://en.wikipedia.org/wiki/Bridge_pattern) to pass work to the specific tracing implementation. The indirection allows the API layer to enforce greater API conformance and standardization across implementations (especially in debug builds), which helps keep instrumented code more portable across OpenTracing implementations.
+*This section is intended for developers wishing to* ***implement their own tracers***. *Developers who simply wish to* ***use OpenTracing*** *can safely ignore this information.*
 
-The "implementation API" - i.e. the interface the API layer expects to be able to call on the implementation - is a proper subset of the API layer itself. The surface area of the implementation API has been reduced in the case where the an API layer method (usually a convenience method of some form) can be expressed in terms of another more general method. For example, `logEvent` can be expressed as a `log` call, therefore the implementation only needs to implement `log`.
+Implementations can subclass the `Tracer`, `Span`, `SpanContext`, and other OpenTracing API classes to build their own implementation. The derived classes can implement the set of underscore-prefixed methods called out in the source code (for example, `Tracer._startSpan` rather than `Tracer.startSpan`). By implementing these methods, the derived classes with automatically pick up "common" code from the base classes that won't vary between implementations. This includes argument normalization and conveniences such as only having to implement `Tracer._addTags` rather than both `Tracer.setTag` and `Tracer.addTags` (since the two methods are effectively map to the same functionality).  Implementors are encouraged to use this approach as it affords the OpenTracing library a opportunity to enforce the call semantics of the API.
 
-For truly implementation-dependent methods, the JavaScript API layer *does* expose `imp()` methods on each major type to allow the implementations to be accessed directly. Use of implementation-dependent methods is discouraged as it immediately makes instrumented code no longer portable.  However, the `imp()` call does at least call attention to deviations from the standard API without making implementation-dependent calls impossible.
+Implementations can of course directly override the API methods (i.e. override `Tracer.startSpan` rather than `Tracer._startSpan`), if desired. This works correctly but requires more code to be written by the implementation.
 
+An minimal example tracer is provided in the `src/mock_tracer` directory of the source code.
 
   [ci-img]: https://travis-ci.org/opentracing/opentracing-javascript.svg?branch=master
   [cov-img]: https://coveralls.io/repos/github/opentracing/opentracing-javascript/badge.svg?branch=master