Usage Tracker Overview

Table of Contents

Usage Tracker is a feature that enables you to track how your Oracle Java SE Advanced and Oracle Java SE Suite 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.

The following topics are covered:

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, and 7 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 <host name>/<literal IP address>

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).

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 usage 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.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:

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:

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.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:

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

Usage Tracker prints these properties as a space-separated list of properties and their values. For example:

com.company.interestingProperty=value1 com.anotherInterestingProperty=value2

com.oracle.usagetracker.separator

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

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.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.

Example Usage Tracker properties File

# 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 UsageTrackerServer.java is a simple application that listens for Usage Tracker data. Follow these steps to run and compile it:

  1. Download and save UsageTrackerServer.java to a file named UsageTrackerServer.java.

  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 will print 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


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