Amazon EC2 System Monitor for macOS is a small agent that runs on every mac1.metal instance to provide on-instance metrics in CloudWatch. Currently the primary use case for this agent is to send CPU utilization metrics. This uses a serial connection attached via the AWS Nitro System and is forwarded to CloudWatch for the instance automatically.
The agent is installed and enabled by default for all AMIs vended by AWS. It logs to
/var/log/amazon/ec2/system-monitoring.log and can be updated via Homebrew.
The package includes a shell script for enabling, disabling, and listing the current status of the agent
according to launchd.
To view the status of the agent:
sudo setup-ec2monitoring listTo enable/install ec2-macos-system-monitor:
sudo setup-ec2monitoring enableThis must be run if updating to a new version to ensure it is scheduled to run again.
To disable ec2-macos-system-monitor:
sudo setup-ec2monitoring disableThe Amazon EC2 System Monitor for macOS uses multiple goroutines to manage two primary mechanisms:
- The serial relay takes data from a UNIX domain socket and writes the data in a payload via a basic wire protocol.
- Runs a ticker that reads CPU utilization and sends the CPU usage percentage to the UNIX domain socket.
This design allows for multiple different processes to write to the serial device while allowing one process to always have the device open for writing.
The wire protocol's primary purpose is to ensure the payload is complete by wrapping the payload in a checksum. There is a tag which is used as a namespace to ensure the reader knows what type of data is being written. The data itself which, in this case is typically the CPU utilization as a percentage of total usage the second field. Finally, a boolean is set specifying if the data should be compressed before sending. A checksum is then computed on this payload and included along with the payload. This payload with checksum allows the receiver to ensure that all the data was correctly received as well as inform if the data should be decompressed before parsing.
See CONTRIBUTING for more information.
This project is licensed under the Apache License, version 2.0.