Merge pull request #1566 from splunk/repo-sync

Pulling refs/heads/main into main

Author: aurbiztondo-splunk

gdi/opentelemetry/collector-addon/collector-addon-configure.rst

@@ -0,0 +1,42 @@
+.. _collector-addon-configure:
+
+*********************************************************************************************
+Configure the Technical Add-on for the Splunk OpenTelemetry Collector
+*********************************************************************************************
+
+.. meta::
+   :description: Configure the Technical Add-on for the Splunk Distribution of the OpenTelemetry Collector.
+
+.. toctree::
+   :maxdepth: 5
+   :hidden:
+
+To configure the OpenTelemetry Collector within the Add-on, follow these steps:
+
+#. Create a new configuration file in YAML format for the Collector. See more at :ref:`otel-configuration`.
+#. Edit the default version of your inputs.conf file to point to the new configuration file.
+#. Restart the Splunk Universal Forwarder.
+
+.. _collector-addon-configure-traces:
+
+Activate trace collection
+============================================================================================================================================
+
+The Splunk Add-on for the OpenTelemetry Collector does not perform automatic tracing. To configure your Collector instance to receive traces from your applications, see :ref:`get-started-application`.
+
+.. _collector-addon-configure-multiple:
+
+Manage multiple Collectors
+============================================================================================================================================
+
+If your configuration uses more than one Collector, consider the following best practices:
+
+* Deploy different agent_config.yaml files to different hosts. For example, a version of the add-on with MySQL Receiver enabled, and a different version of the add-on with MS SQL Server Receiver enabled will work best when deployed on different hosts.
+
+* Deploy the same files to every host, then point to another agent_config.yaml file in inputs.conf in the splunk_config_dir or splunk_config_yaml properties.
+
+* Deploy the same instance of the Splunk Add-on for the OpenTelemetry Collector to all hosts, then deploy another instance of the add-on that does not contain binaries and only contains a YAML file with a specific receiver enabled. In this case, the YAML file from the second add-on instance will supersede the YAML from the first add-on instance on a particular host.
+
+* Designate one instance of the Splunk Add-on for the OpenTelemetry Collector as your default Collector, tailor it to your needs, and then create variants of the add-on using a different name. Then deploy each variant to a different server class.
+
+

gdi/opentelemetry/collector-addon/collector-addon-install.rst

@@ -0,0 +1,149 @@
+.. _collector-addon-install:
+
+*********************************************************************************************
+Install the Technical Add-on for the Splunk OpenTelemetry Collector
+*********************************************************************************************
+
+.. meta::
+   :description: Install the Technical Add-on for the Splunk Distribution of the OpenTelemetry Collector.
+
+.. toctree::
+   :maxdepth: 5
+   :hidden:
+
+You can install the Splunk Add-on for the OpenTelemetry Collector to a :ref:`single <collector-addon-install-uf>` or to :ref:`multiple <collector-addon-install-server>` universal forwarder instances.
+
+The following applies:
+
+* The Splunk Add-on for the OpenTelemetry Collector installer comes packaged with a number of agent bundle libraries. Do not delete these files, even if you do not plan on incorporating an agent bundle.
+
+* To save space you can remove the folder for the binaries you are not using. For example, if you are installing on Linux you can delete the Windows folder.
+
+* If your configuration uses more than one collector, see :ref:`collector-addon-configure-multiple`.
+
+.. _collector-addon-install-uf:
+
+Install the Splunk Add-on for the OpenTelemetry Collector to a universal forwarder instance
+============================================================================================================================================
+
+Follow these steps to install the Splunk Add-on for OpenTelemetry Collector to a universal forwarder instance:
+
+#. Download and unzip the installation file to the machine running universal forwarder. In your unzipped folder, locate and unzip the .tar file to :guilabel:`SPLUNK_HOME > etc > deployment apps`. 
+
+#. Create a new "local" folder in Splunk_TA_otel/. Open the configuration folder and copy the access_token file into your new local folder.
+
+#. In the default folder find the inputs.conf file. You can inspect the defaults for the settings and update the values if necessary. Note that the values in inputs.conf must match those in Splunk Web. 
+
+  * ``splunk_config``. ``$SPLUNK_OTEL_TA_HOME/configs/ta-agent-config.yaml`` by default.
+  * ``disabled``. ``false`` by default. 
+  * ``start_by_shell``. ``false`` by default. 
+  * ``splunk_access_token_file``. ``access_token`` by default. 
+  * ``splunk_realm``. ``us0`` by default. A realm is a self-contained deployment that hosts organizations. You can find your realm name on your profile page in the user interface.
+  * ``splunk_trace_ingest_url``. The default value is :new-page:`https://ingest.us0.signalfx.com/v2/trace`.
+
+#. In :strong:`Splunk Observability Cloud`, retrieve your access token value. If you do not have a token, contact your Splunk Observability Cloud administrator to create a token. See :ref:`admin-tokens` to learn more about tokens.
+
+#. In Splunk_TA_otel/local, create or open the access_token file, and replace the existing contents with the token value you copied from Splunk Observability Cloud. Save the updated file.
+
+#. In :strong:`Splunk Observability Cloud`, select your name, then select the Organization tab to verify that the realm value in the realm and sapm-endpoint files in your local folder reflect the value shown in Splunk Observability Cloud. Save any changes you make in the local files.
+
+#. Restart Splunkd. Your Add-on solution is now deployed. 
+
+#. In :guilabel:`Splunk Infrastructure Monitoring`, navigate to the host where you deployed the Splunk Add-on for the OpenTelemetry Collector and select it to explore its metrics and status. For more information, see :ref:`use-navigators-imm`.
+
+.. _collector-addon-install-server:
+
+Install the Splunk Add-on for the OpenTelemetry Collector to multiple universal forwarder instances using the deployment server
+============================================================================================================================================
+
+Follow these steps to install the Splunk Add-on for the OpenTelemetry Collector to multiple universal forwarder instances using the deployment server:
+
+#. Download and unzip the installation file to the machine running your deployment server. In your unzipped folder, locate and unzip the .tar file to :guilabel:`SPLUNK_HOME > etc > deployment apps`. 
+
+#. Create a new "local" folder in Splunk_TA_otel/. Open the configuration folder and copy the access_token file into your new local folder.
+
+#. In the default folder find the inputs.conf file. You can inspect the defaults for the settings and update the values if necessary. Note that the values in inputs.conf must match those in Splunk Web. 
+
+  * ``splunk_config``. ``$SPLUNK_OTEL_TA_HOME/configs/ta-agent-config.yaml`` by default.
+  * ``disabled``. ``false`` by default. 
+  * ``start_by_shell``. ``false`` by default. 
+  * ``splunk_access_token_file``. ``access_token`` by default. 
+  * ``splunk_realm``. ``us0`` by default. A realm is a self-contained deployment that hosts organizations. You can find your realm name on your profile page in the user interface.
+  * ``splunk_trace_ingest_url``. The default value is :new-page:`https://ingest.us0.signalfx.com/v2/trace`.
+
+#. In :strong:`Splunk Observability Cloud`, retrieve your access token value. If you do not have a token, contact your Splunk Observability Cloud administrator to create a token. See :ref:`admin-tokens` to learn more about tokens.
+
+#. In Splunk_TA_otel/local, create or open the access_token file, and replace the existing contents with the token value you copied from Splunk Observability Cloud. Save the updated file.
+
+#. In :strong:`Splunk Observability Cloud`, select your name, then select the Organization tab to verify that the realm value in the realm and sapm-endpoint files in your local folder match the value shown in Splunk Observability Cloud. Save any changes you make in the local files.
+
+#. In :strong:`Splunk Web`, select :guilabel:`Settings > Forwarder Management` to access your deployment server.
+
+#. Create a server class:
+
+   #. For "Edit clients", update :guilabel:`Include` to add your Universal Forwarder instance and save.
+
+   #. Go to :guilabel:`Add apps` and select your new Splunk Add-on for the OpenTelemetry Collector service class.
+
+   #. Select :guilabel:`Edit` on your newly created service class and make sure the following are checked:
+   
+      * Enable App
+      * Restart Splunkd
+
+#. Save. Your Add-on solution is now deployed. 
+
+#. In :guilabel:`Splunk Infrastructure Monitoring`, navigate to the host where you deployed the Splunk Add-on for the OpenTelemetry Collector and select it to explore its metrics and status. For more information, see :ref:`use-navigators-imm`.
+
+.. _collector-addon-mode:
+
+Configure the deployment mode of your Splunk Add-on Collector instance
+============================================================================================================================================
+
+The OpenTelemetry Collector has different :ref:`deployment modes <otel-deployment-mode>`:
+
+* Host monitoring (agent): This is the default value and the simplest configuration. The Splunk Add-on for the OpenTelemetry Collector, when configured as an agent, sends data to Splunk Observability Cloud.
+
+* Data forwarding (gateway): When configured as a gateway, your Splunk Add-on for the OpenTelemetry Collector collects data from one or more agents before forwarding it to Splunk Observability Cloud.
+
+* As an agent that sends data to a gateway: To use a gateway instance, you create one or more instances of Splunk add-on for the OpenTelemetry Collector as agents that send data to that gateway instance.
+
+.. _collector-addon-mode-agent:
+
+Deploy the Splunk Add-on for the OpenTelemetry Collector as an agent
+------------------------------------------------------------------------------------------------------------------------
+
+As an agent, the OpenTelemetry Collector sends data directly to Splunk Observability Cloud. This is the default configuration. Learn more at :ref:`collector-agent-mode`.
+
+If your instance is not configured as an agent and you want to configure it as an agent, edit your inputs.conf file and update the variable ``Splunk_config`` to reflect your agent configuration file name. You can find this file in your directory at ``/otelcol/config/``. The default file name is ``ta-agent-config.yaml``. If you are using a custom configuration file, provide that file name.
+
+.. _collector-addon-mode-gateway:
+
+Deploy the Splunk Add-on for the OpenTelemetry Collector as a gateway
+------------------------------------------------------------------------------------------------------------------------
+
+If deployed as a gateway, the Collector instance can collect data from one or more Collector instances deployed as agents. The gateway instance then sends that data to Splunk Observability Cloud. Learn more at :ref:`collector-gateway-mode`.
+
+To configure your Splunk Add-on for OpenTelemetry Collector as a gateway:
+
+#. Edit your inputs.conf file to update the variable ``Splunk_config`` with your gateway configuration file name. You can find this file in your directory at ``/otelcol/config/``. The default file name for the gateway file is ``ta-gateway-config.yaml``. If you are using a custom configuration file, provide that file name.
+
+#. Set the ``splunk_listen_interface`` value to ``0.0.0.0`` or to the specific IP address that sends data to this gateway in ``local/inputs.conf``.
+
+.. caution:: You must also configure one or more Collector instances as agents that send data to your new gateway. 
+
+.. _collector-addon-mode-send:
+
+Configure Splunk Add-on for OpenTelemetry Collector as an agent that sends data to a gateway
+------------------------------------------------------------------------------------------------------------------------
+
+You can set up one or more Collector instances as agents that send data to another instance that is set up as a gateway. See more at :ref:`collector-agent-to-gateway`.
+
+To do this configure an instance that works as a gateway, and then one or more instances that operate as agents:
+
+#. Create your gateway, if you have not already done so. See :ref:`collector-addon-mode-gateway` for more information.
+
+#. Edit your inputs.conf file to update the variable ``Splunk_config`` to reflect your gateway configuration file name. You can find the default configuration file in your directory at ``/otelcol/config/``. The default file name for this configuration file is ``ta-agent-to-gateway-config.yaml``. If you are using a custom configuration file, provide that file name.
+
+#. In the README directory, open ``inputs.conf.spec`` and copy the attribute for the ``splunk_gateway_url``.
+
+#. Paste this value into ``ta-agent-to-gateway-config.yaml`` and then update the value for this setting with the gateway IP address.

gdi/opentelemetry/collector-addon/collector-addon-intro.rst

@@ -0,0 +1,125 @@
+.. _collector-addon-intro:
+
+*********************************************************************************************
+Splunk Add-On for the OpenTelemetry Collector
+*********************************************************************************************
+
+.. meta::
+   :description: Introduction to the Splunk Add-on for the Splunk Distribution of the OpenTelemetry Collector.
+
+.. toctree::
+   :maxdepth: 5
+   :hidden:
+
+   Install the Technical Add-on <collector-addon-install.rst>
+   Configure the Technical Add-on <collector-addon-configure.rst>
+   Troubleshooting <collector-addon-troubleshooting.rst>
+
+Use the Splunk Add-on for the OpenTelemetry Collector to collect traces and metrics for Splunk Observability Cloud.
+
+You have two ways to install and configure the Splunk Add-on for the OpenTelemetry Collector:
+
+* :ref:`collector-addon-install-uf`
+* :ref:`collector-addon-install-server`
+
+You can also choose to install and configure the Add-on using a customized or third-party solution, such as Ansible or Terraform. 
+
+.. raw:: html
+
+   <embed>
+      <h2>Differences between the Splunk Distribution of the OpenTelemetry Collector and the Splunk Add-on for the OpenTelemetry Collector<a name="collector-addon-distro-diffs" class="headerlink" href="#collector-addon-distro-diffs" title="Permalink to this headline">¶</a></h2>
+   </embed>
+
+The Collector in the Splunk Add-on for OpenTelemetry is the same Collector offered in Splunk Observability. However, the Splunk Add-on provides the added benefit of out-of-the box Collector content and configuration.
+
+.. list-table::
+  :widths: 30 40 40
+  :width: 100%
+  :header-rows: 1
+
+  * - Function
+    - Splunk Distribution of the OpenTelemetry Collector
+    - Splunk Add-on for the OpenTelemetry Collector
+
+  * - Collector binary
+    - Supported
+    - Supported
+
+  * - Gateway configuration
+    - Supported
+    - Supported
+
+  * - Default agent configuration
+    - Includes logging receiver and exporter configuration
+    - No out-of-the-box configuration is provided for the logging exporter or receiver
+
+  * - Configuration method
+    - Environment variables
+    - Inputs.conf
+
+  * - :ref:`Automatic discovery and configuration <discovery_mode>`
+    - Supported
+    - Not supported
+
+  * - Distribution and deployment
+    - Source code, binary, Operator, Helm Charts, Debian, Ansible, Puppet, Chef, Salt
+    - Manual installation and Splunk deployment server distribution
+
+.. raw:: html
+
+   <embed>
+      <h2>Prerequisites<a name="collector-addon-prereqs" class="headerlink" href="#collector-addon-prereqs" title="Permalink to this headline">¶</a></h2>
+   </embed>
+
+Before you install the Splunk Add-on for the OpenTelemetry Collector, you must have the following Splunk products installed and configured:
+
+* Splunk Universal Forwarder version 8.x or 9.x on Windows or Linux: The Splunk Add-on for the OpenTelemetry Collector is installed alongside your universal forwarder to push collected data to Splunk Observability Cloud.
+
+* Splunk Observability Cloud: The Splunk Add-on for the OpenTelemetry Collector is configured to send data to Splunk Observability Cloud. See :ref:`otel-intro` and :ref:`otel-requirements` for more information on how to prepare your Splunk Observability Cloud instance.
+
+* (optional) Install Splunk Enterprise or Splunk Cloud if you plan to use a Splunk Web interface or deployment server as forwarders.
+
+* (optional) Install the deployment server if you plan to use the deployment server to push the Splunk Add-on for the OpenTelemetry Collector to multiple hosts.
+
+.. raw:: html
+
+   <embed>
+      <h2>Data collection and usage<a name="collector-addon-prereqs" class="headerlink" href="#collector-addon-prereqs" title="Permalink to this headline">¶</a></h2>
+   </embed>
+
+When you deploy the Splunk Add-on for the Open Telemetry Collector, Splunk Cloud Platform sends aggregated telemetry usage data to Splunk Inc. ("Splunk") to help improve future releases. For information about how to opt in or out, and how the data is collected, stored, and governed, see :new-page:`Share performance and usage data in Splunk Enterprise <https://docs.splunk.com/Documentation/Splunk/9.3.1/Admin/Shareperformancedata>`.
+
+The Splunk Add-on for the Open Telemetry Collector uses saved searches to collect anonymous usage data. These searches run in the background regardless of whether you opt in or out to send usage data to Splunk, and do not have any significant impact on performance.
+
+.. raw:: html
+
+   <embed>
+      <h2>Download the Technical Add-on<a name="collector-addon-intro-download" class="headerlink" href="#collector-addon-intro-download" title="Permalink to this headline">¶</a></h2>
+   </embed>
+
+You can download the Splunk Add-on for the OpenTelemetry Collector from Splunkbase. See :new-page:`Splunkbase's Splunk Add-on for the OpenTelemetry Collector <https://splunkbase.splunk.com/app/7125?_gl=1*nsvlab*_gcl_au*MTI1MDc1MzQ3OS4xNzIzNDQ2NTk2*FPAU*MTI1MDc1MzQ3OS4xNzIzNDQ2NTk2*_ga*MTY3OTA0Njk3Mi4xNjUyNzEwMTA4*_ga_5EPM2P39FV*MTcyNzcwMTk1MC4xMDQ5LjEuMTcyNzcwMjM4OC4wLjAuMzU0OTAyMDQ1*_fplc*MEE0WVo5cGVvVWpGWXhndCUyRlE1U0RIdU81dUElMkZoUFQ2RyUyQmZXcTRQMGZCdzl5R2N2NVE0JTJGdEVHTXFkZGhPdGZoJTJCQ21JdHp6cFJIOWl0TEdYJTJCd0NIc1BjelRDeG9Oc1lISDlXOU9BcHJ5cm5PTFBRJTNE>`.
+
+.. raw:: html
+
+   <embed>
+      <h2>Release notes<a name="collector-addon-intro-releasenotes" class="headerlink" href="#collector-addon-intro-releasenotes" title="Permalink to this headline">¶</a></h2>
+   </embed>
+
+.. list-table::
+   :widths: 30 35 35
+   :header-rows: 1
+   :width: 100%
+
+   *  - Splunk Add-on version
+      - Release date
+      - Collector version
+
+   *  - 1.3.2 
+      - September 20, 2024
+      - :new-page:`version 0.104 <https://github.com/signalfx/splunk-otel-collector/releases/tag/v0.104.0>`
+
+   *  - 1.3.1 
+      - August 6, 2024
+      - :new-page:`version 0.104 <https://github.com/signalfx/splunk-otel-collector/releases/tag/v0.104.0>`
+
+