Installation

The Sumo Logic Distribution for OpenTelemetry Collector can be run using either the binary file available in Github releases or the container images stored in AWS Public ECR under the following repository: public.ecr.aws/sumologic/sumologic-otel-collector.

Standalone
Container image
Systemd service
Ansible
Puppet
Chef

Standalone

Sumo Logic Distribution for OpenTelemetry Collector is a static Go binary. To run it as a standalone process you only need to run the binary file downloaded from Github releases with an appropriate configuration.

Installation using script

Get your installation token if you don't have it already and assign it to environment variable:
```
export SUMOLOGIC_INSTALL_TOKEN=<TOKEN>
```
Run installation script:

Either by piping curl straight into bash:
```
curl -s https://raw.githubusercontent.com/SumoLogic/sumologic-otel-collector/main/scripts/install.sh | sudo -E bash -s
```
or by first downloading the script, inspecting its contents for security, and then running it:
```
curl -o install-otelcol-sumo.sh https://raw.githubusercontent.com/SumoLogic/sumologic-otel-collector/main/scripts/install.sh
sudo -E bash ./install-otelcol-sumo.sh
```
The -E argument to sudo is needed to preserve the SUMOLOGIC_INSTALL_TOKEN environment variable in sudo session.

It is going to perform the following operations:
- install or upgrade operation by placing the latest version as /usr/local/bin/otelcol-sumo,
- get static configuration and place it as /etc/otelcol-sumo/sumologic.yaml
- create user configuration directory (/etc/otelcol-sumo/conf.d) with common.yaml file which will contain installation token
- for Systemd:
  - the script is going to get Systemd service configuration and place it as /etc/systemd/system/otelcol-sumo.service
  - create a otelcol-sumo user and group which will be used to run the service
  - enable otelcol-sumo service
  - start otelcol-sumo service

Script options

The following arguments can be passed to the script:

long name	short name	description	takes value
`--skip-install-token`	`k`	Skips requirement for installation token. This option do not disable default configuration creation.	no
`--tag`	`t`	Sets tag for collector. This argument can be use multiple times. One per tag.	yes, in `key=value` format
`--download-only`	`w`	Download new binary only and skip configuration part.	no
`--version`	`v`	Version of Sumo Logic Distribution for OpenTelemetry Collector to install. By defult it gets latest version.	yes, e.g. `0.57.2-sumo-1`
`--skip-config`	`s`	Do not create default configuration	no
`--skip-systemd`	`d`	Preserves from Systemd service installation.	no
`--fips`	`f`	Install the FIPS-compliant binary. See this document for more details.	no
`--yes`	`y`	Disable confirmation asks.	no
`--uninstall`	`u`	Removes Sumo Logic Distribution for OpenTelemetry Collector from the system and disable Systemd service eventually. Use with `--purge` to remove all configurations as well.	no
`--purge`	`p`	It has to be used with `--uninstall`. It removes all Sumo Logic Distribution for OpenTelemetry Collector related configuration and data.	no
`--help`	`h`	Prints help and usage.	no

The following env variables can be used along with script:

name	description
`SUMOLOGIC_INSTALL_TOKEN`	Installation token

Manual installation

Follow the steps for your platform below.

Linux on amd64 (x86-64)

Download the release binary:

curl -sLo otelcol-sumo "https://github.com/SumoLogic/sumologic-otel-collector/releases/download/v0.57.2-sumo-1/otelcol-sumo-0.57.2-sumo-1-linux_amd64"

Install the release binary in your PATH:

chmod +x otelcol-sumo
sudo mv otelcol-sumo /usr/local/bin/otelcol-sumo

Verify the installation
Prepare the configuration according to this document and save it in config.yaml.
IMPORTANT NOTE: It is recommended to limit access to the configuration file as it contains sensitive information. You can change access permissions to the configuration file using:
```
chmod 640 config.yaml
```
Run Sumo Logic Distribution for OpenTelemetry Collector:
```
otelcol-sumo --config config.yaml
```

Linux on arm64

Download the release binary:

curl -sLo otelcol-sumo "https://github.com/SumoLogic/sumologic-otel-collector/releases/download/v0.57.2-sumo-1/otelcol-sumo-0.57.2-sumo-1-linux_arm64"

Install the release binary in your PATH:

chmod +x otelcol-sumo
sudo mv otelcol-sumo /usr/local/bin/otelcol-sumo

Verify the installation
Prepare the configuration according to this document and save it in config.yaml.
IMPORTANT NOTE: It is recommended to limit access to the configuration file as it contains sensitive information. You can change access permissions to the configuration file using:
```
chmod 640 config.yaml
```
Run Sumo Logic Distribution for OpenTelemetry Collector:
```
otelcol-sumo --config config.yaml
```

MacOS on amd64 (x86-64)

Download the release binary:

curl -sLo otelcol-sumo "https://github.com/SumoLogic/sumologic-otel-collector/releases/download/v0.57.2-sumo-1/otelcol-sumo-0.57.2-sumo-1-darwin_amd64"

Install the release binary in your PATH:

chmod +x otelcol-sumo
sudo mv otelcol-sumo /usr/local/bin/otelcol-sumo

Verify the installation
Prepare the configuration according to this document and save it in config.yaml.
IMPORTANT NOTE: It is recommended to limit access to the configuration file as it contains sensitive information. You can change access permissions to the configuration file using:
```
chmod 640 config.yaml
```
Run Sumo Logic Distribution for OpenTelemetry Collector:
```
otelcol-sumo --config config.yaml
```

MacOS on arm64 (Apple M1) (x86-64)

Download the release binary:

curl -sLo otelcol-sumo "https://github.com/SumoLogic/sumologic-otel-collector/releases/download/v0.57.2-sumo-1/otelcol-sumo-0.57.2-sumo-1-darwin_arm64"

Install the release binary in your PATH:

chmod +x otelcol-sumo
sudo mv otelcol-sumo /usr/local/bin/otelcol-sumo

Verify the installation
Prepare the configuration according to this document and save it in config.yaml.
IMPORTANT NOTE: It is recommended to limit access to the configuration file as it contains sensitive information. You can change access permissions to the configuration file using:
```
chmod 640 config.yaml
```
Run Sumo Logic OT Distro:
```
otelcol-sumo --config config.yaml
```

Upgrading standalone installation

To upgrade, simply perform the above installation steps again, overwriting the otelcol-sumo binary with newer version.

Before running the newer version, make sure to check the release notes for potential breaking changes that would require manual migration steps.

Verify the installation

First of all, verify if otelcol-sumo is the right version:
```
otelcol-sumo --version
```

In order to validate the installation, the example configuration can be used. It instructs the Sumo Logic Distribution to read logs from /tmp/sumologic-demo.log and send them to Sumo Logic.

Note: For more details on configuring OT, check out the following document.

The example configuration:

exporters:
  sumologic:
    sending_queue:
      enabled: true
      storage: file_storage
  logging:

extensions:
  file_storage:
    directory: .
  sumologic:
    collector_name: sumologic-demo
    install_token: ${SUMOLOGIC_INSTALL_TOKEN}

receivers:
  filelog:
    include:
    - /tmp/sumologic-otc-example.log
    include_file_name: false
    include_file_path_resolved: true
    start_at: end

service:
  extensions: [file_storage, sumologic]
  pipelines:
    logs:
      receivers: [filelog]
      exporters: [sumologic, logging]

Please save this configuration as config.yaml.

In order to send data to Sumo you will also need an installation token.

If you have an installation token, you can run otelcol with the example configuration:
```
export SUMOLOGIC_INSTALL_TOKEN=<TOKEN>
./otelcol-sumo --config=config.yaml
```
Run _collector=sumologic-demo query in Live Tail

Generate some logs in another window:

echo "$(date --utc) ${hostname} INFO: Hello, Sumo Logic OpenTelemetry Collector Distro\!" >> /tmp/sumologic-otc-example.log

You should be able to see the log in Live Tail after a few seconds:

Container image

To run the Sumo Logic Distribution for OpenTelemetry Collector in a container, you only need to run the container using the image available in the public.ecr.aws/sumologic/sumologic-otel-collector repository.

Set the release version variable:
```
export RELEASE_VERSION=0.57.2-sumo-1
```
Prepare the configuration according to this document and save it in config.yaml.
IMPORTANT NOTE: It is recommended to limit access to the configuration file as it contains sensitive information. You can change access permissions to the configuration file using:
```
chmod 640 config.yaml
```

Run the Sumo Logic Distribution for OpenTelemetry Collector in container, e.g.

docker run --rm -ti --name sumologic-otel-collector \
   -v "$(pwd)/config.yaml:/etc/otel/config.yaml" \
   "public.ecr.aws/sumologic/sumologic-otel-collector:${RELEASE_VERSION}"

Important note about local state files when using `sumologicextension`

IMPORTANT NOTE:

When running Sumo Logic Distribution for OpenTelemetry Collector in a container with sumologicextension, one needs to take into account the local state files which are being used locally in order to store collector credentials upon successful collector registration.

When the collector is being run with sumologicextension (which manages collector registration), local directory (which is configured via collector_credentials_directory in sumologicextension, and which is by default set to $HOME/.sumologic-otel-collector) will be used to store the aforementioned state files. Without any mounts defined on the container the collector will register itself every time it starts up, creating clutter on Sumo Logic Collector Management page.

In order to avoid that, use volume mounts or any other mechanism to mount the collector credentials directory to the container to persist the state or use clobber configuration option from sumologicextension to force collector re-registering under the same name, every time is starts up.

One can read more about the above described mechanism in sumologicextension README.md.

Systemd Service

IMPORTANT NOTE:

Make sure that the user that will run the otelcol-sumo process has access to any directories within your filesystem that have been used in you configuration.

For instance, using filestorage extension in your configuration like so:
extensions:
  file_storage/custom_settings:
    directory: /var/lib/otelcol/mydir
    timeout: 1s
will require that the user running the process has access to /var/lib/otelcol/mydir.

To run opentelemetry collector as Systemd Service please apply following steps:

Ensure that otelcol-sumo has been installed into /usr/local/bin/otelcol-sumo:
```
/usr/local/bin/otelcol-sumo --version
```
Create configuration file and save it as /etc/otelcol-sumo/config.yaml.
IMPORTANT NOTE: It is recommended to limit access to the configuration file as it contains sensitive information. You can change access permissions to the configuration file using:
```
chmod 640 config.yaml
```
Create user and group to run opentelemetry by:
```
sudo useradd -mrUs /bin/false otelcol-sumo
```
IMPORTANT NOTE: This command will create a home directory for the user. By default, the sumologic extension stores the credentials in a subdirectory of the home directory. However, if the user with name otelcol-sumo already exists, it won't be overwritten, so you should make sure that a home directory has been created for this user.

If you don't want the user to have a home directory, you should use useradd without the m flag and explicitely change the directory for saving the credentials, for example:
```
extensions:
  sumologic:
    # ...
    collector_credentials_directory: /etc/otelcol-sumo/credentials
```
For more information, please refer to the documentation of sumologic extension.

Ensure that /etc/otelcol-sumo/config.yaml can be accessed by otelcol-sumo user which will be used to run the service.

$ ls -la /etc/otelcol-sumo/config.yaml
-rw-r--r-- 1 otelcol-sumo daemon 0 Feb 16 16:23 /etc/otelcol-sumo/config.yaml

Verify if opentelemetry collector runs without errors:

sudo su -s /bin/bash otelcol-sumo -c '/usr/local/bin/otelcol-sumo --config /etc/otelcol-sumo/config.yaml'

Create service file: /etc/systemd/system/otelcol-sumo.service:

[Unit]
Description=Sumologic Opentelemetry Collector

[Service]
ExecStart=/usr/local/bin/otelcol-sumo --config /etc/otelcol-sumo/config.yaml
User=otelcol-sumo
Group=otelcol-sumo
MemoryHigh=200M
MemoryMax=300M
TimeoutStopSec=20

[Install]
WantedBy=multi-user.target

Note: adjust memory configuration to your setup.

Enable autostart of the service:
```
sudo systemctl enable otelcol-sumo
```

Start service and check status:

sudo systemctl start otelcol-sumo
sudo systemctl status otelcol-sumo  # checks status
sudo journalctl -u otelcol-sumo  # checks logs

Ansible

Example installation of Sumo Logic Distribution for OpenTelemetry Collector with Ansible is described in examples/ansible.

Puppet

Example installation of Sumo Logic Distribution for OpenTelemetry Collector with Puppet is described in examples/puppet.

Chef

Example installation of Sumo Logic Distribution for OpenTelemetry Collector with Chef is described in examples/chef.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

installation.md

installation.md

Installation

Standalone

Installation using script

Script options

Manual installation

Linux on amd64 (x86-64)

Linux on arm64

MacOS on amd64 (x86-64)

MacOS on arm64 (Apple M1) (x86-64)

Upgrading standalone installation

Verify the installation

Container image

Important note about local state files when using `sumologicextension`

Systemd Service

Ansible

Puppet

Chef

Files

installation.md

Latest commit

History

installation.md

File metadata and controls

Installation

Standalone

Installation using script

Script options

Manual installation

Linux on amd64 (x86-64)

Linux on arm64

MacOS on amd64 (x86-64)

MacOS on arm64 (Apple M1) (x86-64)

Upgrading standalone installation

Verify the installation

Container image

Important note about local state files when using sumologicextension

Systemd Service

Ansible

Puppet

Chef

Important note about local state files when using `sumologicextension`