How to suppress 'Unused declaration' warnings for methods called by JVM agents

Background/Situation

The Unused declaration inspection flags methods, classes, and fields that have no apparent caller in the project source code. Methods invoked through bytecode instrumentation by a JVM agent (the premain entry point declared in the agent's MANIFEST.MF, or the agentmain method used for runtime attachment) appear unused to static analysis even though they are called at runtime.

IntelliJ IDEA does not provide a built-in @CalledByAgent annotation. To silence the warning, declare a project-specific annotation (or define a class or method name pattern) and register it as an inspection entry point.

Question

How can methods called by a JVM agent (premain, agentmain, or methods invoked via instrumented bytecode) be marked as used so that the Unused declaration inspection does not report them?

Answer

Option 1: Register a custom annotation as an entry point

Use this when multiple methods need the exemption, or when the configuration should be shared with the team through version control.

1. Declare a custom annotation in the project:

   @Target({ElementType.METHOD, ElementType.TYPE})
   @Retention(RetentionPolicy.CLASS)
   public @interface CalledByAgent {
   }
   

2. Apply the annotation to every method or class invoked by the JVM agent:

   @CalledByAgent
   public static void premain(String agentArgs, Instrumentation inst) {
       // ...
   }
   

3. Open Settings | Editor | Inspections.

4. In the inspection tree on the left, expand Java | Declaration redundancy and select Unused declaration.

5. In the right-hand panel, open the Entry points tab and click Annotations….

6. Add the fully qualified name of the custom annotation (for example, com.example.agent.CalledByAgent) and click OK.

Annotations registered through this dialog are stored in the project-level inspection profile (.idea/inspectionProfiles/*.xml), so committing the profile applies the configuration for everyone working on the project.

Option 2: Register a class or method name pattern

Use this when the agent entry points have predictable names (such as premain) and the source code cannot or should not be annotated. Available since IntelliJ IDEA 2016.3.

1. Open Settings | Editor | Inspections | Java | Declaration redundancy | Unused declaration.
2. In the right-hand panel, open the Entry points tab.
3. Add a class name pattern or method name pattern that matches the agent entry points. A method name pattern of premain matches the standard JVM agent entry point in any class.

Option 3: Mark a specific method via the intention action

Use this for individual methods when changing the source or the inspection profile is not appropriate.

1. Place the caret on the highlighted method name.
2. Press Alt+Enter to open the intention actions menu.
3. Choose the option that adds the method to the entry point list, or the option that adds @SuppressWarnings("unused") to the method.

Entries added through the intention action are stored per-method in .idea/misc.xml rather than the inspection profile, so they are not propagated when the profile is shared.

Reference

IDEA-376374: Feature request for a built-in @CalledByAgent annotation