Merge pull request #2400 from splunk/pwilliams-o11ydocs-5993

Create framework for adding Node.js 3.0 docs changes

Author: mbechtold-splunk

gdi/get-data-in/application/nodejs/breaking-changes.rst

@@ -0,0 +1,47 @@
+.. _nodejs-3x-breaking-changes:
+
+*****************************************************
+Splunk OpenTelemetry JS version 3.0 breaking changes
+*****************************************************
+
+.. meta::
+  :description: Learn about the latest changes for Splunk OpenTelemetry JS version 3.0.
+
+Update to Splunk OpenTelemetry JS version 3.0
+==========================================================
+
+To update your Splunk Distribution for OpenTelemetry JS agent to version 3.0, see :ref:`instrument-nodejs-applications-3x` and install the latest version of the Splunk OpenTelemetry JS agent.
+
+Default port and protocol changes
+=================================
+
+In the Node.js 3.x instrumentation, the default protocol changed from gRPC to http/protobuf.
+
+If a custom configuration overrides the default endpoint setting, you must make sure of the following:
+
+#. Verify that the Node.js agent configuration is correct:
+
+   #. Verify that you are using the correct port for the selected protocol:
+
+      * gRPC: 4317
+      * http/protobuf: 4318
+
+   #. Verify that the custom endpoint configuration uses the correct port. For example: ``OTEL_EXPORTER_OTLP_ENDPOINT=http://<host>:4318``.
+
+   #. Verify that the custom protocol configuration uses the correct protocol. For example: ``OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf``.
+
+#. In the OTel Collector configuration file, verify that the associated OTLP receiver protocols match those used by the Node.js agent. Here is an example OTLP receiver configuration in the OTel Collector file:
+
+   .. code-block:: yaml
+
+      otlp:
+        protocols:
+          grpc:
+            endpoint: "${SPLUNK_LISTEN_INTERFACE}:4317"
+          http:
+            endpoint: "${SPLUNK_LISTEN_INTERFACE}:4318"
+
+Troubleshooting
+======================
+
+.. include:: /_includes/troubleshooting-components.rst

gdi/get-data-in/application/nodejs/configuration/advanced-nodejs-otel-configuration.rst

@@ -1,4 +1,4 @@
-.. _advanced-nodejs-otel-configuration:
+.. _advanced-nodejs-otel-configuration-3x:
 
 ***************************************************************************
 Configure the Splunk Distribution of OTel JS for Splunk Observability Cloud
@@ -11,7 +11,7 @@ You can configure the Splunk Distribution of OpenTelemetry JS to suit your instr
 
 The following sections describe all available settings for configuring OpenTelemetry for Node.js, including options for activating new features that are unique to the Splunk Distribution of OpenTelemetry JS.
 
-.. _configuration-methods-nodejs:
+.. _configuration-methods-nodejs-3x:
 
 Configuration methods
 ===========================================================
@@ -55,7 +55,7 @@ You can also activate the collection of a specific data type by passing a boolea
 
 .. note:: Function arguments take precedence over the corresponding environment variables.
 
-.. _main-nodejs-agent-settings:
+.. _main-nodejs-agent-settings-3x:
 
 General settings
 =========================================================================
@@ -66,7 +66,7 @@ The following settings are specific to the Splunk Distribution of OpenTelemetry
 
     <div class="instrumentation" section="settings" group="category" filter="general" url="https://raw.githubusercontent.com/splunk/o11y-gdi-metadata/main/apm/splunk-otel-js/metadata.yaml" data-renaming='{"keys": "Identifier", "description": "Description", "instrumented_components": "Components", "signals": "Signals", "env": "Environment variable", "default": "Default", "type": "Type", "property": "Argument to start()"}'></div>
 
-.. _instrumentation-configuration-nodejs:
+.. _instrumentation-configuration-nodejs-3x:
 
 Instrumentations configuration
 =======================================================
@@ -87,7 +87,7 @@ For example, to turn off all default instrumentations and only turn on the ``bun
 The previous settings only apply to instrumentations loaded by the Splunk Distribution of OpenTelemetry JS by default. When using the programmatic API to supply a list of user-specified instrumentations, they have no effect.
 
 
-.. _trace-configuration-nodejs:
+.. _trace-configuration-nodejs-3x:
 
 Trace configuration
 =======================================================
@@ -107,7 +107,19 @@ The following settings control tracing limits and attributes:
      - ``serviceName``
      - Name of the service or application you're instrumenting. Takes precedence over the service name defined in the ``OTEL_RESOURCE_ATTRIBUTES`` variable.
    * - OTEL_RESOURCE_ATTRIBUTES
-     - Not applicable
+     - Use the ``resource`` method in the ``start()`` function to pass resource attributes. For example, 
+
+         .. code-block:: js
+
+            import { start } from '@splunk/otel';
+            import { Resource } from '@opentelemetry/resources';
+
+            start({
+               serviceName: 'example',
+               resource: (detectedResource) => {
+                  return detectedResource.merge(new Resource({ 'service.version': '0.2.0' }));
+               },
+            });
      - Comma-separated list of resource attributes added to every reported span. For example, ``key1=val1,key2=val2``.
    * - OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT
      - Not applicable
@@ -120,10 +132,10 @@ The following settings control tracing limits and attributes:
      - Maximum number of links per span. Default value is ``1000``.
    * - OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT
      - Not applicable
-     - Maximum length of strings for attribute values. Values larger than the limit are truncated. Default value is ``1200``. Empty values are treated as infinity.
+     - Maximum length of strings for attribute values. Values larger than the limit are truncated. Default value is ``12000``. Empty values are treated as infinity.
 
 
-.. _trace-sampling-settings-nodejs:
+.. _trace-sampling-settings-nodejs-3x:
 
 Samplers configuration
 ===============================================================
@@ -132,19 +144,21 @@ The following settings control trace sampling:
 
 .. list-table::
    :header-rows: 1
-   :widths: 30 70
+   :widths: 20 40 40
    :width: 100%
 
    * - Environment variable
      - Description
+     - Default value
    * - OTEL_TRACES_SAMPLER
      - Sampler to use. The default value is ``parentbased_always_on``. Possible values are: ``always_on``, ``always_off``, ``parentbased_always_on``, ``parentbased_always_off``, ``traceidratio``, ``parentbased_traceidratio``. See :new-page:`Built-in samplers <https://github.com/open-telemetry/opentelemetry-js/blob/main/packages/opentelemetry-sdk-trace-base/README.md#built-in-samplers>` in the official OpenTelemetry documentation for more information.
-
+     - ``always_on``
    * - OTEL_TRACES_SAMPLER_ARG
      - Semicolon-separated list of rules for the ``rules`` sampler. For example, when setting the sampler to ``parentbased_traceidratio`` you can set the ratio using a number in the 0 to 1 range: |br| |br| ``OTEL_TRACES_SAMPLER_ARG=0.25``.
+     - None
 
 
-.. _trace-exporters-settings-nodejs:
+.. _trace-exporters-settings-nodejs-3x:
 
 Exporters configuration
 ===============================================================
@@ -155,7 +169,7 @@ The following settings control trace exporters and their endpoints:
 
     <div class="instrumentation" section="settings" group="category" filter="exporter" url="https://raw.githubusercontent.com/splunk/o11y-gdi-metadata/main/apm/splunk-otel-js/metadata.yaml" data-renaming='{"keys": "Identifier", "description": "Description", "instrumented_components": "Components", "signals": "Signals", "env": "Environment variable", "default": "Default", "type": "Type", "property": "Argument to start()"}'></div>
 
-.. _jaeger-exporter-nodejs:
+.. _jaeger-exporter-nodejs-3x:
 
 Jaeger exporter
 -------------------
@@ -180,7 +194,7 @@ To use the Jaeger exporter, add the ``@opentelemetry/exporter-jaeger`` package a
 
 .. note:: To send data directly to Splunk Observability Cloud, see :ref:`export-directly-to-olly-cloud-nodejs`.
 
-.. _trace-propagation-configuration-nodejs:
+.. _trace-propagation-configuration-nodejs-3x:
 
 Propagators configuration
 =======================================================
@@ -203,7 +217,7 @@ For backward compatibility with the SignalFx Tracing Library for Node.js, use th
 
       $env:OTEL_PROPAGATORS=b3multi
 
-.. _profiling-configuration-nodejs:
+.. _profiling-configuration-nodejs-3x:
 
 Node.js settings for AlwaysOn Profiling
 ===============================================
@@ -228,7 +242,7 @@ To configure AlwaysOn Profiling programmatically, pass the arguments to the ``st
 
 .. note:: For more information on AlwaysOn Profiling, see :ref:`profiling-intro`.
 
-.. _metrics-configuration-nodejs:
+.. _metrics-configuration-nodejs-3x:
 
 Metrics configuration
 ===============================================================
@@ -241,22 +255,7 @@ The following settings activate runtime metrics collection:
 
 .. note:: To pass settings as arguments, use the ``start()`` function.
 
-Configuring an existing metrics client to send custom metrics
----------------------------------------------------------------------
-
-You can use an existing SignalFx client for sending custom metrics instead of creating and configuring a new one.
-
-To configure an existing client, pass the following data to the ``start()`` function:
-
-- ``signalfx``: A JavaScript object with optional ``client`` and ``dimensions`` fields. The ``dimensions`` object adds a predefined dimension for each data point. The format for ``dimensions`` is ``{key: value, ...}``.
-
-The following is a list of dimensions added by default:
-
-- ``service``: See ``serviceName`` in :ref:`trace-configuration-nodejs`.
-- ``metric_source``: ``splunk-otel-js``
-- ``node_version``: ``process.versions.node``, for example ``16.10.0``
-
-.. _server-trace-information-nodejs:
+.. _server-trace-information-nodejs-3x:
 
 Server trace information
 ==============================================

gdi/get-data-in/application/nodejs/configuration/nodejs-otel-metrics.rst

@@ -1,4 +1,4 @@
-.. _nodejs-otel-metrics:
+.. _nodejs-otel-metrics-3x:
 
 **********************************************************************
 Metrics and attributes collected by the Splunk Distribution of OTel JS
@@ -11,14 +11,14 @@ The Splunk Distribution of OpenTelemetry JS collects runtime and custom metrics.
 
 To learn about the different metric types, see :ref:`metric-types`.
 
-.. _enable-nodejs-metrics:
+.. _enable-nodejs-metrics-3x:
 
 Activate metrics collection
 ====================================================
 
 To collect Node.js metrics, see :ref:`metrics-configuration-nodejs`.
 
-.. _nodejs-otel-runtime-metrics:
+.. _nodejs-otel-runtime-metrics-3x:
 
 Runtime metrics
 ================================================
@@ -71,7 +71,7 @@ The following runtime metrics are automatically collected and exported:
      - Gauge
      - Minimum event loop lag within the collection interval, in nanoseconds.
 
-.. _nodejs-otel-metrics-migration:
+.. _nodejs-otel-metrics-migration-3x:
 
 Migrate from SignalFx metrics for Node.js
 ===========================================
@@ -150,7 +150,7 @@ With the release of version 2.0 of the Splunk Distribution of OpenTelemetry JS,
    * - ``process.runtime.nodejs.event_loop.lag.min``
      - ``nodejs.event_loop.lag.min``
 
-.. _nodejs-otel-debug-metrics:
+.. _nodejs-otel-debug-metrics-3x:
 
 Debug metrics
 =====================================

gdi/get-data-in/application/nodejs/get-started.rst

@@ -1,4 +1,4 @@
-.. _get-started-nodejs:
+.. _get-started-nodejs-3x:
 
 ***************************************************************
 Instrument Node.js applications for Splunk Observability Cloud
@@ -19,7 +19,11 @@ Instrument Node.js applications for Splunk Observability Cloud
    Performance overhead <performance>
    Troubleshoot the Node.js agent <troubleshooting/common-nodejs-troubleshooting>
    About Splunk OTel JS <splunk-nodejs-otel-distribution>
+   Node.js 3.0 breaking changes <breaking-changes>
    Migrate from the SFx Tracing Library <troubleshooting/migrate-signalfx-nodejs-agent-to-otel>
+   Version 2.X (deprecated) <version2x/get-started>
+
+.. note:: The Splunk OpenTelemetry JS version 3.0 contains a set of breaking changes. To view these changes and learn how to update to version 3.0, see :ref:`nodejs-3x-breaking-changes`.
 
 The Splunk Distribution of OpenTelemetry JS provides a Node.js SDK that automatically adds APM instrumentation to your Node.js application. The instrumentation captures traces, runtime metrics, and CPU and memory profiles and sends them to Splunk Observability Cloud.
 

gdi/get-data-in/application/nodejs/instrumentation/connect-traces-logs.rst

@@ -1,4 +1,4 @@
-.. _correlate-traces-with-logs-nodejs:
+.. _correlate-traces-with-logs-nodejs-3x:
 
 *******************************************************************
 Connect Node.js trace data with logs for Splunk Observability Cloud
@@ -9,7 +9,7 @@ Connect Node.js trace data with logs for Splunk Observability Cloud
 
 You can configure Node.js logging libraries to include tracing attributes provided automatically by the Splunk Distribution of OpenTelemetry JS. Use the trace metadata to correlate traces with log events and explore Node.js application logs in Splunk Observability Cloud.
 
-.. _nodejs-traces-logs-requirements:
+.. _nodejs-traces-logs-requirements-3x:
 
 Supported logging libraries
 =====================================================
@@ -20,14 +20,14 @@ The Splunk Distribution of OpenTelemetry JS automatically supports the following
 - Pino
 - Winston
 
-.. _nodejs-traces-logs-enable:
+.. _nodejs-traces-logs-enable-3x:
 
 Activate logs injection
 =====================================================
 
 Log injection is already activated for the supported libraries. To inject trace data into formatted logs, see the documentation for each library.
 
-.. _nodejs-include-trace-data:
+.. _nodejs-include-trace-data-3x:
 
 Include trace metadata in log statements
 ===================================================