diff --git a/blog-collector/2025-09-01-otel.md b/blog-collector/2025-09-01-otel.md new file mode 100644 index 0000000000..62b8453f04 --- /dev/null +++ b/blog-collector/2025-09-01-otel.md @@ -0,0 +1,16 @@ +--- +title: Remote Management for OpenTelemetry Collector (OpenTelemetry Collector) +image: https://help.sumologic.com/img/reuse/rss-image.jpg +keywords: + - collection + - opentelemetry + - otel + - remote-management +hide_table_of_contents: true +--- + +import useBaseUrl from '@docusaurus/useBaseUrl'; + +We're happy to announce that Sumo Logic now enables you to remotely update the collector timezone for OpenTelemetry collectors through the UI in the OpenTelemetry collector edit flow. You can select the timezone of your choice while editing the collector. If you do not make a selection, the timezone will be set to `(UTC) Etc/UTC` by default. + +[Learn more](/docs/send-data/opentelemetry-collector/remote-management/source-templates/otrm-time-reference/#specifying-a-custom-timestamp-format-and-time-zone). diff --git a/docs/send-data/opentelemetry-collector/install-collector/linux.md b/docs/send-data/opentelemetry-collector/install-collector/linux.md deleted file mode 100644 index a736f90984..0000000000 --- a/docs/send-data/opentelemetry-collector/install-collector/linux.md +++ /dev/null @@ -1,391 +0,0 @@ ---- -id: linux -title: Install OpenTelemetry Collector on Linux -sidebar_label: Linux -description: Learn how to install the Sumo Logic OpenTelemetry Collector on Linux. ---- - -import useBaseUrl from '@docusaurus/useBaseUrl'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -Thumbnail icon - -Follow the steps in this topic to install or uninstall an OpenTelemetry Collector on Linux. See [OpenTelemetry Collector](/docs/send-data/opentelemetry-collector) for information on other operating systems. - -## System Requirements​ - -The Sumo Logic OpenTelemetry Collector is supported on both amd64 and arm64 architectures. - -Minimal resource requirements are the following: - -* 200 MB of disk space -* 64 MB of RAM - -Supported Versions - -* RHEL (7-9), Debian (9-11), Ubuntu (18-22), SUSE (ES12, ES15), Amazon Linux 2(AL2), Amazon Linux 2023(AL2023), CentOS (7, 8) - -## Install - -You can install our OpenTelemetry Collector using one of the following methods: - -* [UI Installation](#ui-installation) -* [Install script](#install-script) -* [Manual step-by-step installation](#manual-step-by-step-installation) - -### UI Installation - -1. [**Classic UI**](/docs/get-started/sumo-logic-ui-classic). In the main Sumo Logic menu, select **Manage Data > Collection > OpenTelemetry Collection**.
[**New UI**](/docs/get-started/sumo-logic-ui). In the Sumo Logic main menu select **Data Management**, and then under **Data Collection** select **OpenTelemetry Collection**. You can also click the **Go To...** menu at the top of the screen and select **OpenTelemetry Collection**. -1. On the OpenTelemetry Collection page, click **Add Collector**. -1. On the left panel, select **Linux** as the platform.
linux-terminal -1. Select/create installation token and customize your tags. -1. (Optional) In the **Collector Settings**, select the **Ephemeral** checkbox to auto-delete your collector after 12 hours, and select the **Locally Manage Collector** checkbox if you want to configure, maintain, and monitor your collector locally. -1. Copy the command and execute it in your system terminal where the collector needs to be installed.
execute command in terminal -1. Wait for the installation process to complete, then click **Next** to proceed. -1. On the next screen, you will see a list of available Source Templates. Select the required Source Template and proceed with the data configuration. - -If you choose to close this Source template creation screen, you can navigate back. [**Classic UI**](/docs/get-started/sumo-logic-ui-classic/). In the main Sumo Logic menu, select **Manage Data > Collection > Source Template**.
[**New UI**](/docs/get-started/sumo-logic-ui/). In the Sumo Logic main menu select **Data Management**, and then under **Data Collection** select **Source Template**. - -### Install Script - -#### 1. Get the Installation token - -Get your [installation token](/docs/manage/security/installation-tokens) if you do not have it already and assign it to an environment variable: - -```bash -export SUMOLOGIC_INSTALLATION_TOKEN= -``` - -#### 2. Run the Installation script - -You can run the script in two ways: - -* By piping `curl` straight into `bash`: - ```bash - curl -Ls https://github.com/SumoLogic/sumologic-otel-collector-packaging/releases/latest/download/install.sh | sudo -E bash -s -- --tag "host.group=default" --tag "deployment.environment=default" - ``` -* By first downloading the script, inspecting its contents for security, and then running it: - ```bash - curl -Lso install-otelcol-sumo.sh https://github.com/SumoLogic/sumologic-otel-collector-packaging/releases/latest/download/install.sh - sudo -E bash ./install-otelcol-sumo.sh - ``` - -The `-E` argument to `sudo` is needed to preserve the `SUMOLOGIC_INSTALLATION_TOKEN` environment variable in `sudo` session. - -This will perform the following operations: -* Install or upgrade operation by placing the latest version as `/usr/local/bin/otelcol-sumo` -* Get [static configuration](https://github.com/SumoLogic/sumologic-otel-collector/blob/main/examples/sumologic.yaml) 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 will get [Systemd service configuration][service file] and place it as `/etc/systemd/system/otelcol-sumo.service` - * Create a `otelcol-sumo` user and group that will be used to run the service - * Enable `otelcol-sumo` service - * Start `otelcol-sumo` service - -#### 3. Script Options - -The following arguments can be passed to the script: - -| long name | short name | description | takes value | -|:----------------------------|:-----------|:--------------|:-------------| -| `--skip-installation-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 default, it gets latest version. | Yes, e.g. `0.94.0-sumo-2` | -| `--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 [FIPS section](#fips) for more details. | No | -| `--install-hostmetrics` | `H` | Install the hostmetrics configuration to collect host metrics. | 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. | - -The following env variables can be used along with script: - -| name | description | -|:-------------------|:-----------------| -| `SUMOLOGIC_INSTALLATION_TOKEN` | Installation token | - -### Manual step-by-step Installation - -#### Step 1. Download the Binary - -Examples for OpenTelemetry Collector version `0.94.0-sumo-2`. - - - - - -```bash -curl -sLo otelcol-sumo \ -"https://github.com/SumoLogic/sumologic-otel-collector/releases/download/v0.94.0-sumo-2/otelcol-sumo-0.94.0-sumo-2-linux_amd64" -``` - - - - -```bash -curl -sLo otelcol-sumo \ -"https://github.com/SumoLogic/sumologic-otel-collector/releases/download/v0.94.0-sumo-2/otelcol-sumo-0.94.0-sumo-2-linux_arm64" -``` - - - - -#### Step 2. Move the binary to your `PATH` environment - -Move the downloaded binary into a directory from your `PATH` environment, so that it can be used by simply invoking `otelcol-sumo`. - -```bash -chmod +x otelcol-sumo -sudo mv otelcol-sumo /usr/local/bin/otelcol-sumo -``` - -#### Step 3. Verify the Installation - -To verify installation, run the OpenTelemetry Collector. - -```bash -otelcol-sumo --version -``` - -#### Step 4. Run OpenTelemetry Collector as Systemd Service - -We recommend using the [installation script](#install-script) as it supports the Systemd scenario. This section describes how to install it manually. - -:::info prerequisites -Ensure that the user who will run the `otelcol-sumo` process has access to any directories used in your configuration within the filesystem. -::: - -For example, if you use the [file_storage extension](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/extension/storage/filestorage) in your configuration like this: - -```yaml -extensions: -file_storage/custom_settings: -directory: /var/lib/otelcol/mydir -timeout: 1s -``` - -Then the user running the process must have access to `/var/lib/otelcol/mydir`. - -To run OpenTelemetry Collector as Systemd Service, follow the steps below: - -1. Ensure that `otelcol-sumo` has been installed into `/usr/local/bin/otelcol-sumo` by running this command. - ```bash - /usr/local/bin/otelcol-sumo --version - ``` -1. Create configuration, follow the steps below. - 1. Get [recommended configuration](https://github.com/SumoLogic/sumologic-otel-collector/blob/main/examples/sumologic.yaml) from Sumo Logic repository and save it as `/etc/otelcol-sumo/sumologic.yaml`. - 1. Create your custom configuration file in the `/etc/otelcol-sumo/conf.d` directory. For example, you can create a file called `common.yaml` in this directory to store your custom configuration, like this `/etc/otelcol-sumo/conf.d/common.yaml`. - :::note - It is recommended to limit access to the configuration file as it contains sensitive information. - ::: - 1. You can change the access permissions to the configuration file by running the following command: - ```bash - mkdir -p /etc/otelcol-sumo/{conf.d,env} - chmod 551 /etc/otelcol-sumo /etc/otelcol-sumo/{conf.d,env} - chmod 440 /etc/otelcol-sumo/conf.d/common.yaml /etc/otelcol-sumo/sumologic.yaml - ``` -1. Create `user` and `group` to run OpenTelemetry by running the following command: - ```bash - sudo useradd -mrUs /bin/false -d /var/lib/otelcol-sumo otelcol-sumo - ``` - * 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 do not want the user to have a home directory, use `useradd` with the `M` flag instead of `m` (`sudo useradd -MrUs ...`) and explicitly change the directory for saving the credentials. For example: - ```yaml - extensions: - sumologic: - # ... - collector_credentials_directory: /var/lib/otelcol-sumo/credentials - ``` - For more information, refer to the [sumologic extension](https://github.com/SumoLogic/sumologic-otel-collector/tree/main/pkg/extension/sumologicextension#configuration) documentation. -1. Ensure that the configuration can be accessed by `otelcol-sumo` user which will be used to run the service by running this command. - ```bash - $ sudo find /etc/otelcol-sumo/ -type 'f' | sudo xargs ls -al - -r--r----- 1 otelcol-sumo otelcol-sumo 48 Feb 16 09:00 /etc/otelcol-sumo/conf.d/common.yaml - -r--r----- 1 otelcol-sumo otelcol-sumo 4569 Feb 16 09:00 /etc/otelcol-sumo/sumologic.yaml - ``` -1. Verify if OpenTelemetry collector runs without errors by running this command: - ```bash - sudo su -s /bin/bash otelcol-sumo -c '/usr/local/bin/otelcol-sumo --config /etc/otelcol-sumo/sumologic.yaml --config "glob:/etc/otelcol-sumo/conf.d/*.yaml"' - ``` -1. Get [service file] and save as `/etc/systemd/system/otelcol-sumo.service`: - ```bash - curl https://raw.githubusercontent.com/SumoLogic/sumologic-otel-collector/main/examples/systemd/otelcol-sumo.service | sudo tee /etc/systemd/system/otelcol-sumo.service - ``` - :::note - Adjust memory configuration to your setup. - ::: -1. Enable autostart of the service by running the following command: - ```bash - sudo systemctl enable otelcol-sumo - ``` -1. Start service and check status by running the following command: - ```bash - sudo systemctl start otelcol-sumo - sudo systemctl status otelcol-sumo # checks status - sudo journalctl -u otelcol-sumo # checks logs - ``` - -#### Using Environmental variable to store Installation token - -We recommend keeping the install token in environmental variable for `Systemd` installation: - -1. Ensure that the service file `/etc/systemd/system/otelcol-sumo.service` contains `EnvironmentFile=-/etc/otelcol-sumo/env/*.env` by running this command. - ```shell - $ sudo cat /etc/systemd/system/otelcol-sumo.service - [Service] - ... - EnvironmentFile=-/etc/otelcol-sumo/env/*.env - ``` -1. Ensure that the `/etc/otelcol-sumo/env` directory exists by running this command. - ```bash - sudo mkdir -p /etc/otelcol-sumo/env - ``` -1. Create the `/etc/otelcol-sumo/env/token.env` file with your installation token. In this example, we use `SUMOLOGIC_INSTALLATION_TOKEN`, as it will be automatically used by the recommended configuration. - ```bash - SUMOLOGIC_INSTALLATION_TOKEN= - ``` -1. Ensure that the file has the correct owner and permissions by running this command. - ```bash - sudo chmod 440 /etc/otelcol-sumo/env/token.env - sudo chown otelcol-sumo:otelcol-sumo /etc/otelcol-sumo/env/token.env - ``` -1. Remove `install_token` overrides from `/etc/otelcol-sumo/conf.d/*.yaml`. You can find them using the following command: - ```shell - $ sudo grep -Rn install_token /etc/otelcol-sumo/conf.d - /etc/otelcol-sumo/conf.d/common.yaml:3: install_token: - ``` -1. Restart `otelcol-sumo` service by running this command. - ```bash - sudo systemctl restart otelcol-sumo - ``` - -#### Running Binary Manually - -If your system does not support `Systemd`, or you do not want to create a service, you can run Collector manually. - -```bash -sudo otelcol-sumo --config=/etc/otelcol-sumo/sumologic.yaml --config "glob:/etc/otelcol-sumo/conf.d/*.yaml" -``` - -### Additional Settings - -This section describes common OpenTelemetry customizations. - -#### Using Proxy - -Exporters leverage the HTTP communication and respect the following proxy environment variables: - -* `HTTP_PROXY` -* `HTTPS_PROXY` -* `NO_PROXY` - -You may either export proxy environment variables locally, for example: - -```bash -export FTP_PROXY=: -export HTTP_PROXY=: -export HTTPS_PROXY=: -``` - -or make them available globally for all users, e.g. - -```bash -tee -a /etc/profile << END -export FTP_PROXY=: -export HTTP_PROXY=: -export HTTPS_PROXY=: -END -``` - -To exclude a specific domain or IP address from using the proxy, you can add it to the `NO_PROXY` environment variable. For example, to exclude the domain `sumologic.com` from using the proxy, you can add the following command: - -`export NO_PROXY=sumologic.com` - -:::note -For Systemd service, the variables can be placed in `/etc/otelcol-sumo/env/proxy.env`, as default configuration (`EnvironmentFile=-/etc/otelcol-sumo/env/*.env`) will load them automatically. -Service need to be restarted in order to apply the changes. -::: - -#### FIPS - -To install FIPS compliant binary, you should add `--fips` switch to installation command, so it will look like the following: - -```bash -curl -Ls https://github.com/SumoLogic/sumologic-otel-collector-packaging/releases/latest/download/install.sh | SUMOLOGIC_INSTALLATION_TOKEN="TOKEN" sudo -E bash -s -- --tag "host.group=default" --tag "deployment.environment=default" --fips && sudo otelcol-sumo --config=/etc/otelcol-sumo/sumologic.yaml --config "glob:/etc/otelcol-sumo/conf.d/*.yaml" -``` - -Refer to [BoringCrypto and FIPS compliance](https://github.com/SumoLogic/sumologic-otel-collector/blob/main/docs/fips.md) in our repository for more details. - -## Uninstall - -The recommended way to uninstall the OpenTelemetry Collector depends on how you installed it. - -### Install Script - -If you installed the Collector with the install script, you can this command to uninstall the Collector: - -```bash -curl -Ls https://github.com/SumoLogic/sumologic-otel-collector-packaging/releases/latest/download/install.sh | sudo -E bash -s -- -u -y -``` - -You can also use flag `-p` to remove all existing configurations as well: - -```bash -curl -Ls https://github.com/SumoLogic/sumologic-otel-collector-packaging/releases/latest/download/install.sh | sudo -E bash -s -- -u -y -p -``` - -### Manual step-by-step Uninstall - -If you installed the Collector manually, simply remove the binary from the directory you have placed it in by running the following command: - -```bash -sudo rm /usr/local/bin/otelcol-sumo -``` - -## Upgrading the Collector - -### Upgrade OpenTelemetry Collector - -First, you have to upgrade the Collector's version. The way you should do it, depends on how you installed it. - -#### Install Script - -Running install script will simply upgrade collector to the latest version: - -```bash -curl -Ls https://github.com/SumoLogic/sumologic-otel-collector-packaging/releases/latest/download/install.sh | sudo bash -``` - -:::note -You need to restart collector process manually in order to apply changes. -::: - -#### Manual step-by-step Installation - -If you installed the Collector manually, the simplest way to upgrade is to follow these steps: - -* [Uninstall the Collector manually](#manual-step-by-step-installation-1) -* [Install the Collector again with a new version](#manual-step-by-step-installation) - -### Update your Config - -After an upgrade, you should make sure that your config for OpenTelemetry Collector is up to date. - -To see changes in upstream OpenTelemetry components, refer to the [core changelog](https://github.com/open-telemetry/opentelemetry-collector/releases) and [contrib changelog](https://github.com/open-telemetry/opentelemetry-collector-contrib/releases). - -List of breaking changes specific to Sumo Logic Distribution of OpenTelemetry Collector can be found [here](https://github.com/SumoLogic/sumologic-otel-collector/blob/main/docs/upgrading.md). - -## Troubleshooting - -For information on troubleshooting and solutions, refer to [Troubleshooting](/docs/send-data/opentelemetry-collector/troubleshooting). - -[service file]: https://github.com/SumoLogic/sumologic-otel-collector/blob/main/examples/systemd/otelcol-sumo.service diff --git a/docs/send-data/opentelemetry-collector/install-collector/macos.md b/docs/send-data/opentelemetry-collector/install-collector/macos.md deleted file mode 100644 index ae7fa20597..0000000000 --- a/docs/send-data/opentelemetry-collector/install-collector/macos.md +++ /dev/null @@ -1,393 +0,0 @@ ---- -id: macos -title: Install OpenTelemetry Collector on macOS -sidebar_label: macOS -description: Learn how to install the Sumo Logic OpenTelemetry Collector on macOS. ---- - -import useBaseUrl from '@docusaurus/useBaseUrl'; -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -macOS - -Follow the steps in this topic to install or uninstall an OpenTelemetry Collector on macOS. See [OpenTelemetry Collector](/docs/send-data/opentelemetry-collector) for information on other operating systems. - -## System Requirements​ - -The Sumo Logic OpenTelemetry Collector is supported on both amd64 and arm64 architectures. - -Minimal resource requirements are the following: - -* 200 MB of disk space -* 64 MB of RAM - -Versions Supported - -* macOS 10.X and up - -## Install - -You can install our OpenTelemetry Collector using one of the following methods: - -* [UI Installation](#ui-installation) -* [Install script](#install-script) -* [Manual step-by-step installation](#manual-step-by-step-installation) - -### UI Installation - -1. [**Classic UI**](/docs/get-started/sumo-logic-ui-classic). In the main Sumo Logic menu, select **Manage Data > Collection > OpenTelemetry Collection**.
[**New UI**](/docs/get-started/sumo-logic-ui). In the Sumo Logic main menu select **Data Management**, and then under **Data Collection** select **OpenTelemetry Collection**. You can also click the **Go To...** menu at the top of the screen and select **OpenTelemetry Collection**. -1. On the OpenTelemetry Collection page, click **Add Collector**. -1. On the left panel, select **macOS** as the platform.
macOs-terminal -1. Select/create installation token and customize your tags. -1. (Optional) In the **Collector Settings**, select the **Ephemeral** checkbox to auto-delete your collector after 12 hours, and select the **Locally Manage Collector** checkbox if you want to configure, maintain, and monitor your collector locally. -1. Copy the command and execute it in your system terminal where the collector needs to be installed.
execute command in terminal -1. Wait for the installation process to complete, then click **Next** to proceed. -1. On the next screen, you will see a list of available Source Templates. Select the required Source Template and proceed with the data configuration. - -If you choose to close this Source template creation screen, you can navigate back. [**Classic UI**](/docs/get-started/sumo-logic-ui-classic/). In the main Sumo Logic menu, select **Manage Data > Collection > Source Template**.
[**New UI**](/docs/get-started/sumo-logic-ui/). In the Sumo Logic main menu select **Data Management**, and then under **Data Collection** select **Source Template**. -### Install Script - -#### Get the Installation token - -Get your [installation token](/docs/manage/security/installation-tokens) (if you do not have it already) and assign it to an environment variable: - -```bash -export SUMOLOGIC_INSTALLATION_TOKEN= -``` - -#### Run the installation script - -You can run the script in two ways: - -* By piping `curl` straight into `bash`: - ```bash - sudo curl -Ls https://github.com/SumoLogic/sumologic-otel-collector-packaging/releases/latest/download/install.sh | sudo -E bash -s -- --tag "host.group=default" --tag "deployment.environment=default" && sudo otelcol-sumo --config=/etc/otelcol-sumo/sumologic.yaml --config "glob:/etc/otelcol-sumo/conf.d/*.yaml" - ``` -* Or by first downloading the script, inspecting its contents for security, and then running it: - ```bash - curl -Lso install-otelcol-sumo.sh https://github.com/SumoLogic/sumologic-otel-collector-packaging/releases/latest/download/install.sh - sudo -E bash ./install-otelcol-sumo.sh -d - ``` - -The `-E` argument to `sudo` is needed to preserve the `SUMOLOGIC_INSTALLATION_TOKEN` environment variable in `sudo` session. - -The `-d` argument to the script is needed on macOS. It will skip Systemd installation, which is not supported on macOS. - -It will perform the following operations: - -* Install or upgrade operation by placing the latest version as `/usr/local/bin/otelcol-sumo` -* Get [static configuration](https://github.com/SumoLogic/sumologic-otel-collector/blob/main/examples/sumologic.yaml) 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 - -#### Script Options - -The following arguments can be passed to the script: - -| long name | short name | description | takes value | -|:----------|:-----------|:------------|:---------------| -| `--skip-installation-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 default, it gets latest version. | Yes (for example: `0.94.0-sumo-2`) | -| `--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 [FIPS section](#fips) for more details. | No | -| `--install-hostmetrics` | `H` | Install the hostmetrics configuration to collect host metrics. | 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_INSTALLATION_TOKEN` | Installation token | - -### Manual step-by-step Installation - -#### Step 1. Download the binary - -Examples for OpenTelemetry Collector version `0.94.0-sumo-2`. - - - - - -```bash -curl -sLo otelcol-sumo "https://github.com/SumoLogic/sumologic-otel-collector/releases/download/v0.94.0-sumo-2/otelcol-sumo-0.94.0-sumo-2-darwin_amd64" -``` - - - - -```bash -curl -sLo otelcol-sumo "https://github.com/SumoLogic/sumologic-otel-collector/releases/download/v0.94.0-sumo-2/otelcol-sumo-0.94.0-sumo-2-darwin_arm64" -``` - - - - - -#### Step 2. Move the binary to your `PATH` environment - -Move the downloaded binary into a directory from your `PATH` environment so that it can be used by simply invoking `otelcol-sumo`. - -```bash -chmod +x otelcol-sumo -sudo mv otelcol-sumo /usr/local/bin/otelcol-sumo -``` - -#### Step 3. Verify the Installation - -To verify installation, run the OpenTelemetry Collector. - -```bash -otelcol-sumo --version -``` - -#### Step 4. Running Binary - -As for now, we do not support installation of OpenTelemetry Collector as service for macOS. It needs to be run manually. - -```bash -sudo otelcol-sumo --config=/etc/otelcol-sumo/sumologic.yaml --config "glob:/etc/otelcol-sumo/conf.d/*.yaml" -``` - -### Additional settings - -This section describes common OpenTelemetry customizations. - -#### Using Proxy - -Exporters leverage the HTTP communication and respect the following proxy environment variables: - -* `HTTP_PROXY` -* `HTTPS_PROXY` -* `NO_PROXY` - -You can either export proxy environment variables locally, e.g. - -```bash -export FTP_PROXY=: -export HTTP_PROXY=: -export HTTPS_PROXY=: -``` - -or make them available globally for all users, e.g. - -```bash -tee -a /etc/profile << END -export FTP_PROXY=: -export HTTP_PROXY=: -export HTTPS_PROXY=: -END -``` - -To exclude a specific domain or IP address from using the proxy, you can add it to the `NO_PROXY` environment variable. For example, to exclude the domain `sumologic.com` from using the proxy, you can add the following command: - -```bash -export NO_PROXY=sumologic.com -``` - -#### FIPS - -We currently do not build FIPS binary for macOS. Refer to [BoringCrypto and FIPS compliance](https://github.com/SumoLogic/sumologic-otel-collector/blob/main/docs/fips.md) in our repository for more details. - -## Uninstall - -The recommended way to uninstall the OpenTelemetry Collector depends on how you installed it. - -### Install script - -If you installed the Collector with the install script, you can use it to uninstall the Collector: - -```bash -sudo curl -Ls https://github.com/SumoLogic/sumologic-otel-collector-packaging/releases/latest/download/install.sh | sudo -E bash -s -- -u -y -``` - -You can also use flag `-p` to remove all existing configurations as well: - -```bash -sudo curl -Ls https://github.com/SumoLogic/sumologic-otel-collector-packaging/releases/latest/download/install.sh | sudo -E bash -s -- -u -y -p -``` - -You can also run the following command to clear the cache. This will remove any cached data associated with the Collector. - -```bash -sudo rm -rf /var/cache/otelcol-sumo -``` - -### Manual step-by-step installation - -If you installed the Collector manually, simply remove the binary from the directory you have placed it in: - -```bash -sudo rm /usr/local/bin/otelcol-sumo -``` - -## Upgrading the collector - -### Upgrade OpenTelemetry Collector - -First, you have to upgrade the Collector's version. The way you should do it, depends on how you installed it. - -#### Install script - -Running install script will simply upgrade collector to the latest version: - -```bash -sudo curl -Ls https://github.com/SumoLogic/sumologic-otel-collector-packaging/releases/latest/download/install.sh | sudo bash -``` - -:::note -You'll need to restart the collector process manually in order to apply changes. -::: - -#### Manual step-by-step installation - -If you installed the Collector manually, the simplest way to upgrade is to follow these steps: - -* [Uninstall the Collector manually](#manual-step-by-step-installation-1) -* [Install the Collector again with a new version](#manual-step-by-step-installation) - -### Update your config - -After an upgrade, you should make sure that your config for OpenTelemetry Collector is up to date. - -To see changes in upstream OpenTelemetry components, refer to the [core changelog](https://github.com/open-telemetry/opentelemetry-collector/releases) and [contrib changelog](https://github.com/open-telemetry/opentelemetry-collector-contrib/releases). - -List of breaking changes specific to Sumo Logic Distribution of OpenTelemetry Collector can be found [here](https://github.com/SumoLogic/sumologic-otel-collector/blob/main/docs/upgrading.md). - -## Troubleshooting - -For general Sumo Logic OTel Collector troubleshooting, refer to [Troubleshooting](/docs/send-data/opentelemetry-collector/troubleshooting). - -Here are some troubleshooting steps specific to macOS. - -### uninstall.sh: No such file or directory error when uninstalling collector - -If you're trying to uninstall the collector on macOS, and you see an error similar to the following: - -```console -$ sudo curl -Ls https://github.com/SumoLogic/sumologic-otel-collector-packaging/releases/latest/download/install.sh | sudo -E bash -s -- -u -y -p -Detected OS type: darwin -Detected architecture: arm64 -Going to uninstall otelcol-sumo. -main: line 785: /Library/Application Support/otelcol-sumo/uninstall.sh: No such file or directory -``` - -This means that you've installed the collector before the installation script was able to use packages in macOS. - -To uninstall, use an older version of the installation script: - -```shell -sudo curl -L https://github.com/SumoLogic/sumologic-otel-collector-packaging/releases/latest/download/install.sh | sudo -E bash -s -- --uninstall --purge --yes -``` - -The output should be similar to this: - -```console -$ sudo curl -L https://github.com/SumoLogic/sumologic-otel-collector-packaging/releases/latest/download/install.sh | sudo -E bash -s -- --uninstall --purge --yes - % Total % Received % Xferd Average Speed Time Time Time Current - Dload Upload Total Spent Left Speed - 0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0 -100 48284 100 48284 0 0 64169 0 --:--:-- --:--:-- --:--:-- 64169 -Going to remove Otelcol binary, user, file storage and configurations. -Uninstallation completed -``` - -### Verify that the 'launchd' daemon has been installed - -```console -$ sudo launchctl list | grep otelcol-sumo -54109 0 otelcol-sumo -``` - -### Verify that the 'launchd' daemon is running - -```console -$ sudo launchctl print system/otelcol-sumo -system/otelcol-sumo = { - active count = 1 - path = /Library/LaunchDaemons/com.sumologic.otelcol-sumo.plist - type = LaunchDaemon - state = running - - program = /usr/local/bin/otelcol-sumo - arguments = { - /usr/local/bin/otelcol-sumo - --config - /etc/otelcol-sumo/sumologic.yaml - --config - glob:/etc/otelcol-sumo/conf.d/*.yaml - } - - stdout path = /var/log/otelcol-sumo/otelcol-sumo.log - stderr path = /var/log/otelcol-sumo/otelcol-sumo.log - default environment = { - PATH => /usr/bin:/bin:/usr/sbin:/sbin - } - - environment = { - SUMOLOGIC_INSTALLATION_TOKEN=(redacted) => - XPC_SERVICE_NAME => otelcol-sumo - } - - domain = system - username = _otelcol-sumo - group = _otelcol-sumo - - minimum runtime = 10 - exit timeout = 5 - runs = 1 - pid = 54109 - immediate reason = speculative - forks = 2 - execs = 1 - initialized = 1 - trampolined = 1 - started suspended = 0 - proxy started suspended = 0 - last exit code = (never exited) - - spawn type = daemon (3) - jetsam priority = 40 - jetsam memory limit (active) = (unlimited) - jetsam memory limit (inactive) = (unlimited) - jetsamproperties category = daemon - submitted job. ignore execute allowed - jetsam thread limit = 32 - cpumon = default - probabilistic guard malloc policy = { - activation rate = 1/1000 - sample rate = 1/0 - } - - properties = keepalive | runatload | inferred program -} -``` - -The output should include `active count = 1` and `state = running`. This means the daemon is running. - -### Verify that the collector process is running - -```shell -$ ps aux | grep '[o]telcol-sumo' -_otelcol-sumo 55368 0.0 0.2 409731808 125232 ?? Ss 12:25PM 0:00.21 /usr/local/bin/otelcol-sumo --config /etc/otelcol-sumo/sumologic.yaml --config glob:/etc/otelcol-sumo/conf.d/*.yaml -``` - -### View logs from the collector - -```shell -cat /var/log/otelcol-sumo/otelcol-sumo.log -``` - -For more troubleshooting, refer to [Troubleshooting](/docs/send-data/opentelemetry-collector/troubleshooting). diff --git a/docs/send-data/opentelemetry-collector/install-collector/windows.md b/docs/send-data/opentelemetry-collector/install-collector/windows.md deleted file mode 100644 index eedc77493d..0000000000 --- a/docs/send-data/opentelemetry-collector/install-collector/windows.md +++ /dev/null @@ -1,205 +0,0 @@ ---- -id: windows -title: Install OpenTelemetry Collector on Windows -sidebar_label: Windows -description: Install the OpenTelemetry Collector on Windows to collect metrics and logs for end-to-end observability in Sumo Logic environments. ---- - -import useBaseUrl from '@docusaurus/useBaseUrl'; - -thumbnail icon - -Follow the steps in this topic to install or uninstall an OpenTelemetry Collector on Windows. See [OpenTelemetry Collector](/docs/send-data/opentelemetry-collector) for information on other operating systems. - -## System Requirements - -Minimal resource requirements are the following: - -* 200 MB of disk space -* 64 MB of RAM - -Supported Versions - -* Windows 10 and up, Windows Server 2016 and up - -## Install - -You can install our OpenTelemetry Collector using either of the following methods: - -* [UI Installation](#ui-installation) -* [Install script](#install-script) -* [Manual step-by-step installation](#manual-step-by-step-installation) - -### UI Installation - -1. [**Classic UI**](/docs/get-started/sumo-logic-ui-classic). In the main Sumo Logic menu, select **Manage Data > Collection > OpenTelemetry Collection**.
[**New UI**](/docs/get-started/sumo-logic-ui). In the Sumo Logic main menu select **Data Management**, and then under **Data Collection** select **OpenTelemetry Collection**. You can also click the **Go To...** menu at the top of the screen and select **OpenTelemetry Collection**. -1. On the OpenTelemetry Collection page, click **Add Collector**. -1. On the left panel, select **Windows** as the platform.
widows-terminal -1. Select/create installation token and customize your tags. -1. (Optional) In the **Collector Settings**, select the **Ephemeral** checkbox to auto-delete your collector after 12 hours and select the **Locally Manage Collector** checkbox if you want to configure, maintain, and monitor the collector locally. -1. Copy the command. -1. Open PowerShell and execute the command in the PowerShell where the collector needs to be installed.
windows-ui-installation-6.png -1. Wait for the installation process to complete, then click **Next** to proceed. -1. On the next screen, you will see a list of available Source Templates. Select the required Source Template and proceed with the data configuration. - -If you choose to close this Source template creation screen, you can navigate back. [**Classic UI**](/docs/get-started/sumo-logic-ui-classic/). In the main Sumo Logic menu, select **Manage Data > Collection > Source Template**.
[**New UI**](/docs/get-started/sumo-logic-ui/). In the Sumo Logic main menu select **Data Management**, and then under **Data Collection** select **Source Template**. - -### Install Script - -A single line installation powered by Install Script. - -#### Get the Installation Token - -Get your [installation token](/docs/manage/security/installation-tokens) if you do not have it already. We are going to refer to this token as `` in next streps. - -#### Run Installation Script - -Run the following command in the same PowerShell window, replacing `` with your token from previous step: - -```sh -Set-ExecutionPolicy RemoteSigned -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; $uri = "https://github.com/SumoLogic/sumologic-otel-collector-packaging/releases/latest/download/install.ps1"; $path="${env:TEMP}\install.ps1"; (New-Object System.Net.WebClient).DownloadFile($uri, $path); . $path -InstallationToken "" -Tags @{"host.group" = "default"; "deployment.environment" = "default"} -``` - -The script is going to perform the following operations: - -* Install or upgrade operation by placing the latest version as `C:\Program Files\Sumo Logic\OpenTelemetry Collector\bin` -* Get [static configuration](https://github.com/SumoLogic/sumologic-otel-collector/blob/main/examples/sumologic.yaml) and place it as `C:\ProgramData\Sumo Logic\OpenTelemetry Collector\config\sumologic.yaml` -* Create user configuration directory (`C:\ProgramData\Sumo Logic\OpenTelemetry Collector\config\conf.d`) with `common.yaml` file which will contain installation token -* Create `OtelcolSumo` (`Sumo Logic OpenTelemetry Collector`) service - -#### Script Options - -| Name | Description | Takes Value | -|:---------------|:----------------|:-------------| -| `-InstallationToken` | Installation token | Yes | -| `-Tags` | Sets tags for collector. This argument should be a map. | Yes, for example `@{"host.group" = "default"; "deployment.environment" = "default"}` | -| `-InstallHostMetrics` | Installs the hostmetrics configuration to collect host metrics. The default is `$False`. | Yes, for example: `-InstallHostMetrics $True` or `-InstallHostMetrics $False`. | -| `-Fips` | If set to `$True`, installs the FIPS-compliant binary. The default is `$False`. See [FIPS](#fips) section for more details. | Yes, for example: `-Fips $True` or `-Fips $False` | -| `-Version` | Version of Sumo Logic Distribution for OpenTelemetry Collector to install. By default, it gets latest version. | Yes, for example: `-Version 0.94.0-sumo-2` | - -### Manual Step-by-Step Installation - -1. Go to the [latest release documentation](https://github.com/SumoLogic/sumologic-otel-collector-packaging/releases/latest). -2. Download `otelcol-sumo_x.y.z.0_en-US.x64.msi` from the `Assets` section.
windows-installation.png -3. Run Installer.
windows-installation-1.png -4. Read and accept End-User License Agreement.
windows-installation-2.png -5. Select binary destination.
windows-installation-3.png -6. Set Installation Token and Tags properties.
windows-installation-4.png -7. Click **Install** to begin installation.
windows-installation-5.png -8. Wait for installation to be completed.
windows-stallation-6.png -9. You can modify configuration, which should be placed in `C:\ProgramData\Sumo Logic\OpenTelemetry Collector\config` directory. - :::note - `C:\ProgramData` directory is hidden by default. - ::: - -### Verify the Installation - -Run the following command in PowerShell: - -```sh -> Get-Service OtelcolSumo - -Status Name DisplayName ------- ---- ----------- -Running OtelcolSumo Sumo Logic OpenTelemetry Collector -``` -Alternatively, you can open `Services.msc` and check whether Sumo Logic OTel Collector Service is running or not. - -### Additional Settings - -This section describes common OpenTelemetry customizations. - -#### Using Proxy - -Exporters leverage the HTTP communication and respect the following proxy environment variables: - -* `HTTP_PROXY` -* `HTTPS_PROXY` -* `NO_PROXY` - -You can set it by adding the following properties to Windows Registry key `HKLM:\SYSTEM\CurrentControlSet\Services\OtelcolSumo\Environment`: - -```text -FTP_PROXY=: -HTTP_PROXY=: -HTTPS_PROXY=: -``` - -You can do it using the following PowerShell command: - -```powershell -Set-ItemProperty ` - -Path 'HKLM:\SYSTEM\CurrentControlSet\Services\OtelcolSumo' ` - -Name Environment ` - -Type MultiString ` - -Value "FTP_PROXY=:", - "HTTP_PROXY=:", - "HTTPS_PROXY=:" -``` - -To exclude a specific domain or IP address from using the proxy, you can add it to the `NO_PROXY` environment variable. For example, to exclude the domain `sumologic.com` from using the proxy, you can add the following line: - -```text -NO_PROXY=sumologic.com -``` - -:::info -Restart `Sumo Logic OpenTelemetry Collector` (`OtelcolSumo`) service to apply the changes. -::: - -#### FIPS - -To install FIPS compliant binary, add `-Fips $True` option to the installation command. - -Refer to [BoringCrypto and FIPS compliance](https://github.com/SumoLogic/sumologic-otel-collector/blob/main/docs/fips.md) in our repository for more details. - -## Uninstall - -1. Go to **Add or remove programs**.
windows-uninstallation-1.png -1. Find **OpenTelemetry Collector** and click **Uninstall**.
windows-uninstallation-2.png -1. Confirm the uninstallation.
windows-uninstallation-3.png - -## Upgrading the Collector - -To upgrade the collector perform installation step and it will automatically upgrade the binary in-place. - -## Troubleshooting - -### Cannot restart service during Installation - -If you get the following output while restarting the service: - -```shell -> Restart-Service -Name OtelcolSumo -Restart-Service : Service 'Sumo Logic OpenTelemetry Collector (OtelcolSumo)' cannot be stopped due to the following -error: Cannot open OtelcolSumo service on computer '.'. -At line:1 char:1 -+ Restart-Service -Name OtelcolSumo -+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - + CategoryInfo : CloseError: (System.ServiceProcess.ServiceController:ServiceController) [Restart-Service - ], ServiceCommandException - + FullyQualifiedErrorId : CouldNotStopService,Microsoft.PowerShell.Commands.RestartServiceCommand -``` - -Ensure that you run **PowerShell** as an Administrator. - -For information on troubleshooting and solutions, refer to the [Troubleshooting](/docs/send-data/opentelemetry-collector/troubleshooting). - -### Error when running the FIPS binary: `panic: cngcrypto: not in FIPS mode` - -If you installed the FIPS version of the OpenTelemetry Collector and are getting the following error when trying to run it: - -```console -C:\>"C:\Program Files\Sumo Logic\OpenTelemetry Collector\bin\otelcol-sumo.exe" --version -panic: cngcrypto: not in FIPS mode - -goroutine 1 [running]: -crypto/internal/backend.init.0() - crypto/internal/backend/cng_windows.go:34 +0x85 -``` - -This means you are running the Sumo Logic Otelcol FIPS binary in a non-FIPS environment. The FIPS binary is built using the `requirefips` mode, which means that the collector only works in a FIPS-compliant environment and will fail to start otherwise. - -To verify if your instance is in FIPS mode, open your registry editor and navigate to **HKLM\System\CurrentControlSet\Control\Lsa\FIPSAlgorithmPolicy\Enabled**. -* If the Enabled value is `1`, then FIPS is enabled successfully. -* If the Enabled value is `0`, this means FIPS is not enabled. See the [Build option to require FIPS mode](https://github.com/microsoft/go/blob/microsoft/main/eng/doc/fips/README.md#build-option-to-require-fips-mode) documentation to enable it. diff --git a/docs/send-data/opentelemetry-collector/remote-management/source-templates/otrm-time-reference.md b/docs/send-data/opentelemetry-collector/remote-management/source-templates/otrm-time-reference.md index 823610d6c6..79492f11fc 100644 --- a/docs/send-data/opentelemetry-collector/remote-management/source-templates/otrm-time-reference.md +++ b/docs/send-data/opentelemetry-collector/remote-management/source-templates/otrm-time-reference.md @@ -46,9 +46,12 @@ OpenTelemetry Collectors can automatically parse most timestamps without any is * If you're configuring a new Source template, proceed to Step 2. Or, * To edit the timestamp settings for an existing Source template, navigate to the source template. Then click **Edit** to the right of the Source name and go to Step 2.
Screenshot showing the editing interface for a source template in Sumo Logic, highlighting the section for editing advanced options including timestamp settings 1. Navigate to the **Timestamp Parsing** section and select **Specify the format** and enter the below details: - 1. **Select Timezone**. Define the geographic location (time zone) to use while parsing a timestamp that does not include a time zone. The available locations depend on the local IANA Time Zone database. For example, `America/New_York`. For more examples, refer to the [List of tz database time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). - 1. **Format**. Specify the exact layout of the timestamp to be parsed. For example, `- %Y-%m-%dT%H:%M:%S.%LZ`. To learn more about the formatting rules, refer to [this guide](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/internal/coreinternal/timeutils/internal/ctimefmt/ctimefmt.go#L68). - 1. **Timestamp locator**. Use a [Go regular expression](https://github.com/google/re2/wiki/Syntax) to match the timestamp in your logs. Ensure the regular expression includes a named capture group called `timestamp_field`.
Screenshot of the Timestamp parsing section for logs in Sumo Logic, focusing on the timestamp format settings + 1. **Select Time Zone**. Select the timezone of your choice from the drop-down while parsing a timestamp. By default, the timezone is set to `(UTC) Etc/UTC`. The available locations depend on the local IANA Time Zone database. For more examples, refer to the [List of tz database time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
edit timezone + :::note + Ensure that the OpenTelemetry collector is enabled to edit the timezone. + ::: + 2. **Format**. Specify the exact layout of the timestamp to be parsed. For example, `- %Y-%m-%dT%H:%M:%S.%LZ`. To learn more about the formatting rules, refer to [this guide](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/internal/coreinternal/timeutils/internal/ctimefmt/ctimefmt.go#L68). + 3. **Timestamp locator**. Use a [Go regular expression](https://github.com/google/re2/wiki/Syntax) to match the timestamp in your logs. Ensure the regular expression includes a named capture group called `timestamp_field`.
Screenshot of the Timestamp parsing section for logs in Sumo Logic, focusing on the timestamp format settings ### Using _format for troubleshooting diff --git a/docs/send-data/opentelemetry-collector/view-opentelemetry-collection-page.md b/docs/send-data/opentelemetry-collector/view-opentelemetry-collection-page.md index 794208151a..111b7bd639 100644 --- a/docs/send-data/opentelemetry-collector/view-opentelemetry-collection-page.md +++ b/docs/send-data/opentelemetry-collector/view-opentelemetry-collection-page.md @@ -20,13 +20,13 @@ To view details about an OpenTelemetry Collector: Dashed line indicates there was no data ingestion in last hour. ::: - **Last Modified**. Timestamp when the collector was last modified. -1. Click on the desired collector.
opentelemetry-collection-details-page +1. Click on the desired collector.
opentelemetry-collection-details-page - **Basic Info** - **Name**. Name of the OpenTelemetry Collector. - **Collector Version**. The collector version with which the collector was created. - **Source Templates**. Displays the number of source templte - **Health**. Displays the health status of the collector. - - **Time Zone**. By default, time zone is set to UTC. + - **Time Zone**. Displays the selected time zone or the default timezone (`(UTC) Etc/UTC`). - **Collector Tags**. Displays the tags linked with the selected collector, which helps in searching and managing the collector. To add or edit the tags, refer to the [Collector Tags](/docs/send-data/opentelemetry-collector/remote-management/source-templates/manage-source-templates/#collector-tags). - **Data Ingested**. Displays the histogram which shows data ingested in last hour. This histogram timeline reflects the data ingestion timestamp as closely as possible, but minor variations may occur. :::note diff --git a/static/img/send-data/opentelemetry-collector/otel-Linux.png b/static/img/send-data/opentelemetry-collector/otel-Linux.png new file mode 100644 index 0000000000..5b8018b165 Binary files /dev/null and b/static/img/send-data/opentelemetry-collector/otel-Linux.png differ diff --git a/static/img/send-data/opentelemetry-collector/otel-Windows.png b/static/img/send-data/opentelemetry-collector/otel-Windows.png new file mode 100644 index 0000000000..6f6593e58a Binary files /dev/null and b/static/img/send-data/opentelemetry-collector/otel-Windows.png differ diff --git a/static/img/send-data/opentelemetry-collector/otel-macOS.png b/static/img/send-data/opentelemetry-collector/otel-macOS.png new file mode 100644 index 0000000000..671d7a2b5e Binary files /dev/null and b/static/img/send-data/opentelemetry-collector/otel-macOS.png differ diff --git a/static/img/send-data/otel-collector-details.png b/static/img/send-data/otel-collector-details.png new file mode 100644 index 0000000000..861d1f9d99 Binary files /dev/null and b/static/img/send-data/otel-collector-details.png differ diff --git a/static/img/send-data/otel-edit-timezone.png b/static/img/send-data/otel-edit-timezone.png new file mode 100644 index 0000000000..c97af48ec2 Binary files /dev/null and b/static/img/send-data/otel-edit-timezone.png differ