MacOS integration for Grafana Cloud

The macOS integration for Grafana Cloud uses the Grafana agent to collect metrics related to the macOS operating system, including aspects like CPU usage, load average, memory usage, and disk and networking I/O. It also enables you to scrape system logs with the agent using promtail. This integration includes useful alerts and a prebuilt dashboard to help you monitor and visualize these metrics and logs.

Before you begin

This integration enables Grafana Agent to send macOS metrics and logs to Grafana Cloud.

Install macOS integration for Grafana Cloud

1. In your Grafana instance, click Integrations and Connections (lightning bolt icon), then click on the macOS tile to install the integration.

2. Once the integration is installed, follow the steps on the Configuration Details page to configure the Grafana agent to automatically scrape and send macOS metrics and logs to your Grafana cloud instance.

Post-install configuration for the macOS integration

This integration supports metrics and logs from macOS. In order to see logs and metrics signals correlated on the same dashboard, you need to make sure that job and instance labels match in the node_exporter integration config and under logs. The job label should be set to integrations/macos-node. The following preferred agent configuration example includes logs collected.

Note: You must replace placeholder <this_mac_hostname> with the appropriate hostname for your configuration needs:

integrations:
  prometheus_remote_write:
    - url: http://cortex:9009/api/prom/push
  node_exporter:
    enabled: true
    relabel_configs:
    - replacement: <this_mac_hostname>
      source_labels: [agent_hostname]
      target_label: instance
    - replacement: "integrations/macos-node"
      source_labels: [agent_hostname]
      target_label: job

logs:
  configs:
  - name: integrations
    clients:
    - url: http://loki:3100/loki/api/v1/push
    positions:
      filename: /tmp/positions.yaml
    target_config:
      sync_period: 10s
    scrape_configs:
    - job_name: integrations/node_exporter_direct_scrape
      static_configs:
      - targets:
        - localhost
        labels:
          instance: <this_mac_hostname>
          __path__: /var/log/*.log
          job: integrations/macos-node
      pipeline_stages:
      - multiline:
          firstline: '^([\w]{3} )?[\w]{3} +[\d]+ [\d]+:[\d]+:[\d]+|[\w]{4}-[\w]{2}-[\w]{2} [\w]{2}:[\w]{2}:[\w]{2}(?:[+-][\w]{2})?'
      - regex:
          expression: '(?P<timestamp>([\w]{3} )?[\w]{3} +[\d]+ [\d]+:[\d]+:[\d]+|[\w]{4}-[\w]{2}-[\w]{2} [\w]{2}:[\w]{2}:[\w]{2}(?:[+-][\w]{2})?) (?P<hostname>\S+) (?P<sender>.+?)\[(?P<pid>\d+)\]:? (?P<message>(?s:.*))$'
      - labels:
          sender:
          hostname:
          pid:
      - match:
          selector: '{sender!="", pid!=""}'
          stages:
            - template:
                source: message
                template: '{{.sender }}[{{.pid}}]: {{ .message }}'
            - labeldrop:
                - pid
            - output:
                source: message

Note that on Macs with an M1 architecture you might encounter errors similar to the following:

level=error integration=node_exporter msg="collector failed" name=thermal duration_seconds=0.001089125 err="no CPU power status has been recorded"

To avoid collector errors, you can add disable_collectors setting to the node_exporter integration to disable it:

    disable_collectors:
      - thermal # disable on M1

Dashboards

After you have successfully configured the macOS integration, the prebuilt dashboard will be installed in your Grafana Cloud instance to help you monitor your macOS metrics and logs.

macOS overview dashboard

This dashboard gives a general overview of all relevant metrics from your Mac, such as CPU usage, memory usage, and disk usage.

The dashboard also contains logs collected by Grafana Agent from macOS.

Alerts

Grafana Cloud alerts are directly tied to metrics and log data. This integration includes the following useful alerts:

Metrics captured by macOS integration for Grafana Cloud

For a complete list of all metrics provided by macOS integration, refer macOS Prometheus metrics.

The most important metrics provided are as follows:

• CPU usage
• Load average 1m,5m,15m
• Number of logical cores
• Physical memory present
• Memory used
• App memory
• Wired memory
• Compressed memory
• Disks I/O
• Disk space usage per mountpoint
• Network bytes received/transmitted

Cost

By connecting your macOS integration to Grafana Cloud you might incur charges. For more information, see the following topics:

• For an increase in the number of active series that your Grafana Cloud account uses for metrics included in each Cloud tier, see Active series and dpm usage and Cloud tier pricing.