Java Platform, Standard Edition

Usage Tracker Overview

Release 1

E50948-01

August 2014

This page describes the Usage Tracker, which tracks how Oracle Java SE Advanced and Oracle Java SE Suite Java Runtime Environments (JREs) are being used in your systems. The output of the Usage Tracker is a plain text, comma-separated record that contains the JRE version, the application being run, and other details. This record is appended to a file or sent over the network in a User Datagram Protocol (UDP) packet.

This page has these topics:

System Requirements

Usage Tracker is available in Oracle Java SE Advanced and Oracle Java SE Suite versions 1.4.2_35 and later, 5.0u33 and later, 6u25 and later, 7 and later, and 8 and later.

Output of Usage Tracker

The following is an example of output from Usage Tracker; it is a record of one invocation of a Java application. Line breaks were added for clarity; each record appears as one line of text:

"VM start",
"Fri Oct 22 14:13:03 BST 2010",
"examplehost/192.0.2.0",
"AppName",
"/path/to/jre",
"1.7.0",
"19.0-b09",
"Oracle Corporation",
"Oracle Corporation",
"Linux",
"i386",
"2.6.29.x86_64",
"-Xmx128m",
"/opt/programs",
"user.home=/home/username foo.bar=null"

The following table describes each value of this comma-separated line:

Example Description

VM start

Type of start; it has one of the following values:

  • VM start: JVM start-up (either Java application or JNI invocation)

  • plugin or plugin2: Applets

  • javaws application or javaws applet: Java Web Start

Fri Oct 22 14:13:03 BST 2010

Date and time

examplehost/192.0.2.1

Host name and IP address in the form <hostname>/<literalIPaddress>

AppName

Java command (name of main class or jar file) and list of arguments, if any (space-separated list)

Java Web Start applications have the following form:

<URL>: <main class> <arguments>

Applet invocations have the following form:

<URL>: <parameters>

/path/to/jre

Directory that contains the JRE (java.home system property value)

1.7.0

Java version (java.version system property value)

19.0-b09

JVM version (java.vm.version system property value)

Oracle Corporation

Java vendor (java.vendor system property value)

Oracle Corporation

JVM vendor (java.vm.vendor system property value)

Linux

Operating system name (os.name system property value)

i386

Operating system architecture (os.arch system property value)

2.6.29.x86_64

Operating system version (os.version system property value)

-Xmx128m

JVM arguments (space-separated list); empty if there are no JVM arguments; n/a if this information is not available (for example, in Java SE 1.4.2, this information is not available)

/opt/programs

Class path (java.class.path system property value)

user.home=/home/username foo.bar=null

Name=value pairs of any additional system properties specified in the Usage Tracker properties file. Multiple pairs are space-separated; empty if no additional property names are specified (default).


Note:

In the fields that are space-separated lists, a different quote character (by default, the single quotation mark, ') is used to quote an item that contains a space. Any existing quote characters are printed twice.

For example, consider the following command:

/jdk1.8.0_20/bin/java
  -Dfoo1="a b"
  -Dfoo=\"
  -jar c:\\Program\ Files\\Java/jdk1.6.0_25/demo/jfc/Java2D/Java2Demo.jar

Usage Tracker prints these system properties as follows (line breaks were added for clarity):

"'-Dfoo1=a b' -Dfoo="" ",
"-jar c:\Program Files\Java/jdk1.6.0_25/demo/jfc/Java2D/Java2Demo.jar",
""

For versions Oracle Java SE Advanced and Oracle Java SE Suite prior to 8u20, Java Usage Tracker does not surround fields with quotation marks.

Configuring Usage Tracker

Usage Tracker is disabled by default. Enable it by creating the properties file <JRE directory>/lib/management/usagetracker.properties. If this file exists, all usages of the JRE contained in <JRE directory> are tracked.

Note that the path name is different, depending on whether you are configuring Usage Tracker for a JDK or for a JRE.

For additional flexibility, if you want to use a different properties file, you can specify it with the system property -Dcom.oracle.usagetracker.config.file on the command line. In this case, the properties file <JRE directory>/lib/management/usagetracker.properties is not used. In the following example, Usage Tracker uses the properties file /path/usagetracker.properties:

java -Dcom.oracle.usagetracker.config.file=/path/usagetracker.properties MyApplication

Note:

To activate Usage Tracker, the usagetracker.properties file that you create must have a valid value for at least one of the following properties: oracle.usagetracker.logToFile, oracle.usagetracker.logToUDP.

Usage Tracker Properties

The following table describes the properties you can specify in the Usage Tracker properties file.

These properties are set only in the Usage Tracker properties file; they are not set at the command line. This is intended so that Usage Tracker has no impact on or interaction with the JRE user or existing applications.

Note:

The backslash (\) is an escape character in a properties file. Consequently, when specifying file paths that include directories or drive letters, use a forward slash (/) or an escaped backslash (\\) as a directory separator.

Property Description

com.oracle.usagetracker.additionalProperties

Use this property to record values of additional Java properties and their values.

The value of this property is a comma-separated list of properties and their values. For example (ignore line break):

com.oracle.usagetracker.additionalProperties = com.company.interestingProperty,com.anotherInterestingProperty

com.oracle.usagetracker.innerQuote

The character or string used to quote items that contain a space in the JVM argument field list and the additional properties field. The default value is the single quotation mark (').

This property is available in Oracle Java SE Advanced and Oracle Java SE Suite versions 8u20 and later.

com.oracle.usagetracker.logFileMax

The log file size limit, in bytes. If the file size equals or exceeds the given value when logging is attempted, that attempt will be canceled.

If this property is not set, then there is no log file limit.

com.oracle.usagetracker.logToFile

If this property is specified, the fully qualified path name of the file to which Usage Tracker writes records.

You can specify ${user.home} in the path name. The property will expand to the user's home directory. For example (ignore line break):

com.oracle.usagetracker.logToFile = ${user.home}/.java_usagetracker

com.oracle.usagetracker.logToUDP

If this property is specified, Usage Tracker logs to the specified remote host in a UDP packet. For example (ignore line break):

com.oracle.usagetracker.logToUDP = loggingmachine.domainname:32139

Specifying an IP address may be faster in some cases; although, this resolution does not delay the startup of the JVM or the application.

See "Sample: Receiver for UDP Packets"for an example application that can receive UDP packets.

com.oracle.usagetracker.quote

The character or string used to quote fields. The default value is the double quotation mark (").

This property is available in Oracle Java SE Advanced and Oracle Java SE Suite versions 8u20 and later.

com.oracle.usagetracker.separator

The character or string that separates entries in the log file. The default is the comma (,).

com.oracle.usagetracker.verbose

If this property is set to true, error information may be reported to the standard error stream; this is only recommended for diagnostic purposes.


Example Usage Tracker properties File

To create a Usage Tracker properties file, you can use the following example as a template. Lines that begin with the pound sign (#) are comments.

# UsageTracker template properties file.
# Copy to JRE/lib/management/usagetracker.properties and edit,
# uncommenting required settings, to enable.
 
# Settings for logging to a UDP socket:
# com.oracle.usagetracker.logToUDP = hostname.domain:32139
 
# Settings for logging to a file:
# Use forward slashes (/) because backslash is an escape character in a
# properties file.
# com.oracle.usagetracker.logToFile = ${user.home}/.java_usagetracker
 
# (Optional) Specify a file size limit in bytes:
# com.oracle.usagetracker.logFileMaxSize = 10000000
 
# If the record should include additional Java properties,
# this can be a comma-separated list:
# com.oracle.usagetracker.additionalProperties = 
 
# Additional options:
# com.oracle.usagetracker.verbose = true
# com.oracle.usagetracker.separator = ,

Sample: Receiver for UDP Packets

The sample http://docs.oracle.com/javase/products/samplecode/UsageTrackerServer.java is a simple application that listens for Usage Tracker data. Follow these steps to compile and run it:

  1. Create a directory, change to it, and download the UsageTrackerServer.java file into the directory.

  2. Compile the sample with the following command:

    javac UsageTrackerServer.java
    
  3. Run the sample; the following is an example:

    java UsageTrackerServer -v -o usagetracker.out :32139
    
    • The -v option is verbose; if you specify this option, the sample displays additional information.

    • The -o option enables you to specify the name of a log file; if you do not specify this option, the sample prints messages to standard output.

    • In this example, the UDP receiver listens on the localhost address on port 32139. When a JRE (with an enabled and configured Usage Tracker) sends data, the receiver will send the data to the file usagetracker.out. The port number is arbitrary but must be available and must match the one configured in the JRE. If multiple interfaces exist, it may be necessary to specify the port using the form hostname:port or ipaddress:port.

Errors and Exceptions

If Usage Tracker encounters an error or exception during the logging of a record, it does not interrupt the application currently running.

Usage Tracker does not report errors unless the property oracle.usagetracker.verbose is specified in the properties file.

Disk Space

When Usage Tracker incrementally adds records to the log file, it does not check for available disk space or perform administrative tasks such as truncating, deleting, or compressing the log file in order to be minimally intrusive. Although the size of the records is small, it is recommended that you periodically truncate, compress, archive, or delete the log file.

However, you can specify the maximum size of the log file, in bytes, with the oracle.usagetracker.logFileMax property in the properties file.

Limitations

Usage Tracker cannot log Java command line options that are processed by the Java launcher before the JVM is started. For example, Usage Tracker does not record the command line options -client and -server that select the Java HotSpot client and server VM, respectively.

Usage Tracker may not log an application if it terminates immediately because it will not stop a process from exiting.

Frequently Asked Questions

Here are answers to some frequently asked questions:

  • Does Usage Tracker affect the private JRE within a JDK, or does it only affect the standalone JRE?

    If you have a JDK installed in a computer, there is a JRE in the jre subdirectory; this is the private JRE referred to in the question. Yes, Usage Tracker logs the usage of both the private JRE and the standalone JRE, but note that they are configured separately through their own individual lib/management/usagetracker.properties files.

  • Can Usage Tracker log the usage of JDK tools?

    If Usage Tracker is enabled, it logs the usage of tools that come with the JDK such as jmap and jstack.

  • Does Usage Tracker log the usage of JVMs created by native Java applications?

    Yes. When a native application creates a JVM with the Java Native Interface (JNI), Usage Tracker logs this invocation with a blank Java command.

  • Will an invocation similar to java -jar file.jar be tracked by Usage Tracker?

    Yes.

  • Does Oracle capture any of the data logged by Usage Tracker?

    No. As the administrator of the JRE installation, usage data obtained from Usage Tracker is stored in the file of your choice or sent to the UDP host and port that you specify. There is no facility for this data to leave your own network. (Theoretically, if your firewall permits it, the port your UDP host listens on could be configured as remote, but this is not expected or recommended usage.)

  • What does the log record look like for Java Plug-in invocations and applets?

    The Java Plug-in creates a JVM within which multiple applets can execute. Therefore, there could be a log record for the new JVM (line breaks were added for clarity):

    "VM start,Sun Oct 24 21:42:30 BST 2010",
    "examplehost/192.0.2.1",
    "oracle.plugin2.main.client.PluginMain write_pipe_name=jpi2_pid4296_pipe2",
    "read_pipe_name=jpi2_pid4296_pipe1",
    "C:\Program Files\Java\jre",
    "1.7.0",
    "19.0-b09",
    "Oracle Corporation",
    "Oracle Corporation",
    "Windows XP",
    "x86",
    "5.1",
    "-D__jvm_launched=4176676344166
      -Xbootclasspath/a:C:\PROGRA~1\Java\jre6\lib\deploy.jar;
        C:\PROGRA~1\Java\jre\lib\javaws.jar;
        C:\PROGRA~1\Java\jre\lib\plugin.jar
      -Dsun.awt.warmup=true",
    "C:\PROGRA~1\Java\jre\classes",
    

    An additional record is created for each applet started:

    "plugin2",
    "Sun Oct 24 21:42:31 BST 2010",
    "examplehost/192.0.2.1",
    "http://example.com/myapplications/Bounce/Bounce.html:
      height=243 width=243 code=Bounce.class",
    "C:\Program Files\Java\jre",
    "1.7.0",
    "19.0-b09",
    "Oracle Corporation",
    "Oracle Corporation",
    "Windows XP",
    "x86,5.1",
    "-D__jvm_launched=4176676344166
      -Xbootclasspath/a:C:\PROGRA~1\Java\jre6\lib\deploy.jar;
        C:\PROGRA~1\Java\jre\lib\javaws.jar;
        C:\PROGRA~1\Java\jre\lib\plugin.jar
      -Dsun.awt.warmup=true",
    "C:\PROGRA~1\Java\jre\classes",
    
  • How can I remove the quoting behavior of Oracle Java SE Advanced and Oracle Java SE Suite versions 8u20 and later for records with the previous formatting?

    In the Usage Tracker properties file, set blank quote characters with the following two lines:

    com.oracle.usagetracker.quote=
    com.oracle.usagetracker.innerQuote=
    

Documentation Accessibility

For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.

Access to Oracle Support

Oracle customers have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired.


Java Platform, Standard Edition Usage Tracker Overview, Release 1

E50948-01

Copyright © 1993, 2014, Oracle and/or its affiliates. All rights reserved.

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government.

This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate failsafe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.

This software or hardware and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.