Docs changes for GA

CHANGELOG.md

@@ -50,7 +50,7 @@ Tue, 07 Sep 2021 12:05:40 GMT
 
 ### Changed
 
-- Context management should not work properly on older versions of NodeJS (<14.8).
+- Context management should not work properly on older versions of Node.js (<14.8).
   ([#53](https://github.com/signalfx/splunk-otel-js/pull/53))
 
 

CONTRIBUTING.md

@@ -34,6 +34,17 @@ When filing an issue, please do *NOT* include:
 
 See [SECURITY.md](SECURITY.md#reporting-security-issues) for detailed instructions.
 
+## Documentation
+
+The Splunk Observability documentation is hosted on https://docs.splunk.com/Observability,
+which contains all the prescriptive guidance for Splunk Observability products. 
+Prescriptive guidance consists of step-by-step instructions, conceptual material,
+and decision support for customers. Reference documentation and development 
+documentation is hosted on this repository.
+
+You can send feedback about Splunk Observability docs by clicking the Feedback 
+button on any of our documentation pages.
+
 ## Contributing via Pull Requests
 
 Contributions via Pull Requests (PRs) are much appreciated. Before sending us a

MIGRATING.md

@@ -1,21 +1,21 @@
-# Migrate from the SignalFx Tracing Library for NodeJS
+# Migrate from the SignalFx Tracing Library for Node.js
 
-The Splunk Distribution of OpenTelemetry for NodeJS replaces the SignalFx Tracing
-Library for NodeJS. If you’re using the SignalFx Tracing Library, migrate to
-the Splunk Distribution of OpenTelemetry for NodeJS to use OpenTelemetry
-instrumentation to send traces to Splunk APM. The Splunk Distribution of
-OpenTelemetry for NodeJS uses OpenTelemetry to instrument applications, which is
-an open-source API to gather telemetry data, and has a smaller footprint.
+The Splunk Distribution of OpenTelemetry for Node.js replaces the SignalFx Tracing
+Library for Node.js. If you’re using the SignalFx Tracing Library, migrate to
+the Splunk Distribution of OpenTelemetry for Node.js to send traces to Splunk 
+Observability Cloud. The Splunk Distribution of OpenTelemetry for Node.js uses 
+OpenTelemetry to instrument applications, which is an open-source API to gather 
+telemetry data, and has a smaller footprint.
 
-Because the SignalFx Tracing Library for NodeJS uses OpenTracing and the Splunk Distribution of OpenTelemetry for NodeJS
-uses OpenTelemetry, the semantic conventions for span names and attributes change when you migrate. For more
-information, see
-[Migrate from OpenTracing to OpenTelemetry](https://docs.signalfx.com/en/latest/apm/apm-getting-started/apm-opentelemetry-collector.html#apm-opentelemetry-migration).
+Because the SignalFx Tracing Library for Node.js uses OpenTracing and the Splunk
+ Distribution of OpenTelemetry for Node.js uses OpenTelemetry, the semantic 
+ conventions for span names and attributes change when you migrate. For more
+information, see [Migrate from OpenTracing to OpenTelemetry](https://docs.signalfx.com/en/latest/apm/apm-getting-started/apm-opentelemetry-collector.html#apm-opentelemetry-migration).
 
 ## Getting help
 
-If you experience any issues following the guide below, or something is unclear, or missing, please don't hesitate to
-open an issue in Github. Any and all ideas for improvements are also welcome.
+If you experience any issues following the guide below, or something is unclear, or missing, don't hesitate to
+open an issue in GitHub. Any and all ideas for improvements are also welcome.
 
 <a name="known-limitations"></a>
 ## Known limitations as compared to SignalFx Tracing Library
@@ -40,7 +40,7 @@ open an issue in Github. Any and all ideas for improvements are also welcome.
 
 ## Requirements
 
-This Splunk Distribution of OpenTelemetry requires Node.js 8.5 or later,
+This Splunk Distribution of OpenTelemetry requires Node.js 8.5 or higher,
 [see more information here](https://github.com/open-telemetry/opentelemetry-js#node-support)
 If you're still using an earlier version of Node.js, continue using the SignalFx Tracing Library for Node.js.
 
@@ -51,15 +51,15 @@ Current effective required Node.js version is: ![node-current](https://img.shiel
 ### Instrumented libraries
 
 With the exception of [explicitly listed limitations](#known-limitations) we aim to support all libraries supported by
-signalfx-nodejs-tracing. To find an equivalent auto-instrumentation open <https://opentelemetry.io/registry/> and for
+signalfx-nodejs-tracing. To find an equivalent autoinstrumentation open <https://opentelemetry.io/registry/> and for
 each instrumentation
 [from `signalfx-nodejs-tracing`'s README](https://github.com/signalfx/signalfx-nodejs-tracing/#requirements-and-supported-software)
 search by the name of the library in the registry.
 
 For example, if you'd like to migrate instrumentation for `mysql`, go to
 [https://opentelemetry.io/registry/?s=**mysql**&component=&language=**js**#](https://opentelemetry.io/registry/?s=mysql&component=&language=js#).
 
-Once you have identified an instrumentation package, **install it** using npm or Yarn.
+Once you have identified an instrumentation package, **install it** using npm or yarn.
 
 - If the package is [on this list](./README.md#default-instrumentation-packages-), it
   will be enabled automatically (**but it won't be installed automatically**).
@@ -70,23 +70,23 @@ Once you have identified an instrumentation package, **install it** using npm or
 
 Rename environment variables:
 
-| OpenTracing environment variable   | OpenTelemetry environment variable   | notes |
-| ---------------------------------- | ------------------------------------ | ----- |
-| SIGNALFX_ACCESS_TOKEN              | SPLUNK_ACCESS_TOKEN                  | |
-| SIGNALFX_SERVICE_NAME              | OTEL_SERVICE_NAME                    | |
-| SIGNALFX_ENDPOINT_URL              | _no direct equivalent_               | see [the notes on endpoint](#endpoint) |
-| SIGNALFX_RECORDED_VALUE_MAX_LENGTH | SPLUNK_MAX_ATTR_LENGTH               | currently not implemented. See [#2403](otel-issue-attr-limits) |
-| SIGNALFX_TRACING_DEBUG             | _no direct equivalent_               | see [instrumentation logs](#instrumentation-logs) |
-| SIGNALFX_SPAN_TAGS                 | OTEL_RESOURCE_ATTRIBUTES             | format needs to be changed to `key1=val1,key2=val2` |
-| SIGNALFX_LOGS_INJECTION            | SPLUNK_LOGS_INJECTION                | |
-| SIGNALFX_LOGS_INJECTION_TAGS       | OTEL_RESOURCE_ATTRIBUTES             | there's no direct equivalent, but values specified in `OTEL_RESOURCE_ATTRIBUTES` will also be used for logs injection |
-| SIGNALFX_ENABLED_PLUGINS           | n/a                                  | see [the README section about instrumentations](./README.md#custom-instrumentation-packages) |
-| SIGNALFX_SERVER_TIMING_CONTEXT     | SPLUNK_TRACE_RESPONSE_HEADER_ENABLED | |
-| SIGNALFX_TRACING_ENABLED           | OTEL_TRACE_ENABLED                   | |
+| OpenTracing environment variable   | OpenTelemetry environment variable     | notes |
+| ---------------------------------- | -------------------------------------- | ----- |
+| SIGNALFX_ACCESS_TOKEN              | SPLUNK_ACCESS_TOKEN                    | |
+| SIGNALFX_SERVICE_NAME              | OTEL_SERVICE_NAME                      | |
+| SIGNALFX_ENDPOINT_URL              | _no direct equivalent_                 | See [the notes on endpoint](#endpoint) |
+| SIGNALFX_RECORDED_VALUE_MAX_LENGTH | OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT | |
+| SIGNALFX_TRACING_DEBUG             | _no direct equivalent_                 | See [Instrumentation logs](#instrumentation-logs) |
+| SIGNALFX_SPAN_TAGS                 | OTEL_RESOURCE_ATTRIBUTES               | Format needs to be changed to `key1=val1,key2=val2` |
+| SIGNALFX_LOGS_INJECTION            | n/a                                    | Logs injection is now enabled by default. |
+| SIGNALFX_LOGS_INJECTION_TAGS       | n/a                                    | |
+| SIGNALFX_ENABLED_PLUGINS           | n/a                                    | see [the README section about instrumentations](./README.md#custom-instrumentation-packages) |
+| SIGNALFX_SERVER_TIMING_CONTEXT     | SPLUNK_TRACE_RESPONSE_HEADER_ENABLED   | |
+| SIGNALFX_TRACING_ENABLED           | OTEL_TRACE_ENABLED                     | |
 
 ### Programmatic configuration
 
-Update these programmatic configuration options:
+Update these programmatic configuration options (passed as arguments to `startTracing()`):
 
 | OpenTracing property     | OpenTelemetry property  | Notes |
 | ------------------------ | ----------------------- | ----- |

README.md

@@ -26,8 +26,6 @@ If you're currently using the SignalFx Tracing Library for Node and want to
 migrate to the Splunk Distribution of OpenTelemetry Node, see [Migrate from
 the SignalFx Tracing Library for JS](./MIGRATING.md).
 
-> This project is currently in **BETA**. It is **officially supported** by Splunk. However, breaking changes **MAY** be introduced.
-
 ## Get started
 
 The following instructions assume that you're sending data to Splunk Observability Cloud using the [OpenTelemetry Collector](https://docs.splunk.com/Observability/gdi/opentelemetry/opentelemetry.html) running on localhost. If you're running a
@@ -74,7 +72,7 @@ In order to send traces directly to Splunk Observability Cloud, you need to:
 2. Set the `SPLUNK_ACCESS_TOKEN` to your Splunk Observability Cloud [access token](https://docs.splunk.com/Observability/admin/authentication-tokens/api-access-tokens.html).
 ## Automatically instrument an application
 
-You can use the `-r` CLI flag to preload the instrumentation module and automatically instrument your NodeJS application.
+You can use the `-r` CLI flag to preload the instrumentation module and automatically instrument your Node.js application.
 For example, if you normally started your application as follows:
 
 ```bash
@@ -87,6 +85,12 @@ Then you can automatically instrument your application by running
 node -r @splunk/otel/instrument index.js
 ```
 
+## Correlate traces and logs
+
+The Splunk Distribution of OpenTelemetry JS can make trace metadata available to many Node.js logging libraries capable of accessing them, like Pino, Winston, and Bunyan. You can use trace metadata to correlate traces with log events, and explore logs in Observability Cloud. 
+
+For more information, see [Correlating traces with logs](./docs/correlate-logs-traces.md).
+
 ## Manually instrument an application<a name="instrument-with-code"></a>
 
 You can also manually instrument your application by adding the following lines before everything else in your application.

docs/README.md

@@ -0,0 +1,3 @@
+The official documentation for this distribution can be found here:
+
+https://docs.splunk.com/Observability/gdi/get-data-in/application/nodejs/get-started.html

docs/advanced-config.md

@@ -1,33 +1,34 @@
+> The official Splunk documentation for this page is [Configure the Splunk Distribution of OTel JS](https://docs.splunk.com/Observability/gdi/get-data-in/application/nodejs/configuration/advanced-nodejs-otel-configuration.html). For instructions on how to contribute to the docs, see [CONTRIBUTING.md](../CONTRIBUTING.md#documentation).
+
 # Advanced Configuration
 
-The agent can be configured in the following ways:
+To configure the Splunk Distribution of OpenTelemetry JS, you can use a combination of environment variables and arguments passed to the `startTracing()` function:
 
-- Environment variables (also within `.env` files)
+- Environment variables
 
    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.
+> `startTracing()` 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.
+| Environment variable                 | Arguments to ``startTracing()`` | 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.
+| OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT | 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.
+| 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
 

docs/correlate-logs-traces.md

@@ -0,0 +1,36 @@
+> The official Splunk documentation for this page is [Connect Node.js trace data with logs](https://docs.splunk.com/Observability/gdi/get-data-in/application/nodejs/instrumentation/connect-traces-logs.html). For instructions on how to contribute to the docs, see [CONTRIBUTING.md](../CONTRIBUTING.md#documentation).
+# Correlating traces with logs
+
+The Splunk Distribution of OpenTelemetry JS automatically injects trace metadata into logs so that Node.js logging libraries can access it. You can use trace metadata to correlate traces with log events and explore logs in Observability Cloud.
+
+## Supported logging libraries
+
+The following logging librares are supported:
+
+- Bunyan
+- Pino
+- Winston
+
+## Available trace data
+
+The following attributes are available for applications instrumented using the Splunk distribution of OpenTelemetry JS:
+
+- Trace information: `trace_id`, `span_id`, and `trace_flags`
+
+The format of each log message depends on the logging library. The following is a sample log message formatted by the Pino library:
+
+```
+   {"level":30,"time":1979374615686,"pid":728570,"hostname":"my_host","trace_id":"f8e261432221096329baf5e62090d856","span_id":"3235afe76b55fe51","trace_flags":"01","url":"/lkasd","msg":"request handler"}
+```
+
+## Enable logs injection
+
+To enable log injection, install the instrumentation package for your logging library:
+
+``
+@opentelemetry/instrumentation-bunyan
+@opentelemetry/instrumentation-pino
+@opentelemetry/instrumentation-winston
+``
+
+To inject trace data into formatted logs, refer to the documentation of each library.

docs/plugins.md

@@ -1,3 +1,5 @@
+> The official Splunk documentation for this page is [Instrument a Node application automatically](https://docs.splunk.com/Observability/gdi/get-data-in/application/nodejs/instrumentation/instrument-nodejs-application.html). For instructions on how to contribute to the docs, see [CONTRIBUTING.md](../CONTRIBUTING.md#documentation).
+
 # Using custom or third-party instrumentations
 
 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:

docs/troubleshooting.md

@@ -1,3 +1,5 @@
+> The official Splunk documentation for this page is [Troubleshoot Node.js instrumentation](https://docs.splunk.com/Observability/gdi/get-data-in/application/nodejs/troubleshooting/common-nodejs-troubleshooting.html). For instructions on how to contribute to the docs, see [CONTRIBUTING.md](../CONTRIBUTING.md#documentation).
+
 # Troubleshooting
 
 Diagnostic logs can help you troubleshoot instrumentation issues.