Installing the host agent on Mac OS

The Instana agent is a regular Java process at its core. The packages for all our supported operating systems only differ in a few native libraries shipped with it.

Prerequisites

A Java Development Kit (JDK) needs to be available for the agent. You can see the list of supported JDKs as follows. There are two options:

  1. The easiest is to place or link that JDK into <instana-agent-install-dir>/jvm (so that <instana-agent-install-dir>/jvm/bin/java exists).

  2. The customizable way is to export an environment variable called JAVA_HOME to point to that JDK (this environment variable can be also set via instana-agent-install-dir>/bin/setenv).

At the moment, the following JVMs are supported for running the agent:

It is important that the JVM is executable for any user on the system. You are recommended to use the latest available patch release of the Java distribution of your choice. The agent requires a JDK thats supports TLSv1.3 (available in all current JDK 8 and JDK 11 builds). Note that depending on your OS distribution, the packages provided by the OS distributor might not contain strong encryption support due to export control. If you use such a package, you might meet errors like "java.lang.RuntimeException: Could not generate DH key pair."

Download the agent

To install and run the host agent, complete the following steps:

  1. Sign in to the Instana UI, and then select an option to display the agent catalog; for example, on the home page, click Deploy Agent.

    If you are starting a new trial instance of Instana, the agent catalog is displayed with a prompt to select a host agent to install.

  2. Click the tile macOS - macOS (64bit - Intel & Apple silicon)

  3. Select the packaging option to install a dynamic or static agent.

  4. Click download link, to download the agent archive file.

    The agent archive file is pre-configured with your agent key and host agent endpoint, so you just have to extract and then run the agent.

  5. Extract the agent archive.

    You must use a GNU-tar to extract the archive, because the archive contains paths longer than 100 characters. If you do not use a GNU-tar, then the agent will fail to start and return a "SEVERE: Could not launch framework" error.

Run the agent

  1. Open Terminal, and change the directory to to the path where you extracted the agent. Typically it's ~/Downloads/instana-agent.

    cd ~/Downloads/instana-agent

  2. Make sure that the JAVA_HOME environment variable is set according to the prerequisites section. Then, run the following command to start the agent in the background:

    bin/start

  3. Check if the agent is up and running by running the following command in the terminal:

    bin/status

  4. On the first start of the Instana agent on Apple silicon-based machines, you might see a warning from macOS about an unsigned library that is named libsigar-universal64-macosx.dylib, which is required to run the agent.

    macOS dylib warning

    To allow the usage of this architecture-specific library, you need to approve it from System Preferences -> Security & Privacy -> General.

    macOS dylib approve

    Then, restart the agent by running the following command in the terminal, and approve the library on the upcoming pop-up window once again:

    bin/stop & bin/start

Checking the status of the host agent

After you install the host agent, you can check the status of the host agent in the Instana UI or on the host. For more information, see Checking the status of the host agent.

Limitations

  • Instana provides a best-effort compatibility with MacOS for development and testing purposes. You must run the Instana agent as regular user account, instead of the root account. In addition, Instana will monitor only the processes that are run by the same user. Running the agent in a Docker container is not supported. Finally, monitoring Docker containers is not possible due to significant differences in internals of Docker Machine, Docker for Mac, and the regular Linux Docker.

  • On Apple silicon-based machines, the architecture-specific library is not yet signed. Follow step 4 in the run instructions in this topic to approve the libsigar-universal64-macosx.dylib library. For more information, see the official Apple documentation.

Troubleshooting agent deployment

If installing the agent is not successful at first, you can check log messages and troubleshooting tips. If this troubleshooting section does not answer the questions you have, contact the IBM Instana support team with information about your experience, so that we can help you and update our documentation accordingly.

For troubleshooting information that is general to all host agents, see Managing host agents / Troubleshooting.