macOS - OpenTelemetry Collector

The Sumo Logic app for macOS allows you to monitor the performance and resource utilization of hosts and processes that your mission-critical applications are dependent upon.

The app consists of predefined searches and dashboards that provide visibility into your environment for real-time or historical analysis. Our dashboards provide insight into CPU load, memory, network, file descriptors, page faults, and TCP connectors. This app uses OpenTelemetry, an open-source collector for metrics.

We use the Sumo Logic Distribution for OpenTelemetry Collector for metrics collection.

The OpenTelemetry collector runs on the macOS machine, and uses the Host Metrics Receiver to obtain host and process metrics, and the Sumo Logic OpenTelemetry Exporter to send the metrics to Sumo Logic.

info

This app includes built-in monitors. For details on creating custom monitors, refer to Create monitors for macOS app.

Fields Created in Sumo Logic for macOS

Following are the fields which will be created as part of the macOS app install, if not already present. 

• sumo.datasource. Has a fixed value of mac.
• deployment.environment. This is a collector level field and is user configured (at the time of collector installation). Through this, the mac host cluster is identified by the environment where it resides. For example: dev, prod, or qa.
• host.group. This is a collector level field and is user configured (at the time of collector installation). Through this, the mac host cluster is identified.
• host.name. This is tagged through the resourcedetection processor. It holds the value of the host name where the OTel collector is installed.

Collection configuration and app installation

As part of data collection setup and app installation, you can select the App from App Catalog and click on Install App. Follow the steps below.

Step 1: Set up Collector

note

If you want to use an existing OpenTelemetry Collector, you can skip this step by selecting the Use an existing Collector option.

To create a new Collector:

1. Select the Add a new Collector option.
2. Select the platform where you want to install the Sumo Logic OpenTelemetry Collector.

This will generate a command that you can execute in the machine environment you need to monitor. Once executed, it will install the Sumo Logic OpenTelemetry Collector.

Step 2: Configure integration

In this step, you will configure the yaml required for macOS Collection.

(Optional) You can add a custom tag, if desired. (There are no parameters required for the macOS app to install.)

Enable process metric collection (Optional)

By default, the collector will not send process metrics to Sumo Logic. This is because the number of processes running on a host can be very large, which would result in a significant increase in Data Points per Minute (DPM).

Click the Enable process metric collection checkbox to collect process-level metrics.

• Name of process. Add the list of process names.
• Include/Exclude the above pattern. Signifies if you want to exclude or include the metrics for the processes listed previously.
• Match type for process name. Select if the process name given should be considered for a strict match with the host machine processes or if it should be considered as regex when matching.
  

note

If you need to edit the process list in the future, you can do this manually in the OTEL config yaml by adding or removing in the names list under process scrapper.

process:
  include:
    names: [ <process name1>, <process name2> ... ]
    match_type: <strict|regexp>

Click on the Download YAML File button to get the yaml file.

Step 3: Send metrics to Sumo Logic

Once you have downloaded the YAML file as described in the previous step, follow the below steps based on your platform.

macOS

1. Copy the yaml file to /etc/otelcol-sumo/conf.d/ folder in the macOS instance which needs to be monitored.

2. Restart the otelcol-sumo process using the below command 

    otelcol-sumo --config /etc/otelcol-sumo/sumologic.yaml --config "glob:/etc/otelcol-sumo/conf.d/*.yaml"

Chef

1. Copy the yaml file into your Chef cookbook files directory files/<downloaded_yaml_file>.
2. Use a Chef file resource in a recipe to manage it. cookbook_file '/etc/otelcol-sumo/conf.d/<downloaded_yaml_file>' do mode 0644 notifies :restart, 'service[otelcol-sumo]', :delayed end
3. Add the recipe to your collector setup to start collecting the data. Every team typically has their established way of applying the Chef recipe. The resulting Chef recipe should look something like:

   cookbook_file '/etc/otelcol-sumo/conf.d/<downloaded_yaml_file>' do
       mode 0644
       notifies :restart, 'service[otelcol-sumo]', :delayed
   end

Ansible

1. Place the file into your Ansible playbook files directory.
2. Run the Ansible playbook.

   ansible-playbook -i inventory install_sumologic_otel_collector.yaml
   -e '{"installation_token": "<YOUR_TOKEN>", "collector_tags": {<YOUR_TAGS>}, "src_config_path": "files/conf.d"}'

Puppet

1. Place the file into your Puppet module files directory modules/install_otel_collector/files/<downloaded_yaml>.
2. Use a Puppet file resource to manage it.

   file { '/etc/otelcol-sumo/conf.d/<downloaded_yaml_file>':
       ensure => present,
       source => 'puppet:///modules/install_otel_collector/<downloaded_yaml_file>',
       mode => '0644',
       notify => Service[otelcol-sumo],
     }
3. Apply the Puppet manifest. Every team typically has their established way of applying the Puppet manifest. The resulting Puppet manifest should look something like:

   node 'default' {
       class { 'install_otel_collector'
         installation_token => '<YOUR_TOKEN>',
         collector_tags => { <YOUR_TAGS> },
       }
   
       service { 'otelcol-sumo':
         provider => 'systemd',
         ensure => running,
         enable => true,
         require => Class['install_otel_collector'],
       }
   
       file { '/etc/otelcol-sumo/conf.d/<downloaded_yaml_file>':
         ensure => present,
         source => 'puppet:///modules/install_otel_collector/<downloaded_yaml_file>',
         mode => '0644',
         notify => Service[otelcol-sumo],
       }
     }

After successfully executing the above command, Sumo Logic will start receiving data from your host machine.

Click Next. This will install the app (dashboards and monitors) to your Sumo Logic Org.

Dashboard panels will start to fill automatically. It's important to note that each panel fills with data matching the time range query and received since the panel was created. Results won't immediately be available, but within 20 minutes, you'll see full graphs and maps.

Sample metrics

{
	"queryId":"A",
	"_source":"sumo-mac-dc8d7942-8038-46f0-af33-9a3a06a73f72",
	"state":"LAST_ACK",
	"_sourceName":"sumomacsyslog",
	"host":"sumo-mac",
	"os.type":"darwin",
	"sumo.datasource":"mac",
	"_sourceCategory":"sumo/mac/sys/logs",
	"metric":"system.network.connections",
	"_collectorId":"000000000CAADE8D",
	"_sourceId":"0000000000000000",
	"unit":"{connections}",
	"_sourceHost":"sumo-mac",
	"_collector":"sumo-mac-dc8d7942-8038-46f0-af33-9a3a06a73f72",
	"protocol":"tcp",
	"max":0,
	"min":0,
	"avg":0,
	"sum":0,
	"latest":0,
	"count":14
}

Sample queries

Metrics query from the File System Utilization panel.

sumo.datasource=mac host.name=* device=* metric=system.filesystem.utilization | sum by host.name, device, type, mountpoint

Viewing macOS dashboards

All dashboards have a set of filters that you can apply to the entire dashboard. Use these filters to drill down and examine the data to a granular level.

• You can change the time range for a dashboard or panel by selecting a predefined interval from a drop-down list, choosing a recently used time range, or specifying custom dates and times. Learn more.
• You can use template variables to drill down and examine the data on a granular level. For more information, see Filtering Dashboards with Template Variables.

Host Metrics - Overview

The Host Metrics - Overview dashboard gives you an at-a-glance view of the key metrics like CPU load, memory, network, and TCP connections of all your macOS hosts. Use this dashboard to identify hosts with high CPU load, memory utilization, and identify anomalies over time.

Host Metrics - CPU

The Host Metrics - CPU dashboard provides the metric over time for CPU load. Use this dashboard to identify hosts and processes with high CPU utilization.

Host Metrics - Disk

The Host Metrics - Disk dashboard provides detailed information about file system metrics.

Use this dashboard to view:

• File system utilization over time.
• Devices by file system usage.
• Disk used by host.

Host Metrics - Memory

The Host Metrics - Memory dashboard provides detailed information on host memory usage, memory distribution, and used free and Inactive memory.

Use this dashboard to:

• Identify hosts with high memory utilization.
• Examine memory distribution (free, used) for a given host.
• Total free used and inactive memory.

Host Metrics - Network

The Host Metrics - Network dashboard provides detailed information on host network errors, throughput, and packets sent and received.

Use this dashboard to:

• Determine top hosts with network errors and dropped packets.
• Monitor abnormal spikes in incoming/outgoing packets and bytes sent and received.
• Use dashboard filters to compare throughput across the interface of a host.

Host Metrics - TCP

The Host Metrics - TCP dashboard provides detailed information about inbound, outbound, open, and established TCP connections.

Use this dashboard to:

• Identify abnormal spikes in inbound, outbound, open, or established connections.

Create monitors for macOS app

From your App Catalog:

1. From the Sumo Logic navigation, select App Catalog.
2. In the Search Apps field, search for and then select your app.
3. Make sure the app is installed.
4. Navigate to What's Included tab and scroll down to the Monitors section.
5. Click Create next to the pre-configured monitors. In the create monitors window, adjust the trigger conditions and notifications settings based on your requirements.
6. Scroll down to Monitor Details.
7. Under Location click on New Folder.
   note

   By default, monitor will be saved in the root folder. So to make the maintenance easier, create a new folder in the location of your choice.

8. Enter Folder Name. Folder Description is optional.
   tip

   Using app version in the folder name will be helpful to determine the versioning for future updates.

9. Click Create. Once the folder is created, click on Save.

macOS alerts

Alert Name	Alert Description and conditions	Alert Condition	Recover Condition
Metrics Mac - High FileSystem Utilization Alert	This alert gets triggered when filesystem utilization exceeds threshold.	Count > 80	Count < = 80
Mac - High Memory Utilization Alert	This alert gets triggered when memory utilization exceeds threshold.	Count > 80	Count < = 80