FaqProfilerProfileFreeForm

How do I profile a free-form project?

If you have a free-form project, you have to write your own Ant target to be able to profile the project. In the build script of your free-form project you should write the following two targets:

  • a target for profiling the project
  • a target for profiling individual files

If your free-form project is set as the main project, the first time you invoke "Profile Main Project" or "Profile File" you are asked to specify which of the existing Ant targets to use.

The targets would typically look similar to your existing "run" target, with some additional parameters. One way to create your Ant targets is to copy your "run" target, then rename the copy "profile" and modify it according to the following instructions.

If you copy the run target to make your new profile target, you need to make two changes to the profile target:

  1. Add a call to nbprofiledirect task at the beginning (see nbprofiledirect below)
  2. Add an extra JVM argument to the task that starts the VM to run your application. You typically do this by adding a sub-element similar to the following to the java task:
      
<jvmarg value="${profiler.info.jvmargs.agent}"/>


Target Examples

The following are examples of basic targets for "profile" and "profile-single" (JDK 5.0 or later)

<target name="profile" depends="jar" description="Profile Project">
  <fail unless="netbeans.home">This target can only run inside the NetBeans IDE.</fail>
                    
  <nbprofiledirect>
     <classpath> <pathelement location="... specify ..."/> </classpath>
  </nbprofiledirect>
                    
  <java ... use same attributes as with run ...>
     <jvmarg value="${profiler.info.jvmargs.agent}"/>
  </java>
</target>

To start the profiler with a class selected in the explorer, you can add the same target, and use classname="${profile.class}", for example:

<target name="profile-single" depends="jar" description="Profile File">
  <fail unless="netbeans.home">This target can only run inside the NetBeans IDE.</fail>
                    
  <nbprofiledirect>
     <classpath> <pathelement location="... specify ..."/> </classpath>
  </nbprofiledirect>
                    
  <java classname="${profile.class}" ... use same attributes as with run ...>
     <jvmarg value="${profiler.info.jvmargs.agent}"/>
  </java>
</target>

Additional parameters

The following are some additional parameters you can use. The use of some of the parameters is optional, but they enhance your ability to control the profiler setup from the UI.

  • Add jvm="${profiler.info.jvm}" attribute to start profiling with the JDK selected from the UI (Tools | Options | Profiler) for profiling
  • Add dir="${profiler.info.dir}" attribute to be able to start the profiled application with the working directory specified in the profiler UI
  • Add <jvmarg line="${profiler.session.jvm.args}"/> allows you to specify custom JVM arguments and working directory in a profiler configuration. This can be particularly useful if you are tuning the VM with extra arguments and want to observe the differences in the profiler.

Here is an example of a full profile target that allows you to control the working directory, JVM and JVM arguments from the IDE:

  <target name="profile" depends="jar" description="Profile Project">
    <fail unless="netbeans.home">This target can only run inside the NetBeans IDE.</fail>

    <nbprofiledirect>
        <classpath> <pathelement location=" ... specify ... "/> </classpath>
    </nbprofiledirect>

    <java fork="true" classname="... specify ..." dir="${profiler.session.working.dir}" jvm="${profiler.info.jvm}">
        <jvmarg value="${profiler.info.jvmargs.agent}"/>
        <jvmarg line="${profiler.info.jvmargs}"/>
        <classpath> <pathelement location="... specify ..."/> </classpath>
    </java>
  </target>
 

Profiling Properties

The following table displays the properties that are set if the profiling is invoked from the Profile Project or Profile File actions.

profile.class If using Profile File, this property contains the name of the class to profile (Java style)
profiler.info.single.file If using Profile File, this property contains the file name of the class to profile
profiler.info.jvm Path to Java executable of JVM selected for profiling
profiler.info.jvmargs JVM arguments selected in IDE - selected in Project customizer or overridden in Custom profiling configuration
profiler.info.jvmargs.agent JVM argument to be used for starting the profiler agent in the VM
profiler.info.agentpath Path to the profiler agent
profiler.info.project.dir Project directory of project that is being profiled
profiler.info.dir Working directory of the profiler application



nbprofiledirect

nbprofiledirect launches the profiler when run within the NetBeans IDE. The profiler will start listening on a specific port to try to connect to an agent running in the profiled VM.

The task returns immediately and is not blocking. You typically should call this task before starting the VM with the profiler agent.

This task is typically not started by hand, but rather from the Profiler UI actions Profile Project or Profile File, however in some special circumstances in can be also called manually (but still within the context of NetBeans IDE).

If the task is called with insufficient context or the interactive attribute is specified, it will first display a dialog that will allow the user to select the type of profiling.

Parameters

Attribute Description Required
mainclass the Java class to execute. Either jar or classname
jvmargsproperty can be used to specify in which property the JVM argument for starting profiler agent should be stored. Default value is profiler.info.jvmargs.agent. Upon successful completion of the nbprofiledirect No
jvmargsprefix can be used to instruct the profiler to use certain prefix when creating the profiler agent JVM argument. This is useful for example for NetBeans IDE profiling, where arguments that should be passed to the VM are prefixed with -J No
jvmproperty can be used to specify in which property the JVM to use for profiling should be stored. Default value is profiler.info.jvm. Upon successful completion of the nbprofiledirect No
interactive auto, true or false. Controls whether the Select Profiling Task is displayed when this task is called. The default value is auto, which means that the nbprofiledirect should only display the dialog when it is called with insufficient properties context. Under normal circumstances, when the task is correctly called as a results of Profile Project or Profile File action, the dialog would not be displayed. No


Parameters specified as nested elements

classpath

Java's classpath attribute is a PATH like structure and can also be set via a nested classpath element.

rootspath

A PATH like structure that allows to specify which packages the profiler shoudl treat as belonging to the project. If this is used, CPU profiling would only profile code invoked from methods in those packages. This is especially useful in case of applciation servers, where specifying which packages are the user code that should only be profiler, can lead to much smaller profiling overhead.

Errors and return codes None

Examples A typical way to use nbprofiledirect in a free-form project:

        <nbprofiledirect>
          <classpath>
            <pathelement location="dist/test.jar"/>
            <pathelement path="${java.class.path}"/>
          </classpath>
        </nbprofiledirect>

        <java classname="org.mytest.Main" jvm="${profiler.info.jvm}">
          <classpath>
            <pathelement location="dist/test.jar"/>
            <pathelement path="${java.class.path}"/>
          </classpath>
          <jvmarg value="${profiler.info.jvmargs.agent}"/>
        </java>

Using the nbprofiledirect in the interactive mode.

        <nbprofiledirect interactive="true" jvmargsproperty="my.agent.property">
          <classpath>
            <pathelement location="dist/test.jar"/>
            <pathelement path="${java.class.path}"/>
          </classpath>
        </nbprofiledirect>
        <java classname="org.mytest.Main" jvm="${profiler.info.jvm}">
         <classpath>
           <pathelement location="dist/test.jar"/>
           <pathelement path="${java.class.path}"/>
         </classpath>
         <jvmarg value="${my.agent.property}"/>
        </java>

Applies to: NetBeans IDE 6.8, 6.9, 7.0, 7.1

Platform: all

Not logged in. Log in, Register

By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo