The Service Map for APM is here!

Basic Agent Usage for macOS

Overview

This page outlines the basic features of the Datadog Agent for macOS. If you haven’t installed the Agent yet, instructions can be found in the Datadog Agent Integration documentation.

By default, the Agent is installed in a sandbox located at /opt/datadog-agent. You’re free to move this folder wherever you like; however, his documentation assumes a default installation location.

Commands

In Agent v6, the launchctl service manager provided by the operating system is responsible for the Agent lifecycle, while other commands must be run via the Agent binary directly. Alternatively, lifecycle commands can also be managed via the systray app, and other commands can be executed via the web GUI.

Description Command
Start Agent as a service launchctl start com.datadoghq.agent or systray app
Stop Agent running as a service launchctl stop com.datadoghq.agent or systray app
Restart Agent running as a service run stop then start or systray app
Status of Agent service launchctl list com.datadoghq.agent or systray app
Status page of running Agent datadog-agent status or web GUI
Send flare datadog-agent flare or web GUI
Display command usage datadog-agent --help
Run a check datadog-agent check <check_name>
Description Command
Start Agent as a service datadog-agent start
Stop Agent running as a service datadog-agent stop
Restart Agent running as a service datadog-agent restart
Status of Agent service datadog-agent status
Status page of running Agent datadog-agent info
Send flare datadog-agent flare
Display command usage not implemented
Run a check datadog-agent check <check_name>

Configuration

The configuration files and folders for the Agent are located in:

  • ~/.datadog-agent/datadog.yaml

Configuration files for Integrations:

  • ~/.datadog-agent/conf.d/

The configuration files and folders for the Agent are located in:

  • ~/.datadog-agent/datadog.conf

Configuration files for Integrations:

  • ~/.datadog-agent/conf.d/

Troubleshooting

Run the status command to see the state of the Agent. The Agent logs are located in the /var/log/datadog/ directory and are consolidated in the agent.log file.

If you’re still having trouble, our support team is glad to provide further assistance.

Run the info command to see the state of the Agent. The Agent logs are located in the /var/log/datadog/ directory and are split into:

  • datadog-supervisord.log
  • collector.log
  • dogstatsd.log
  • forwarder.log

If you’re still having trouble, our support team is glad to provide further assistance.

Working with the embedded Agent

The Agent contains an embedded Python environment at /opt/datadog-agent/embedded/. Common binaries such as python and pip are contained within /opt/datadog-agent/embedded/bin/.

See the instructions on how to add packages to the embedded Agent for more information.

Switch between Agent v5 and v6

Upgrade to Agent 6

You can either download the DMG package and install it manually, or use the one-line install script.

Manual installation

  1. Download the DMG package of the latest Agent version, use the latest macOS release listed on the release page of the repository
  2. Install the DMG package
  3. Add your API key to /opt/datadog-agent/etc/datadog.yaml

Then start the Datadog Agent app (once started, you should see it in the system tray), and manage the Agent from there. Agent v6 includes a web-based GUI to edit the Agent configuration files and much more.

Install script

To Upgrade

The Agent v6 installer can automatically convert v5 configurations during the upgrade:

DD_UPGRADE=true bash -c "$(curl -L https://raw.githubusercontent.com/DataDog/datadog-agent/master/cmd/agent/install_mac_os.sh)"

Note: The import process won’t automatically move custom Agent checks. This is by design as we cannot guarantee full backwards compatibility out of the box.

To Install Fresh

This is very similar to the upgrade method above, except instead of specifying the upgrade flag, you must supply your API key. This method will also work on Agent v5 machines, however the existing configuration will not be converted.

DD_API_KEY=YOUR_API_KEY bash -c "$(curl -L https://raw.githubusercontent.com/DataDog/datadog-agent/master/cmd/agent/install_mac_os.sh)"

Downgrade to Agent v5

  1. Stop the Agent with the systray app, if it’s running

  2. Exit the systray app

  3. Uninstall the Datadog Agent application

  4. Install the Agent 5 DMG package using your preferred installation method

Uninstall the Agent

  1. Stop and close the Datadog Agent via the systray.

  2. Drag the Datadog Application from the application folder to the Trash Bin.

  3. Remove the system elements:

    $ sudo rm -rf /opt/datadog-agent
    $ sudo rm -rf /usr/local/bin/datadog-agent
    $ sudo rm -rf ~/.datadog-agent/**​ #to remove broken symlinks
    
  4. If you ran the optional install commands to have the Agent run at boot time, run the following to finish uninstalling:

    sudo launchctl unload -w /Library/LaunchDaemons/com.datadoghq.agent.plist
    sudo rm /Library/LaunchDaemons/com.datadoghq.agent.plist
    

Further Reading