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

Run installation script:
```
bash <(curl -s https://raw.githubusercontent.com/SumoLogic/sumologic-otel-collector/main/scripts/install.sh)
```
It is going to perform install or upgrade operation by placing the latest version in /usr/local/bin,
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
```

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.55.0-sumo-0/otelcol-sumo-0.55.0-sumo-0-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.55.0-sumo-0/otelcol-sumo-0.55.0-sumo-0-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.55.0-sumo-0/otelcol-sumo-0.55.0-sumo-0-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.55.0-sumo-0/otelcol-sumo-0.55.0-sumo-0-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:
  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.55.0-sumo-0
```
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/config.yaml" "public.ecr.aws/sumologic/sumologic-otel-collector:${RELEASE_VERSION}" --config /etc/config.yaml
2021-07-06T10:31:17.477Z      info      service/application.go:277      Starting otelcol-sumo-linux_amd64...    {"Version": "v0.0.10", "NumCPU": 4}
2021-07-06T10:31:17.477Z      info      service/application.go:185      Setting up own telemetry...
2021-07-06T10:31:17.478Z      info      service/telemetry.go:98 Serving Prometheus metrics      {"address": ":8888", "level": 0, "service.instance.id": "596814dd-d8ad-4a4f-b2e9-106c29c416a0"}
2021-07-06T10:31:17.478Z      info      service/application.go:220      Loading configuration...
2021-07-06T10:31:17.479Z      info      service/application.go:236      Applying configuration...
2021-07-06T10:31:17.479Z      info      builder/exporters_builder.go:274        Exporter was built.     {"kind": "exporter", "exporter": "sumologic"}
2021-07-06T10:31:17.479Z      info      builder/pipelines_builder.go:204        Pipeline was built.     {"pipeline_name": "metrics/1", "pipeline_datatype": "metrics"}
2021-07-06T10:31:17.479Z      info      builder/receivers_builder.go:230        Receiver was built.     {"kind": "receiver", "name": "telegraf", "datatype": "metrics"}
2021-07-06T10:31:17.479Z      info      service/service.go:155  Starting extensions...
2021-07-06T10:31:17.479Z      info      builder/extensions_builder.go:53        Extension is starting...        {"kind": "extension", "name": "sumologic"}
2021-07-06T10:31:17.479Z      info      sumologicextension@v0.27.0/extension.go:128     Locally stored credentials not found, registering the collector {"kind": "extension", "name": "sumologic"}
2021-07-06T10:31:17.480Z      info      sumologicextension@v0.27.0/credentials.go:142   Calling register API    {"kind": "extension", "name": "sumologic", "URL": "https://collectors.sumologic.com/api/v1/collector/register"}
...

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 opentelemetry
```
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 opentelemetry 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 opentelemetry user which will be used to run the service.

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

Verify if opentelemetry collector runs without errors:

sudo su -s /bin/bash opentelemetry -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=opentelemetry
Group=opentelemetry
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

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

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`