Troubleshooting - Monitoring macOS

Check Collectord on a Mac: collectord verify, its log, the LaunchDaemon, a diagnostic bundle for support, and the common problems.

Find out why a Mac’s data isn’t reaching Splunk, and collect what support needs when you open a case. Start with collectord verify, then look for your symptom below.

Verify configuration

When data isn’t showing up in Splunk, the first thing to run is collectord verify. It prints OK or the exact error for each of its checks:

the configuration and the license;
a test record it posts to every events and metrics index the configuration sends to;
what Collectord reads on the Mac.

On a Mac it needs no flags. It reads the configuration in /opt/collectorformacos/etc, as the LaunchDaemon does, and the configuration profile’s settings on top.

bash

1sudo /opt/collectorformacos/bin/collectord verify

Besides the checks every Collectord runs (conf, the database, the license, the Splunk output), its macOS section reports:

Check	What it means
`host`	the Mac’s facts: model, chip, macOS version
`host stats`	a reading of the host record; FAILED when Mach and sysctl return no CPU or memory
`log tool`	`/usr/bin/log`, which the unified log input drives; FAILED means the log packs read nothing
`sudo logging`	whether sudo logs the commands it runs; macOS 15 and later ship `Defaults !log_allowed`, which logs only its refusals
`hardware`	what the hardware sampler finds: CPU clusters, power and thermal sensors, the GPU, disks and interfaces
`managed preferences`	the configuration profile: each key it set and what it set (never the value), `none` without a profile, FAILED for a profile it cannot read or a key of the wrong type

Any line that’s not OK points at the problem:

a wrong HEC URL;
a missing token;
a token that may not write the metrics index;
an expired license;
blocked outbound traffic to the licensing endpoint.

Fix it, rerun verify, and restart Collectord.

verify counts its FAILED lines and still exits 0, so read its output rather than its exit status.

Logs and the LaunchDaemon

Collectord writes its log to /Library/Logs/collectorformacos/collectord.log, which newsyslog rotates at 10 MB, keeping 5 compressed copies. Collectord forwards it to Splunk too, as sourcetype=macos_collectord, so the Collectord usage page and the “Collectord logged warnings or errors” template see its warnings:

bash

1tail -f /Library/Logs/collectorformacos/collectord.log

The LaunchDaemon’s label is com.outcoldsolutions.collectord. Ask launchd whether it runs, with its pid and last exit status:

bash

1sudo launchctl print system/com.outcoldsolutions.collectord

Restart it after a configuration change:

bash

1sudo launchctl kickstart -k system/com.outcoldsolutions.collectord

If launchctl print finds no such service, or the package said the service is disabled, someone switched it off in System Settings › General › Login Items, or with launchctl disable. Turn it back on and load it:

bash

1sudo launchctl enable system/com.outcoldsolutions.collectord
2sudo launchctl bootstrap system /Library/LaunchDaemons/com.outcoldsolutions.collectord.plist

To keep users from switching it off, deploy the Managed Login Items profile.

Common problems

No stats, but the logs arrive. The stats go to the metrics index only. Check that the index exists as a metrics index, that the HEC token may write it, and that defaultMetricsIndex (or the MetricsIndex managed preference) names it. The Stats that reached an events index tile on Setup › Configuration counts the stats that went to an events index instead and were lost. See Metrics index.
Nothing arrives from a Mac. Collectord cannot start without an accepted license and a HEC URL and token: its log says which is missing, and launchd tries again every 10 seconds.
Log messages read <private>. macOS hides the values a program logs without marking them public; only a configuration profile can lift that. See Log forwarding.
No sudo commands on the Security page, only refusals. macOS 15 and later turn sudo’s log_allowed off. verify names the setting; see Log forwarding.
No SSH logins on the Security page. OpenSSH writes them at the info level, which the security pack reads. Check that the pack is on, and that a LogPacks managed preference names it.
Collectord warns that the log store holds nothing. Every noise sampler window reads the log store back. When it reads nothing back, the log store is one macOS cannot read, and every catch-up after a restart or a wake comes back empty too. The warning names the time-index files under /var/db/diagnostics/timesync that an OS install can leave out of order.

Collect diagnostic information

When you open a support case, attach a diagnostic bundle so we can reproduce the issue without a back-and-forth. The bundle includes Collectord’s internal metrics, its goroutines and process information, and its configuration with the HEC token and other secrets stripped out.

Run all four steps below.

1. Collect internal diag information

collectord diag asks launchd for the running Collectord, signals it to write the bundle, and waits for it, up to a few minutes:

bash

1sudo /opt/collectorformacos/bin/collectord diag --stream > diag.tar.gz

Add --include-performance-profiles if support asks for performance profiles.

2. Collect logs

bash

1cp /Library/Logs/collectorformacos/collectord.log collectorformacos.log

3. Run verify

bash

1sudo /opt/collectorformacos/bin/collectord verify > verify.log

4. Prepare tar archive

bash

1tar -czvf collectorformacos-$(date +%s).tar.gz verify.log collectorformacos.log diag.tar.gz