|
| 1 | +.. _deployments-windows-chef: |
| 2 | + |
| 3 | +******************************************************** |
| 4 | +Deploy the Collector for Windows with Chef |
| 5 | +******************************************************** |
| 6 | + |
| 7 | +.. meta:: |
| 8 | + |
| 9 | + :description: Use Chef to install and configure the OpenTelemetry Collector to collect metrics, traces, and logs from Linux and Windows machines and send data to Splunk Observability Cloud. |
| 10 | + |
| 11 | +Chef is a configuration management technology used to manage infrastructure on physical or virtual machines. Chef uses cookbooks to define a scenario. |
| 12 | + |
| 13 | +Cookbooks are fundamental working units of Chef, which consists of all the details related to working units, having the capability to modify configuration and the state of any system configured as a node on Chef infrastructure. Cookbooks can run multiple tasks. |
| 14 | + |
| 15 | +Prerequisites |
| 16 | +========================= |
| 17 | + |
| 18 | +You need the following resources to use Chef: |
| 19 | + |
| 20 | +* :ref:`Splunk Access Token <admin-org-tokens>` |
| 21 | +* :new-page:`Splunk Realm <https://dev.splunk.com/observability/docs/realms_in_endpoints/>` |
| 22 | +* Double-check exposed ports to make sure your environment doesn't have conflicts. You can change ports in the Collector configuration. See :ref:`otel-exposed-endpoints` for more information. |
| 23 | + |
| 24 | +Windows |
| 25 | +--------------------- |
| 26 | + |
| 27 | +The following Windows versions. All versions require using PowerShell 3.0 or newer. |
| 28 | + |
| 29 | +* Windows Server 2019 64-bit |
| 30 | +* Windows Server 2022 64-bit |
| 31 | + |
| 32 | +.. caution:: On Windows, the Collector is installed as a Windows service and its environment variables are set at the service scope, so they're only available to the Collector service and not to the entire machine. |
| 33 | + |
| 34 | +Install and use the Collector with Chef |
| 35 | +============================================================ |
| 36 | + |
| 37 | +Download the Chef cookbook from the :new-page:`Chef Supermarket <https://supermarket.chef.io/cookbooks/splunk_otel_collector>`, which is the site for community cookbooks. |
| 38 | + |
| 39 | +To install the Collector, include the ``splunk_otel_collector::default`` recipe in the ``run_list``, and set the attributes on the node's ``run_state``. The following is an example configuration that shows how to configure the required ``splunk_access_token`` attribute and some optional attributes: |
| 40 | + |
| 41 | +.. code-block:: yaml |
| 42 | +
|
| 43 | + { |
| 44 | + "splunk-otel-collector": { |
| 45 | + "splunk_access_token": "<SPLUNK_ACCESS_TOKEN>", |
| 46 | + "splunk_realm": "<SPLUNK_REALM>", |
| 47 | + } |
| 48 | + } |
| 49 | +
|
| 50 | +Configure automatic discovery for SignalFx .NET |
| 51 | +================================================================= |
| 52 | + |
| 53 | +You can automatically instrument your .NET applications along with the Collector installation using automatic discovery. Automatic discovery removes the need to install and configure the SignalFx .NET agent separately. See :ref:`discovery_mode` for more information. |
| 54 | + |
| 55 | +The cookbook accepts the attributes described in the following table: |
| 56 | + |
| 57 | +.. list-table:: |
| 58 | + :widths: 20 50 30 |
| 59 | + :header-rows: 1 |
| 60 | + |
| 61 | + * - Name |
| 62 | + - Description |
| 63 | + - Default value |
| 64 | + * - ``with_signalfx_dotnet_instrumentation`` |
| 65 | + - Whether to install or manage automatic discovery for .NET. When set to ``true``, the ``signalfx-dotnet-tracing`` MSI package will be downloaded and installed, and the Windows registry will be updated based on other configuration options. To learn more, see :ref:`windows-backend-auto-discovery` |
| 66 | + - ``false`` |
| 67 | + * - ``signalfx_dotnet_auto_instrumentation_version`` |
| 68 | + - Version of the ``signalfx-dotnet-tracing`` MSI package to download and install. |
| 69 | + - ``1.1.0`` |
| 70 | + * - ``signalfx_dotnet_auto_instrumentation_msi_url`` |
| 71 | + - Specify the URL to download the MSI from a custom host, for example ``https://my.host/signalfx-dotnet-tracing-1.0.0-x64.msi``. If specified, the ``signalfx_dotnet_auto_instrumentation_version`` option is ignored. |
| 72 | + - ``https://github.com/signalfx/signalfx-dotnet-tracing/releases/download/v{{ signalfx_dotnet_auto_instrumentation_version }}/signalfx-dotnet-tracing-{{ signalfx_dotnet_auto_instrumentation_version }}-x64.msi`` |
| 73 | + * - ``signalfx_dotnet_auto_instrumentation_iisreset`` |
| 74 | + - By default, the ``iisreset.exe`` command will be executed after installation/configuration in order for any changes to take effect for IIS applications. Set this option to ``false`` to skip this step if IIS is managed separately or is not applicable. |
| 75 | + - ``false`` |
| 76 | + * - ``signalfx_dotnet_auto_instrumentation_system_wide`` |
| 77 | + - Whether to configure automatic discovery for all .NET applications on the node. When set to ``true``, all attributes and environment variables are added to the ``HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Environment`` registry key. |
| 78 | + - ``false`` |
| 79 | + * - ``signalfx_dotnet_auto_instrumentation_environment`` |
| 80 | + - Sets the deployment environment variable that is reported to Splunk APM, for example ``production``. The value is assigned to the ``SIGNALFX_ENV`` environment variable in the Windows registry. |
| 81 | + - ``''`` |
| 82 | + * - ``signalfx_dotnet_auto_instrumentation_service_name`` |
| 83 | + - Sets the service name for the instrumented application, for example, ``my-service``. The value is assigned to the ``SIGNALFX_SERVICE_NAME`` environment variable in the Windows registry. |
| 84 | + - ``''`` |
| 85 | + * - ``signalfx_dotnet_auto_instrumentation_enable_profiler`` |
| 86 | + - Activates or deactivates AlwaysOn Profiling. The value will be assigned to the ``SIGNALFX_PROFILER_ENABLED`` environment variable in the Windows registry. |
| 87 | + - ``false`` |
| 88 | + * - ``signalfx_dotnet_auto_instrumentation_enable_profiler_memory`` |
| 89 | + - Activates or deactivates AlwaysOn Memory Profiling. The value will be assigned to the ``SIGNALFX_PROFILER_MEMORY_ENABLED`` environment variable in the Windows registry. |
| 90 | + - ``false`` |
| 91 | + * - ``signalfx_dotnet_auto_instrumentation_additional_options`` |
| 92 | + - Hash of additional options to be added to the Windows registry in addition to the options above. To learn more, see :ref:`advanced-dotnet-configuration`. |
| 93 | + - ``{}`` |
| 94 | + |
| 95 | +Additional environment variables |
| 96 | +====================================================== |
| 97 | + |
| 98 | +Use ``collector_additional_env_vars`` to include any additional environment variables from the Collector configuration file for the Collector's service. ``{}`` by default. |
| 99 | + |
| 100 | +For example, if the Collector's configuration file includes references to ``${MY_CUSTOM_VAR1}`` and ``${MY_CUSTOM_VAR2}``, specify the following to allow the Collector service to expand these variables: |
| 101 | + |
| 102 | +.. code-block:: yaml |
| 103 | +
|
| 104 | + collector_additional_env_vars: {'MY_CUSTOM_VAR1' => 'value1', 'MY_CUSTOM_VAR2' => 'value2'} |
| 105 | +
|
| 106 | +On Linux, the variables/values will be added to the ``/etc/otel/collector/splunk-otel-collector.conf`` systemd environment file. |
| 107 | + |
| 108 | +On Windows, the variables/values will be added to the Environment value under the ``HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\splunk-otel-collector`` registry key. |
0 commit comments