docs: update docs for the GA

README.md

@@ -15,10 +15,10 @@ The Splunk distribution of [OpenTelemetry JS](https://github.com/open-telemetry/
 
 This Splunk distribution comes with the following defaults:
 
-- [W3C context propagation](https://www.w3.org/TR/trace-context).
+- [W3C tracecontext and baggage propagation](https://www.w3.org/TR/trace-context).
 - [OTLP exporter](https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-exporter-collector-proto)
-  configured to send spans to a locally running [OpenTelemetry Collector](https://github.com/open-telemetry/opentelemetry-collector)
-  (`http://localhost:55681/v1/traces`).
+  configured to send spans to a locally running [OpenTelemetry Collector](https://github.com/open-telemetry/opentelemetry-collector) over HTTP
+  (default endpoint: `http://localhost:55681/v1/traces`).
 - Unlimited default limits for [configuration options](#trace-configuration) to
   support full-fidelity traces.
 
@@ -28,10 +28,10 @@ the SignalFx Tracing Library for JS](./MIGRATING.md).
 
 > :construction: This project is currently in **BETA**. It is **officially supported** by Splunk. However, breaking changes **MAY** be introduced.
 
-## Getting Started
+## Get started
 
 Assuming the default Splunk APM setup with [OpenTelemetry Collector](https://github.com/open-telemetry/opentelemetry-collector) running on localhost. If you're running a
-different setup, refer to the [configuration options](#env-config-options) below to customize trace export endpoint
+different setup, refer to the [configuration options](./docs/advanced-config.md) to customize trace export endpoint
 and other behaviour.
 
 1. Install `@splunk/otel` package
@@ -54,7 +54,7 @@ npm install @opentelemetry/instrumentation-http --save
 
 You can find a list of instrumentation packages supported out of the box [here](#default-instrumentation-packages).
 
-You can also install additional packages and use them as described [here](#custom-instrumentation-packages).
+You can also install additional packages and use them as described in [Plugins](./docs/plugins.md).
 
 
 3. Run node app with `-r @splunk/otel/instrument` CLI argument
@@ -66,32 +66,14 @@ node -r @splunk/otel/instrument app.js
 
 That's it - the telemetry data is not sent to the locally running Opentelemetry Collector! You can also instrument your app with code as described [here](#instrument-with-code).
 
-### Splunk APM
+### Send data directly to Splunk APM
 
 In order to send traces directly to Splunk APM, you need to:
 
 1. Set `OTEL_EXPORTER_OTLP_ENDPOINT` to
    `https://ingest.<realm>.signalfx.com/v2/trace/otlp` where `realm` is your
    Splunk APM realm e.g, `https://ingest.us0.signalfx.com/v2/trace/otlp`.
 2. Set `SPLUNK_ACCESS_TOKEN` to your Splunk APM access token.
-
-## Configuration options<a name="env-config-options"></a>
-
-| Environment variable                 | Config Option                 | Default value                         | Notes
-| -----------------------------        | ----------------------------- | ------------------------------------- | ----
-| OTEL_EXPORTER_OTLP_ENDPOINT          | endpoint                      | `http://localhost:55681/v1/traces`    | The OTLP endpoint to export to. Only OTLP over HTTP is supported.
-| OTEL_TRACES_EXPORTER                 | tracesExporter                | `otlp`                                | Chooses the exporter. Shortcut for setting `spanExporterFactory`. One of [`otlp`, `jaeger-thrift-http`, `jaeger-thrift-splunk`]. See [`TracesExporter`](./src/options.ts).
-| OTEL_PROPAGATORS                     | propagators                   | `tracecontext,baggage`                | Comma-delimited list of propagators to use. Valid keys: `baggage`, `tracecontext`, `b3multi`, `b3`.
-| OTEL_SERVICE_NAME                    | serviceName                   | `unnamed-node-service`                | The service name of this Node service.
-| SPLUNK_ACCESS_TOKEN                  | acceessToken                  |                                       | The optional access token for exporting signal data directly to SignalFx API.
-| SPLUNK_MAX_ATTR_LENGTH               | maxAttrLength                 | 1200                                  | Maximum length of string attribute value in characters. Longer values are truncated.
-| SPLUNK_TRACE_RESPONSE_HEADER_ENABLED | serverTimingEnabled           | `true`                                | Enable injection of `Server-Timing` header to HTTP responses.
-| SPLUNK_LOGS_INJECTION                | logInjectionEnabled           | `false`                               | Enable injecting of trace ID, span ID and service name to log records. Please note that the corresponding logging library instrumentation needs to be installed.
-| OTEL_RESOURCE_ATTRIBUTES             |                               |                                       | Comma-separated list of resource attributes added to every reported span. <details><summary>Example</summary>`key1=val1,key2=val2`</details>
-| OTEL_TRACE_ENABLED                   |                               | `true`                                | Globally enables tracer creation and auto-instrumentation.
-
-More details on config options can be seen [here](#config-options)
-
 ## Automatically instrument an application
 
 You can use node's `-r` CLI flag to pre-load the instrumentation module and automatically instrument your NodeJS application.
@@ -126,66 +108,10 @@ startTracing({
 });
 ```
 
-Please note that `startTracing` is destructive to Open Telemetry API globals. We provide the `stopTracing` method, but
+Note that `startTracing` is destructive to Open Telemetry API globals. We provide the `stopTracing` method, but
 it won't revert to OTel API globals set before `startTracing` was run, it will only disable globals, which
 `startTracing` set.
 
-### All config options<a name="config-options"></a>
-
-`startTracing()` accepts an optional argument to pass down configuration. The argument must be an Object and may contain any of the following keys.
-
-- `endpoint`: corresponds to the `OTEL_EXPORTER_OTLP_ENDPOINT` environment variable. Defaults to `http://localhost:55681/v1/traces`. Configures the http endpoint to which all spans will be exported.
-
-- `serviceName`: corresponds to the `OTEL_SERVICE_NAME` environment variable. Defaults to `unnamed-node-service`. Configures the service name of the instrumented node service. The name is added to all spans as an attribute.
-
-- `accessToken`: corresponds to the `SPLUNK_ACCESS_TOKEN` environment variable. Configures the access token that should be used to authenticate with the span exporter http endpoint. Used when exporting directly to Splunk APM from a Node service.
-
-- `maxAttrLength`: corresponds to the `SPLUNK_MAX_ATTR_LENGTH` environment variable. Defaults to `1200`. Configures the maximum length any span attribute value can have. Values longer than the specified length will be truncated.
-
-- `serverTimingEnabled`: corresponds to the `SPLUNK_SERVER_TIMING_ENABLED` environment variable. Defaults to false. Enables injection of `Server-Timing` header to responses.
-
-- `logInjectionEnabled`: corresponds to the `SPLUNK_LOGS_INJECTION` environment variable. Defaults to false. Injects trace ID, span ID and service name to the log records. Service version or deployment environment will be injected if available in the [configured resource](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/semantic_conventions/README.md). Supported logging libraries: bunyan, pino, winston.
-
-- `tracerConfig`: a JS object that is merged into the default tracer config replacing any existing keys and is passed on to the tracer provider during initialization. This can be used to customize the tracer provider or tracer. Must satisfy [`TracerConfig` interface](https://github.com/open-telemetry/opentelemetry-js/blob/71ba83a0dc51118e08e3148c788b81fe711003e7/packages/opentelemetry-tracing/src/types.ts#L26)
-
-- `spanExporterFactory`: A function that accepts the options passed to startTracing function and returns a new instance of SpanExporter. When set, this function will be used to create a new exporter and the returned exporter will be used in the pipeline.
-
-- `spanProcessorFactory`: A function that accepts the options passed to startTracing function and returns a SpanProcessor instance or an array of SpanProcessor instances. When set, this function is be used to create one or more span processor(s). The returned processors are added to the global tracer provider and configured to process all spans generated by any tracer provider by the global provider. The function is responsible for creating a new span exporter and using it with each processor it creates. It may call `options.spanExporterFactory(options)` to create a new exporter as configured by the user.
-
-- `propagatorFactory`: A function that accepts the options passed to startTracing function and returns a new instance of a TextMapPropagator. Defaults to a composite propagator comprised of W3C [Trace Context](https://www.w3.org/TR/trace-context/) and [Baggage](https://w3c.github.io/baggage/) propagators.
-
-- `instrumentations`: defaults to the list of instrumentation listed [below](#default-instrumentation-packages). Can be used to enable additional instrumentation packages. Refer examples [here](#custom-instrumentation-packages)
-
-## Using additional instrumentation plugins<a name="custom-instrumentation-packages"></a>
-
-If you setup tracing manually by calling the `startTracing()` method, you can use custom or 3rd party instrumentations as long as they implement the [OpenTelemetry JS Instrumentation interface](https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-instrumentation). Custom instrumentations can be enabled by passing them to the `startTracing()` method as follows:
-
-```js
-const { startTracing } = require('@splunk/otel');
-
-startTracing({
-  instrumentations: [
-    new MyCustomInstrumentation(),
-    new AnotherInstrumentation(),
-  ]
-});
-```
-
-You can also add the default set of instrumentation to the list as follows:
-
-```js
-const { startTracing } = require('@splunk/otel');
-const { getInstrumentations } = require('@splunk/otel/lib/instrumentations');
-
-startTracing({
-  instrumentations: [
-    ...getInstrumentations(),
-    new MyCustomInstrumentation(),
-    new AnotherInstrumentation(),
-  ]
-});
-```
-
 ## Default Instrumentation Packages<a name="default-instrumentation-packages"></a>
 
 By default the following instrumentations will automatically be enabled if they are installed. In order to use
@@ -221,12 +147,11 @@ If log injection is enabled, the corresponding logging library package will need
 @opentelemetry/instrumentation-winston
 ```
 
-You can find more instrumentation packages over at the [OpenTelemetry Registry](https://opentelemetry.io/registry/?language=js) and enable them manually
-as described above.
+You can find more instrumentation packages over at the [OpenTelemetry Registry](https://opentelemetry.io/registry/?language=js) and enable them manually as described above.
 
 ## Troubleshooting
 
-TODO:
+For troubleshooting issues with the Splunk distribution of OpenTelemetry JS, see [Troubleshooting](./docs/troubleshooting.md).
 
 # License and versioning
 

docs/advanced-config.md

@@ -0,0 +1,44 @@
+# Advanced Configuration
+
+The agent can be configured in the following ways:
+
+- Environment variables (also within `.env` files)
+
+   For example: `export OTEL_SERVICE_NAME='test-service'`
+
+- Arguments passed to the `startTracing()` function
+
+   For example: `startTracing({ serviceName: 'my-node-service', });`
+
+> Code arguments take precedence over the corresponding environment variables.
+
+## List of settings
+
+The following table contain the configuration options supported by this distribution.
+
+| Environment variable                 | Config Option                 | Default value                         | Notes
+| -----------------------------        | ----------------------------- | ------------------------------------- | ----
+| OTEL_EXPORTER_OTLP_ENDPOINT          | endpoint                      | `http://localhost:55681/v1/traces`    | The OTLP endpoint to export to. Only OTLP over HTTP is supported.
+| OTEL_TRACES_EXPORTER                 | tracesExporter                | `otlp`                                | Chooses the exporter. Shortcut for setting `spanExporterFactory`. One of [`otlp`, `jaeger-thrift-http`, `jaeger-thrift-splunk`]. See [`TracesExporter`](./src/options.ts).
+| OTEL_PROPAGATORS                     | propagators                   | `tracecontext,baggage`                | Comma-delimited list of propagators to use. Valid keys: `baggage`, `tracecontext`, `b3multi`, `b3`.
+| OTEL_SERVICE_NAME                    | serviceName                   | `unnamed-node-service`                | The service name of this Node service.
+| SPLUNK_ACCESS_TOKEN                  | accessToken                   |                                       | The optional access token for exporting signal data directly to SignalFx API.
+| SPLUNK_MAX_ATTR_LENGTH               | maxAttrLength                 | 1200                                  | Maximum length of string attribute value in characters. Longer values are truncated.
+| SPLUNK_TRACE_RESPONSE_HEADER_ENABLED | serverTimingEnabled           | `true`                                | Enable injection of `Server-Timing` header to HTTP responses.
+| SPLUNK_LOGS_INJECTION                | logInjectionEnabled           | `false`                               | Enable injecting of trace ID, span ID and service name to log records. Please note that the corresponding logging library instrumentation needs to be installed.
+| OTEL_RESOURCE_ATTRIBUTES             |                               |                                       | Comma-separated list of resource attributes added to every reported span. <details><summary>Example</summary>`key1=val1,key2=val2`</details>
+| OTEL_TRACE_ENABLED                   |                               | `true`                                | Globally enables tracer creation and auto-instrumentation.
+
+## Additional config options
+
+The following config options can be set by passing them as arguments to `startTracing()`.
+
+- `tracerConfig`: A JS object that is merged into the default tracer config replacing any existing keys. It's passed to the tracer provider during initialization. This can be used to customize the tracer provider or tracer. Must satisfy [`TracerConfig` interface](https://github.com/open-telemetry/opentelemetry-js/blob/71ba83a0dc51118e08e3148c788b81fe711003e7/packages/opentelemetry-tracing/src/types.ts#L26)
+
+- `spanExporterFactory`: A function that accepts the options passed to the startTracing function. Returns a new instance of SpanExporter. When set, this function is used to create a new exporter and the returned exporter will be used in the pipeline.
+
+- `spanProcessorFactory`: Returns a SpanProcessor instance or an array of SpanProcessor instances. When set, this function is be used to create one or more span processors. The returned processors are added to the global tracer provider and configured to process all spans generated by any tracer provider by the global provider. The function creates a new span exporter and uses it with each processor it creates. It may call `options.spanExporterFactory(options)` to create a new exporter as configured by the user.
+
+- `propagatorFactory`: A function that returns a new instance of a TextMapPropagator. Defaults to a composite propagator comprised of W3C [Trace Context](https://www.w3.org/TR/trace-context/) and [Baggage](https://w3c.github.io/baggage/) propagators.
+
+- `instrumentations`: Can be used to enable additional instrumentation packages.

docs/plugins.md

@@ -0,0 +1,29 @@
+# Using additional instrumentation plugins
+
+If you set up tracing manually by calling the `startTracing()` method, you can use custom or third-party instrumentations as long as they implement the [OpenTelemetry JS Instrumentation interface](https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-instrumentation). Custom instrumentations can be enabled by passing them to the `startTracing()` method as follows:
+
+```js
+const { startTracing } = require('@splunk/otel');
+
+startTracing({
+  instrumentations: [
+    new MyCustomInstrumentation(),
+    new AnotherInstrumentation(),
+  ]
+});
+```
+
+You can also add the default set of instrumentation to the list as follows:
+
+```js
+const { startTracing } = require('@splunk/otel');
+const { getInstrumentations } = require('@splunk/otel/lib/instrumentations');
+
+startTracing({
+  instrumentations: [
+    ...getInstrumentations(),
+    new MyCustomInstrumentation(),
+    new AnotherInstrumentation(),
+  ]
+});
+```

examples/express/README.md

@@ -81,9 +81,9 @@ There is an exmample [.env](./.env.collector) file included, which following com
 # make sure the collector is running
 docker run --name otel-collector -d -p 55681:55681 otel/opentelemetry-collector
 # run the example server
-npm run server:collecor
+npm run server:collector
 # in a separate terminal:
-npm run client:collecor
+npm run client:collector
 ```
 
 ### Instrumented via legacy OpenTracing SDK