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.
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:
The easiest is to place or link that JDK into
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
At the moment, the following JVMs are supported for running the agent:
- IBM OpenJ9 JDK 11 (Preferred on x64)
- Azul Zulu JDK 8 (Preferred on Apple silicon)
- OpenJDK JDK 8
- Oracle Hotspot JDK 8
- Amazon Corretto JDK 8
- IBM J9 8
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
Sign in to Instana, click More > Agents > Instana agent installation -> Mac OS.
For Mac OS (64bit - Intel and Apple silicon), click Download.
Your agent key and location are pre-populated, so you just have to extract and start the agent.
Extract the agent archive.
Note: You must use a GNU-tar to extract the archive, since it contains paths longer than 100 characters. Failure to do so will prevent the agent to start with a "SEVERE: Could not launch framework" error.
Run the agent
Open Terminal, and change the directory to to the path where you extracted the agent. Typically it's
Make sure that the
JAVA_HOMEenvironment variable is set according to the prerequisites section. Then, run the following command to start the agent in the background:
Check if the agent is up and running by running the following command in the terminal:
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.
To allow the usage of this architecture-specific library, you need to approve it from System Preferences -> Security & Privacy -> General.
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
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
rootaccount. 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.dyliblibrary. For more information, see the official Apple documentation.