Upgrade the Collector for Kubernetes and other updates

General guidelines

Apply the following changes to the Collector configuration files for specific version upgrades.

From 0.158.0 to 0.159.0

Linux DEB and RPM packages and Windows installations through MSI or Chocolatey now use otelcollauncher as the service entrypoint instead of otelcol. By default, the launcher starts otelcol directly and passes through the existing service arguments, so upgrades preserve the previous Collector service behavior. The launcher allows the service to start either otelcol directly or the OpAMP Supervisor, enabling additional Fleet Management capabilities. See OpenTelemetry Fleet Management for details.

For a new Linux installation, pass --with-supervisor to the installer script. To enable the OpAMP Supervisor after upgrading, set SPLUNK_OPAMP_SUPERVISOR_ENABLED=true in /etc/otel/collector/splunk-otel-collector.conf and restart the service.

For a new Windows installation, pass -with_supervisor $true to the installer script. To enable the OpAMP Supervisor after upgrading, set SPLUNK_OPAMP_SUPERVISOR_ENABLED=true in the service's Environment value under HKLM:\SYSTEM\CurrentControlSet\Services\splunk-otel-collector and restart the service.

To stop running the Collector under OpAMP Supervisor, set SPLUNK_OPAMP_SUPERVISOR_ENABLED=false in:

• Linux: /etc/otel/collector/splunk-otel-collector.conf
• Windows: service's Environment value under HKLM:\SYSTEM\CurrentControlSet\Services\splunk-otel-collector

Restart the service after changing the setting. The launcher will return to starting otelcol directly, without the supervisor. When switched back to direct mode, remote configuration delivered through the supervisor is no longer applied.

On Linux DEB and RPM installation or upgrade, the package also now recursively sets the ownership of /var/lib/otelcol to the service user and group. This ensures the Collector and OpAMP Supervisor can write files in existing and new subdirectories of the shared state directory.

From 0.157.0 to 0.158.0

OpenTelemetry has deprecated deployment.environment in favor of deployment.environment.name. The Collector's optional deployment environment configuration and the --deployment-environment (Linux) and -deployment_env (Windows) installer options now use deployment.environment.name.

If deployment.environment is still required, use that name instead in the applicable configuration. For instrumented applications, set OTEL_RESOURCE_ATTRIBUTES=deployment.environment=<value>. The Ansible, Chef, Puppet, and Salt integrations can pass the deprecated key through their generic resource-attribute option.

The installer deployment environment option will use the new attribute name. To keep the deprecated attribute, replace only that attribute in OTEL_RESOURCE_ATTRIBUTES, preserve all other attributes, and restart the instrumented applications or IIS.

From 0.150.0 to 0.151.0

The default Windows MSI artifact download URL has been updated: Splunk Observability Cloud domain transition guide

• https://dl.signalfx.com → https://dl.observability.splunkcloud.com

To keep using the legacy dl.signalfx.com download URL, pass -collector_msi_url explicitly to install.ps1 (replace <version> with the collector version):

Windows (install.ps1):

-collector_msi_url https://dl.signalfx.com/splunk-otel-collector/msi/release/splunk-otel-collector-<version>-amd64.msi

From 0.149.0 to 0.150.0

Default endpoint URLs have changed from *.signalfx.com to *.observability.splunkcloud.com. The legacy endpoints remaim functional but migrating to the new domain is highly recommended. See the domain transition guide for background.

Package manager upgrade (apt, yum, choco upgrade)

Your existing environment configuration is preserved. The collector continues to use the endpoints you previously configured.

When you are ready to migrate, replace with your realm (e.g. us0):

SPLUNK_API_URL=https://api.<realm>.observability.splunkcloud.com
SPLUNK_INGEST_URL=https://ingest.<realm>.observability.splunkcloud.com
SPLUNK_HEC_URL=https://ingest.<realm>.observability.splunkcloud.com/v1/log

Then restart the service: sudo systemctl restart splunk-otel-collector.

Windows: Update the Environment value in the registry at HKLM:\SYSTEM\CurrentControlSet\Services\splunk-otel-collector with the same URLs, then restart the service.

SPLUNK_TRACE_URL is derived automatically from SPLUNK_INGEST_URL at runtime unless you have explicitly set it. If you have, update it as well.

MSI upgrade (Windows)

Upgrading via msiexec applies the new *.observability.splunkcloud.com defaults. To keep the legacy endpoints, pass them as MSI properties:

msiexec /i <path\to\msi> SPLUNK_API_URL=https://api.<realm>.signalfx.com SPLUNK_INGEST_URL=https://ingest.<realm>.signalfx.com SPLUNK_HEC_URL=https://ingest.<realm>.signalfx.com/v1/log

New installation

New installations default to *.observability.splunkcloud.com. If your environment requires the legacy endpoints, pass them explicitly:

install.sh (add these flags):

--api-url https://api.<realm>.signalfx.com \
--ingest-url https://ingest.<realm>.signalfx.com

install.ps1 (add these flags):

-api_url https://api.<realm>.signalfx.com `
-ingest_url https://ingest.<realm>.signalfx.com

Chocolatey (add these params):

choco install splunk-otel-collector --params "'/SPLUNK_API_URL:https://api.<realm>.signalfx.com /SPLUNK_INGEST_URL:https://ingest.<realm>.signalfx.com /SPLUNK_HEC_URL:https://ingest.<realm>.signalfx.com/v1/log'"

msiexec (add these properties):

SPLUNK_API_URL=https://api.<realm>.signalfx.com SPLUNK_INGEST_URL=https://ingest.<realm>.signalfx.com SPLUNK_HEC_URL=https://ingest.<realm>.signalfx.com/v1/log

From 0.117.0 to 0.118.0

The deprecated syntax for config source expansion is no longer supported. Strings like $ENV or $include:/path/to/file.yaml will no longer be expanded. Instead, use the ${env:ENV} or ${include:/path/to/file.yaml} syntax. There are only two symbols allowed after $: { and $. The collector will log an error and fail to start if it encounters a bare config source. Please update your configuration files to use the correct syntax.

From 0.114.0 to 0.115.0

The sapm exporter still works as before but has been deprecated. Use the otlphttp exporter instead:

1. Replace the sapm exporter with otlphttp exporter using the following configuration:

   YAMLCopy

   otlphttp: traces_endpoint: "${SPLUNK_INGEST_URL}/v2/trace/otlp" headers: "X-SF-Token": "${SPLUNK_ACCESS_TOKEN}"

   otlphttp:
     traces_endpoint: "${SPLUNK_INGEST_URL}/v2/trace/otlp"
     headers:
       "X-SF-Token": "${SPLUNK_ACCESS_TOKEN}"

2. Update traces pipeline to use otlphttp exporter instead of sapm:

   YAMLCopy

   service: pipelines: traces: exporters: [otlphttp, signalfx]

   service:
     pipelines:
       traces:
         exporters: [otlphttp, signalfx]

From 0.96.1 to 0.97.0

From 0.68.0 to 0.69.0

The gke and gce resource detectors in the resourcedetection processor have been replaced with the gcp resource detector. If you have gke and gce detectors configured in the resourcedetection processor, update your configuration accordingly.

For more information, see Resource detection processor.

From 0.41.0 to 0.42.0

The Splunk Distribution of the OpenTelemetry Collector used to evaluate user configuration twice and this required escaping of each $ symbol with $$ to prevent unwanted environment variable expansion. The issue was fixed in the 0.42.0 version. Any occurrences of $$ in your configuration need to be replaced with $.

From 0.35.0 to 0.36.0

Move the config parameter exporters -> otlp -> insecure to exporters -> otlp -> tls -> insecure.

The otlp exporter configuration must look like this:

exporters:
  otlp:
    endpoint: "${SPLUNK_GATEWAY_URL}:4317"
    tls:
      insecure: true

From 0.34.0 to 0.35.0

Move the ballast_size_mib parameter from the memory_limiter processor to the memory_ballast extension, and rename it to size_mib.

extensions:
  memory_ballast:
    size_mib: ${SPLUNK_BALLAST_SIZE_MIB}