docs: update readme

packages/opentelemetry-propagator-b3/README.md

@@ -6,7 +6,11 @@
 [![devDependencies][devdependencies-image]][devdependencies-url]
 [![Apache License][license-image]][license-image]
 
-OpenTelemetry B3 propagator provides HTTP header propagation for systems that are using B3 HTTP header format. See the [B3 specification][b3-spec] for complete details.
+The OpenTelemetry b3 propagator package provides multiple propagator
+implementations for systems using the b3 context format. See the
+[b3 specification][b3-spec] for complete details.
+
+## B3 Formats
 
 Single-Header Format:
 
@@ -27,6 +31,8 @@ X-B3-Sampled: {SamplingState}
 
   - Required
   - Encoded as 32 or 16 lower-hex characters
+  - 16 character traceIds will be converted to 32 characters by left-padding
+    with 0s to conform with the [OpenTelemetry specification][otel-spec-id-format]
 
 - {SpanId}
 
@@ -60,17 +66,85 @@ X-B3-Sampled: {SamplingState}
   - Optional
   - Debug is encoded as `X-B3-Flags`: 1. Absent or any other value can be ignored. Debug implies an accept decision, so don't also send the `X-B3-Sampled` header.
 
-Example of usage:
+## Propagator Implementations
+
+### B3Propagator
+
+The default `B3Propagator` implements b3 propagation according to the
+[OpenTelemetry specification][otel-b3-requirements]. It extracts b3 context
+from multi and single header encodings and injects context using the
+single-header b3 encoding. The inject encoding can be changed to multi-header
+via configuration.
+
+Example usage (default):
 
 ```javascript
-const { NodeTracerProvider } = require('@opentelemetry/node');
+const api = require('@opentelemetry/api');
 const { B3Propagator } = require('@opentelemetry/propagator-b3');
 
-const provider = new NodeTracerProvider();
-provider.register({
-  // Use B3 propagator
-  propagator: new B3Propagator(),
-});
+api.propagation.setGlobalPropagator(new B3Propagator());
+```
+
+Example usage (specify inject encoding):
+
+```javascript
+const api = require('@opentelemetry/api');
+const { B3Propagator } = require('@opentelemetry/propagator-b3');
+
+api.propagation.setGlobalPropagator(
+  new B3Propagator({ injectEncoding: B3InjectEncoding.MULTI_HEADER })
+);
+```
+
+### B3SinglePropagator
+
+If a distributed system only needs support for the b3 single-header
+encoding it can use the `B3SinglePropagator` directly.
+
+Example usage:
+
+```javascript
+const api = require('@opentelemetry/api');
+const { B3SinglePropagator } = require('@opentelemetry/propagator-b3');
+
+api.propagation.setGlobalPropagator(new B3SinglePropagator());
+```
+
+### B3MultiPropagator
+
+If a distributed system only needs support for the b3 multi-header
+encoding it can use the `B3MultiPropagator` directly.
+
+Example usage:
+
+```javascript
+const api = require('@opentelemetry/api');
+const { B3MultiPropagator } = require('@opentelemetry/propagator-b3');
+
+api.propagation.setGlobalPropagator(new B3MultiPropagator());
+```
+
+### CompositePropagator
+
+If a distributed system needs to support both single and multiple header
+encodings for inject and extract the `B3SinglePropagator` and
+`B3MultiPropagator` can be used in conjunction with a `CompositePropagator`.
+
+Example usage:
+
+```javascript
+const api = require('@opentelemetry/api');
+const { CompositePropagator } = require('@opentelemetry/core');
+const {
+  B3SinglePropagator,
+  B3MultiPropagator,
+} = require('@opentelemetry/propagator-b3');
+
+api.propagation.setGlobalPropagator(
+  new CompositePropagator({
+    propagators: [new B3SinglePropagator(), new B3MultiPropagator()],
+  })
+);
 ```
 
 ## Useful links
@@ -94,3 +168,5 @@ Apache 2.0 - See [LICENSE][license-url] for more information.
 [npm-url]: https://www.npmjs.com/package/@opentelemetry/propagator-jaeger
 [npm-img]: https://badge.fury.io/js/%40opentelemetry%2Fpropagator-jaeger.svg
 [b3-spec]: https://github.com/openzipkin/b3-propagation
+[otel-b3-requirements]: https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/context/api-propagators.md#b3-requirements
+[otel-spec-id-format]: https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#retrieving-the-traceid-and-spanid