Skip to main content

Auto Instrumentation

The APM agent can automatically scan your servers and virtual machines to find Java applications that are ready to be instrumented. You can turn on monitoring for them with a single click directly from the UI.

Prerequisites​

Before you begin, ensure the following requirements are met:

  • The Motadata Agent must be installed and running on the server where the application is deployed. The otelcol process must also be running as part of the Motadata Agent.

    To check the agent status, open a Linux terminal and run the following command:

    service motadata-agent status
    info

    If the agent is not running, restart it using the following commands:

    service motadata-agent stop
    service motadata-agent start

  • Java version 8 or higher is required. To verify the installed version, run:

    java -version

  • Motadata Agent and application version must be 8.2.5 or higher.

Select Auto Detect as the Instrumentation Method.

Select the Linux or Windows agent for the Host/VM method from the Select Agent list. The Setup Command is displayed — copy it and run it in the CLI of the server where you want to instrument the application.

Once the above steps are applied, the list of discovered applications is displayed.

Click the Configure button in the Action column for the application you want to register.

note

Services with a name starting with unknown_service* cannot be registered. Additionally, if a service with the same name already exists, it cannot be configured again.

Once configured, a registration confirmation is displayed on the screen. Trace collection starts automatically, and the application becomes visible in the APM Explorer.

Troubleshooting: Java Agent JAR Access Issues​

Symptoms​

The application server (such as Tomcat) fails to start with errors similar to:

Error opening zip file or JAR manifest missing
Error occurred during initialization of VM
agent library failed to init

Cause​

The Java agent JAR may exist with correct file permissions, but the application still cannot access it. This happens when one or more parent directories in the path lack execute (traverse) permission.

On Linux, a process needs execute (x) permission on every directory in the path to reach a file. Even if the JAR itself is readable, the application cannot load it if any parent directory blocks traversal.

note

This commonly occurs when the installer creates the instrumentation directory hierarchy with owner-only (700) permissions, and the application runs as a non-root service user.

Verification Steps​

  1. Verify that the JAR file exists:

    ls -la <path-to-agent-jar>

  2. Identify the user running the application. Do not assume it runs as root.

  3. Check the permissions of every directory in the path:

    namei -l <path-to-agent-jar>

  4. Look for parent directories that show drwx------ or otherwise deny execute (x) permission to the application user or group.

Solution​

Grant traverse (execute) permission on each affected parent directory:

chmod o+x /opt/motadata
chmod o+x /opt/motadata/motadata
chmod o+x /opt/motadata/motadata/motadata
chmod o+x /opt/motadata/motadata/motadata/instrumentation

Alternatively, adjust group ownership and permissions according to your organization's security policies.

Restart the application server after updating the permissions. The Java agent should now load without errors.

info

When you see "Error opening zip file or JAR manifest missing", check the permissions of the entire directory path first, not just the JAR file. The namei -l command shows permission issues on every parent directory in one output.

A few changes worth flagging:

  1. Removed the "Example: Issue Encountered in Our Environment" section — internal incident details don't belong in customer-facing docs. The useful learnings from it (the 700 installer permissions, the exact chmod path fix, the namei -l diagnostic) are folded into the Cause note, Solution, and Tip instead.

  2. Converted passive voice — "Traverse permission was added" became "Grant traverse permission," and all steps now start with action verbs.

  3. Kept the concrete /opt/motadata/... paths in the Solution since they match the actual product install path — readers can copy-paste directly.