Docs » Get started with the Splunk Distribution of the OpenTelemetry Collector » Collector deployment tools and options » Deploy the Collector with Ansible for Linux

Deploy the Collector with Ansible for Linux 🔗

Install the Ansible collection 🔗

The following Linux distributions and versions are supported:

  • Amazon Linux: 2, 2023. Log collection with Fluentd isn’t supported for Amazon Linux 2023.

  • CentOS, Red Hat, or Oracle: 7, 8, 9

  • Debian: 9, 10, 11

  • SUSE: 12, 15 for Collector version 0.34.0 or higher. Log collection with Fluentd isn’t supported.

  • Ubuntu: 16.04, 18.04, 20.04, and 22.04

Before installing the Ansible collection, do the following:

Ansible Galaxy is the Ansible official hub for sharing Ansible content. See Ansible Collection for the Splunk Distribution of OpenTelemetry Collector for more information about the playbook.

Run the following command to install the Ansible collection from Ansible Galaxy:

ansible-galaxy collection install signalfx.splunk_otel_collector

To use the role, include the signalfx.splunk_otel_collector.collector role invocation in your playbook. Note that this role requires root access. The following example shows how to use the role in a playbook with minimal required configuration:

- name: Install the Splunk Distribution of OpenTelemetry Collector
  hosts: all
  become: yes
  tasks:
    - name: "Include splunk_otel_collector"
      include_role:
        name: "signalfx.splunk_otel_collector.collector"
      vars:
        splunk_access_token: YOUR_ACCESS_TOKEN
        splunk_realm: SPLUNK_REALM

The following table describes the variables that can be configured for this role:

Variable

Description

gomemlimit

Replaces splunk_ballast_size_mib starting in Collector version 0.97.0. It allows limiting memory usage in the GO runtime, helping enhance garbage collection and prevent out of memory situations. Learn more at how to update memory ballast in your configuration. Default value is 90% of splunk_total_mem_mib.

splunk_access_token

The Splunk access token to authenticate requests. This attribute is required.

splunk_realm

The realm to send the data to. This variable is set with this value for the service. The default value is us0. To find your Splunk realm, see Note about realms.

splunk_ingest_url

The Splunk ingest URL, for example, https://ingest.us0.signalfx.com. This variable is set with this value for the service. The default value is https://ingest.{{ splunk_realm }}.signalfx.com.

splunk_api_url

The Splunk API URL, for example, https://api.us0.signalfx.com. This variable is set with this value for the service. The default value is https://api.{{ splunk_realm }}.signalfx.com.

splunk_trace_url

The Splunk trace endpoint URL, for example, https://ingest.us0.signalfx.com/v2/trace. This variable is set with this value for the service. The default value is {{ splunk_ingest_url }}/v2/trace.

splunk_hec_url

The Splunk HEC endpoint URL, for example, https://ingest.us0.signalfx.com/v1/log. This variable is set with this value for the service. The default value is {{ splunk_ingest_url }}/v1/log.

splunk_otel_collector_version

The version of the package to install, for example, 0.25.0. The default value is latest.

splunk_otel_collector_config

The configuration file, created in YAML. This variable can be set to /etc/otel/collector/gateway_config.yaml to install the package in data forwarding (gateway) mode. The default location is /etc/otel/collector/agent_config.yaml.

splunk_config_override

The custom configuration that is merged into the default configuration.

splunk_config_override_list_merge

The variable used to configure the list_merge option for merging lists in splunk_config_override with lists in the default configuration. Allowed options are replace, keep, append, prepend, append_rp, or prepend_rp. The default value is replace. You can find information about this variable on the Ansible Documentation site .

splunk_otel_collector_config_source

This is the source path to a configuration file on your control host that is uploaded and set in place of the value set in splunk_otel_collector_config on remote hosts. This variable can be used to submit a custom configuration, for example, ./custom_collector_config.yaml. The default value is "", which means that nothing is copied and the configuration file set with splunk_otel_collector_config is used.

splunk_bundle_dir

The path to the bundle directory. The default path is provided by the package. If the specified path is changed from the default value, the path should be an existing directory on the node. This variable is set with this value for the service. The default location is /usr/lib/splunk-otel-collector/agent-bundle.

splunk_collectd_dir

The path to the collectd configuration directory for the bundle. The default path is provided by the package. If the specified path is changed from the default value, the path should be an existing directory on the node. This variable is set with this value for the service. The default location is /usr/lib/splunk-otel-collector/agent-bundle.

splunk_service_user and splunk_service_group

The user or group ownership for the service. The user or group is created if they do not exist. The default value is splunk-otel-collector.

splunk_otel_collector_proxy_http and splunk_otel_collector_proxy_https

The proxy address, respectively for http_proxy and https_proxy environment variables, to be used by the service if at least one of them is not empty. This value must be a full URL, for example, http://user:pass@10.0.0.42. Notice this proxy is not used by Ansible itself during deployment. The default value is "".

splunk_memory_total_mib

The amount of allocated memory in MiB. The default value is 512, or 500 x 2^20 bytes, of memory .

splunk_ballast_size_mib

splunk_ballast_size_mib is deprecated starting on Collector version 0.97.0. If you’re using it, see how to update your configuration.

install_fluentd

The option to install or manage Fluentd and dependencies for log collection. The dependencies include capng_c for activating Linux capabilities, fluent-plugin-systemd for systemd journal log collection, and the required libraries or development tools. The default value is false.

td_agent_version

The version of td-agent (Fluentd package) that is installed. The default value is 3.3.0 for Debian jessie, 3.7.1 for Debian stretch, and 4.3.0 for other distros.

splunk_fluentd_config

The path to the Fluentd configuration file on the remote host. The default location is /etc/otel/collector/fluentd/fluent.conf.

splunk_fluentd_config_source

The source path to a Fluentd configuration file on your control host that is uploaded and set in place of the value set in splunk_fluentd_config on remote hosts. Use this variable to submit a custom Fluentd configuration, for example, ./custom_fluentd_config.conf. The default value is "", which means that nothing is copied and the configuration file set with splunk_otel_collector_config is used.

Configure automatic discovery for back-end applications (Linux only) 🔗

You can automatically discover and instrument your back-end applications along with the Collector installation. Automatic discovery (formerly zero configuration auto instrumentation) removes the need to install and configure the SDKs separately. See Configure automatic discovery for Java for more information.

The following table shows the variables that you can configure for this Ansible role:

Variable

Description

Default value

install_splunk_otel_auto_instrumentation

Installs or manages automatic discovery for Java, Node.js, and/or .NET back-end applications. When set to true, the splunk-otel-auto-instrumentation Debian or RPM package is downloaded and installed from the Collector repository. The application(s) on the node needs to be started or restarted separately after installation for automatic discovery or any configuration changes to take effect.

false

splunk_otel_auto_instrumentation_sdks

The automatic discovery SDKs to install and activate. Note: dotnet is currently only supported for x86_64/amd64.

['java', 'nodejs', 'dotnet']

splunk_otel_auto_instrumentation_version

Determines the version of the splunk-otel-auto-instrumentation package to install, for example, 0.50.0. The minimum supported version is 0.48.0 for Java, 0.87.0 for Node.js, and 0.99.0 for .NET.

latest

splunk_otel_auto_instrumentation_systemd

By default, the /etc/ld.so.preload file on the node will be configured for the /usr/lib/splunk-instrumentation/libsplunk.so shared object library provided by the splunk-otel-auto-instrumentation package to activate and configure automatic discovery system-wide for all supported applications. Alternatively, set this option to true to activate and configure automatic discovery only for supported applications running as systemd services. If this option is set to true, /usr/lib/splunk-instrumentation/libsplunk.so will not be added to /etc/ld.so.preload. Instead, the /usr/lib/systemd/system.conf.d/00-splunk-otel-auto-instrumentation.conf systemd drop-in file will be created and configured for environment variables based on the default and specified options.

false

splunk_otel_auto_instrumentation_ld_so_preload

By default, the /etc/ld.so.preload file on the node is configured for the /usr/lib/splunk-instrumentation/libsplunk.so shared object library, which is provided by the splunk-otel-auto-instrumentation package and is required for automatic discovery. You can configure this variable to include additional library paths, for example, /path/to/my.library.so. Use this option if you need to include custom or other shared object library files to be preloaded for your applications, in addition to the /usr/lib/splunk-instrumentation/libsplunk.so file.

None

splunk_otel_auto_instrumentation_java_agent_jar

Determines the path to the Splunk OpenTelemetry Java agent. The default path is provided by the splunk-otel-auto-instrumentation package. If the path is changed from the default value, the path should be an existing file on the node.

/usr/lib/splunk-instrumentation/splunk-otel-javaagent.jar

splunk_otel_auto_instrumentation_npm_path

The path to the pre-installed npm command required to install the Node.js SDK. For example, /my/custom/path/to/npm.

npm

splunk_otel_auto_instrumentation_resource_attributes

Configures the OpenTelemetry instrumentation resource attributes, for example, deployment.environment=prod. The resource attributes are user-defined comma-separated key=value pairs. See Java, Node.js, and .NET for more information.

None

splunk_otel_auto_instrumentation_service_name

Explicitly sets the service name for the instrumented applications, for example, my.service. By default, the service name is automatically derived from the arguments of the executable on the node. See Java, Node.js, and .NET for more information.

None

splunk_otel_auto_instrumentation_enable_profiler

Activates or deactivates AlwaysOn CPU Profiling.

false

splunk_otel_auto_instrumentation_enable_profiler_memory

Activates or deactivates AlwaysOn Memory Profiling.

false

splunk_otel_auto_instrumentation_enable_metrics

Activates or deactivates JVM metrics.

false