Java API Reference
2018 Update Rollup 2

Java API ReferencePermanent link for this heading

The Fabasoft app.telemetry Java API allows you to instrument any Java application with instrumentation points to see what's going on in complex applications.

In order to use the Software-Telemetry Java API effectively you should use the Eclipse IDE for development and set up an Eclipse Java project as described in the following chapter.

Configure Eclipse for Java ProjectPermanent link for this heading

For your new Eclipse Java project you have to include the following Fabasoft app.telemetry SDK resources:

  • The Software-Telemetry library “softwaretelemetry.jar” as referenced library. This Java library is a wrapper for the native binary library “softwaretelemetry-java64.dll” delivered with the Fabasoft app.telemetry agent.
  • The Javadoc for this library “softwaretelemetry-javadoc.jar”. This file should be set as Javadoc-location for the softwaretelemetry.jar library.

On the same server as your Java project is located, you have to have the Fabasoft app.telemetry agent installed, which includes the binary library “softwaretelemetry-java64.dll” and handles the native telemetry data processing.

A correct configured Eclipse project provides ContentAssist and Javadoc help for efficient development of an instrumented software solution.

The Java Software-Telemetry SDK is packaged all together into the Java package: com.apptelemetry.apm where the basic classes and the constants are defined.

Constants (Java)Permanent link for this heading

All the constants are static members of the APM class and can be accessed in a static way.

Flags (Java)Permanent link for this heading

Flags are used to specify the type of an event and are passed as argument to every event call. They are predefined by the API on the base class APM with the data type Byte and have the following possible values:

  • FLAG_NONE
  • FLAG_ENTER
  • FLAG_LEAVE
  • FLAG_WAIT
  • FLAG_WARNING
  • FLAG_ERROR
  • FLAG_PROCESS_INFO

For more details about the flags and there meaning see the general chapter “Flags”.

Log Level (Java)Permanent link for this heading

An event will only be logged if the event-level is lower or equal to the value selected in the session or log-definition. The log levels are predefined by the API on the base class APM with the data type Byte and have the following possible values:

  • EVENT_LEVEL_LOG
  • EVENT_LEVEL_IPC (only internal)
  • EVENT_LEVEL_NORMAL
  • EVENT_LEVEL_DETAIL
  • EVENT_LEVEL_DEBUG

For more details about the log levels and there meaning see the general chapter “Log Level”.

Predefined Modules (Java)Permanent link for this heading

To use a predefined module create a new APMModule object (by means of calling the constructor) with the predefined module name. This object will be used later to fire events for that module.

For a list of available standard modules with a set of predefined events see chapter “Standard Modules”.

Usage Example

APMModule mod1 = new APMModule(APM.MODULE_NAME_OS);

APMModule mod2 = new APMModule(APM.MODULE_NAME_XMLHTTP);

Predefined Events (Java)Permanent link for this heading

The SDK already provides a set of predefined events used for general purpose. For a full listing of all available predefined events see the generic chapter “Predefined Events”.

All predefined events are declared and available as global constants on the base class “APM”.

Error/Trace Events:

Use these standard events to mark error, warning or info conditions in your application:

  • EVENT_ERROR
  • EVENT_WARNING
  • EVENT_INFO
  • EVENT_TRACE

Data Types / Class Overview (Java)Permanent link for this heading

APM (Java)Permanent link for this heading

The APM class is the base class of the Software-Telemetry SDK. It contains all global defined constants as described in chapter “Constants (Java)”. Use the methods from the APM class in a static way (there is no new instance allocation required).

The APM class supports the following global static methods which do not require an application scope or status:

  • IsConnected
  • IsCompatible
  • DetachThread
  • AttachThread

A detailed description of this class with all methods explained is described in chapter “APM Class and Methods (Java)”.

APMApplication (Java)Permanent link for this heading

APMApplication is the base class for own application implementation and handles the request scope and reporting functions.

After creating an instance with the class constructor passing the application registration information, it stores the application handle inside and provides all context-specific functions for your application.

The APMApplication class supports the following instance/class methods which require an application scope and have to be called on your object instance of APMApplication:

  • RegisterFilterValue
  • CreateContext
  • AttachContext
  • ReleaseContext
  • GetContext
  • GetSyncMark
  • SetSyncMark
  • HasActiveContext
  • Report
  • ReportValue
  • ReportContent

A detailed description of this class with all methods explained is described in chapter “APMApplication Class and Methods (Java)”.

Note: At the end of your program lifecycle you should call the Unregister()-function to be sure that also the native library (JNI) objects are released (to prevent memory leaks).

APMModule (Java)Permanent link for this heading

APMModule is the base class for own module implementation and is used to fire instrumentation events.

After creating an instance with the class constructor passing the module name, it stores the module handle inside and provides all module-specific functions for your application.

The APMModule class supports the following instance/class methods which require a module scope and have to be called on your object instance of APMModule:

  • RegisterEvent
  • Event
  • EventStr
  • EventParam

A detailed description of this class with all methods explained is described in chapter “APMModule Class and Methods (Java)”.

Note: At the end of your program lifecycle you should call the Unregister()-function to be sure that also the native library (JNI) objects are released (to prevent memory leaks).

APMParameter (Java)Permanent link for this heading

APMParameter is used as data class for generic event parameters.

To define any parameters used in events you have to create a new APMParameter instance and add the typed parameters to that instance:

  • AddInt32
  • AddInt64
  • AddString

A detailed description of this class with all methods explained is described in chapter “APMParameter Class and Methods (Java)”.

APMCompatibilityInfo (Java)Permanent link for this heading

The APMCompatibilityInfo class is a simple data structure providing the state and the message of the library compatibility.

The current APMCompatibilityInfo can be obtained using the public method call: APM.IsCompatible() which will return an instance of the class APMCompatibilityInfo (see “Method IsCompatible (Java)”).

Type Declaration

package com.apptelemetry.apm;

public class APMCompatibilityInfo {

    public boolean compatible;
    public String message;

}

APM Class and Methods (Java)Permanent link for this heading

The APM class is the base class of the Software-Telemetry SDK. It contains all global defined constants as described in chapter “Constants (Java)”. Use the methods from the APM class in a static way (there is no new instance allocation required).

Remarks:

With version 2010 Fall Release the application-specific functions (CreateContext, ..., Report, ...) of the Java API where moved to the APMApplication class (see chapter “APMApplication Class and Methods (Java)”) and have to be called on an object instance of this class!

Method IsConnected (Java)Permanent link for this heading

The API method IsConnected will tell you if the application (the one that is instrumented with the APM SDK) has successfully registered to an app.telemetry agent and is currently connected to the agent process.

Only when an application is successfully connected to an app.telemetry agent, Software-Telemetry data will be processed and sent to and collected by the app.telemetry server

Syntax

public static boolean IsConnected();

Parameters:

This function does not take any arguments.

Return Value:

  • true: if the application has successfully registered to and connected to an app.telemetry agent.
  • false: if the application has not registered or is currently not connected to an app.telemetry agent or if the native Software-Telemetry library is not loaded correctly.

Usage Example

public static void main(String[] args) {

    boolean apiConnected = APM.IsConnected();

    System.out.println("Library connected via agent to server: " + apiConnected);

}

Method IsCompatible (Java)Permanent link for this heading

Call IsCompatible to check if the native library is compatible with the implementation in the current softwaretelemetry.jar archive.

Syntax

public static APMCompatibilityInfo IsCompatible();

Parameters:

This function does not take any arguments.

Return Value:

  • Instance of APMCompatibilityInfo. The member compatible is set to true if the library is compatible. The message member contains a descriptive text and an optional product name and version number.

Remarks:

For details about the object structure of APMCompatibilityInfo see chapter “APMCompatibilityInfo (Java)

Usage Example

public static void main(String args[]) {

    APMCompatibilityInfo ci = APM.IsCompatible();

    if (!ci.compatible) {
        System.out.println("INCOMPATIBLE: " + ci.message);

        System.exit(1);

    } else {
        System.out.println(ci.message);

    }

}

Method DetachThread (Java)Permanent link for this heading

Call the DetachThread-method when processing of a particular request is suspended and will be resumed later in this or another thread in the same process. Pass the handle returned by this method to the AttachThread-method to resume processing (see “Method AttachThread (Java)”).

This functionality is in particular useful in queuing systems, where a large number of requests will be queued and processed by a small number of worker threads asynchronous to the initial request. Using the Detach-/AttachThread methods you can follow the request through the process and even measure the time spent in the queue, even if a different thread continues processing.

Syntax

public static long DetachThread()

Parameters:

This function does not take any arguments.

Return Value:

  • DetachThread generates an id (64bit) that uniquely identifies the current state of the request. If the function succeeds, the return value is not 0.
  • The function will return 0 in case the library is not available or if no request has been started using CreateContext and/or AttachContext.

Usage Example

public class Task {

    //...
    public
long tx;
    //...

    public void Initialize(/* ... */)
    {

        app.CreateContext("filterstring");
        module.Event(EVENT_ENTER_TASK_TO_QUEUE, APM.EVENT_LEVEL_NORMAL, APM.FLAG_ENTER);

        
tx = APM.DetachThread();
        schedule();

    }

    public void process()
    {

        APM.AttachThread(tx);
        module.Event(EVENT_REMOVE_TASK_FROM_QUEUE, APM.EVENT_LEVEL_NORMAL, APM.FLAG_LEAVE);

        // process work

        app.ReleaseContext();
    }

}

Remarks:

Be careful to use DetachThread and AttachThread in a balanced way. DetachThread will store the current state of the request in memory and AttachThread will remove the information from memory while restoring the request state. So calls to DetachThread lacking a continuation will leak memory and will leave the request in a "running" state. Multiple calls to AttachThread will not have an effect, because the request state is only available to the first call to AttachThread.

Method AttachThread (Java)Permanent link for this heading

Call the AttachThread-method when processing of a particular request is resumed after being suspended in this or another thread of the same process. Pass the handle returned by DetachThread-method to restore the recorded state of the request.

For more details see “Method DetachThread (Java)”.

Syntax

public static void AttachThread(long transaction);

Parameters:

  • transaction: AttachThread uses the transaction handle generated by DetachThread to identify the current state of the request.

Return Value:

This function does not return any value.

Usage Example

See Method DetachThread (Java)

APMApplication Class and Methods (Java)Permanent link for this heading

The APMApplication class is the base class for your application registration, the context- and report-functions and the filter registration (callback or directly). It stores the application handle inside and provides all application-specific functions for your application to be called on your APMApplication object instance.

Your own application implementation may override the callback function EnumFilterValuesCallback (default implementation is empty) to provide the filters values via the callback function. Alternatively the filters may also be registered directly.

The application is registered when a new instance of the APMApplication class is being created.

Note: At the end of your program lifecycle you should call the Unregister()-function to be sure that also the native library (JNI) objects are released (to prevent memory leaks).

Constructor APMApplication (Java)Permanent link for this heading

Syntax

public APMApplication(String appName, String appId, String appTierName, String appTierId);

Parameters:

  • appName: The name of your application
  • appId: The id of your application
  • appTierName: The tier inside the application
  • appTierId: id to distinguish multiple services of one application tier

Usage Example

public static void main(String args[]) {

    APMApplication app = new APMApplication("Java Test-App", "1", "Tier", "1");
    APMModule mod = new APMModule("module1");

    registerEvents(mod);
    registerFilters(app);

    app.CreateContext("MyFilter");

    mod.Event(10, APM.EVENT_LEVEL_LOG, APM.FLAG_ENTER);
    // ... process request and fire more events

    mod.Event(10, APM.EVENT_LEVEL_LOG, APM.FLAG_LEAVE);

    app.ReleaseContext();

    mod.Unregister();
    app.Unregister();

}

Method Unregister (Java)Permanent link for this heading

Call Unregister at the end of your program to tell the Fabasoft app.telemetry agent that your program lifetime ends now.

The automatic unregister call via the object destructor may not work properly because the Java native library (JNI) also keeps a reference on the object which may prevent the destructor from run after the object is not used any longer in your application code.

The explicit call of Unregister will release any references to the APMApplication also in the Java native library (JNI).

Syntax

public void Unregister();

Method RegisterFilterValue (Java)Permanent link for this heading

RegisterFilterValue registers application specific filter items, which may be used as filter strings in the CreateContext function. Registering the filter values helps the user selecting filters when starting Software-Telemetry sessions in the client interface.

There are two possibilities how to register the filter values for your application:

  • Directly at program start: you have to provide all filter values after your application is created/registered - by calling the registerFilterValue method with all possible filter values.
  • via callback function: you can implement your own APMApplication subclass and implement the callback function EnumFilterValuesCallback - where you provide the available filters for your application on invocation by calling the RegisterFilterValue method.

The APMApplication class is not abstract but provides an empty method body for the callback function EnumFilterValuesCallback.

This callback method will be invoked only if no application with same application name, application id and application tier has already registered filter values. Enumerate and register the filter values in the callback function. This mechanism is designed e.g. for web service farms, where the enumeration of the filters will register all users. So it is sufficient to register the filter values once on one web service instance.

Syntax

public void RegisterFilterValue(String filterValue, String filterDescription);

Parameters:

  • filterValue (String): The exact filter value as a string as used in the CreateContext method. (e.g. the user login string: "domain\user.name")
  • filterDescription (String): Description string of the filter. (e.g. a display string for the user login: "full user name")

Return Value:

This function does not return any value.

Remarks:

You should register all filters that are available in your application so that the user can choose in the client interface from a list box.

Usage Example

// Extend the APMApplication API class with your own implementation
//    to provide the events and filters of your application.

class InstrumentedApp extends APMApplication {

    // own constructor invoking super constructor from base class
    public InstrumentedApp(String appName, String appId, String appTier
Name, String appTierId) {
        super(appName, appId, appTier
Name, appTierId);
    }

    public void EnumFilterValuesCallback() {
        RegisterFilterValue("user.name1", "Test User 1");

        RegisterFilterValue("user.name2", "Test User 2");

        RegisterFilterValue("user.name3", "Test User 3");

        // or get a map of all used login names with description

        // and add them by means of iterating over all entries.

    }

} // InstrumentedApp

Method CreateContext (Java)Permanent link for this heading

Call CreateContext to start a new request in the Software-Telemetry context.

If the filter value matches a currently started session filter, logging is started for the current execution thread and the request will be associated with the session. You may call CreateContext more than once in one request in order to pass additional filter values. The request will start at the first CreateContext and will be finished by the first ReleaseContext. Make sure to call ReleaseContext (see “Method ReleaseContext (Java)”) when exiting the request.

A context can be regarded as a complete request that is traced through several involved threads or modules. And the full context request has a duration that spans the interval from CreateContext to ReleaseContext.

Syntax

public void CreateContext(String filtervalue);

Parameters:

  • filtervalue (String): (may be empty) Value to be matched against the session start value.

Return Value:

This function does not return any value.

See chapter “Request and Context Handling” for more information on the app.telemetry request concept.

Usage Example

public static void main(String args[]) {
    // ...

    APMApplication app = new APMApplication(...);

    app.CreateContext("filtervalue");

    // ...

    // do anything with the Software-Telemetry (log events, ...)

    // ...

    app.ReleaseContext();

    // ...

}

Method ReleaseContext (Java)Permanent link for this heading

Call ReleaseContext to indicate the end of the processing of one request. One ReleaseContext will close the request no matter how many CreateContext or AttachContext calls have been called.

Syntax

public void ReleaseContext();

Remarks:

If you don't call ReleaseContext the request keeps the running status until the request-timeout has been reached.

Usage Example

See Method CreateContext (Java)

Method GetContext (Java)Permanent link for this heading

Call the GetContext-method to get a new context handle from the SDK.

This context handle is used to synchronize different threads/processes/modules - this helps you track the control flow through a distributed environment. The acquired context handle has to be submitted (either by transmitting over the network or in another way) to the other thread/process/module which has to call the AttachContext-method with the same context.

For more information see also “Passing Context” and “Method AttachContext (Java)”.

Syntax

public byte[] GetContext();

Parameters:

This function does not take any arguments.

Return Value:

  • This function will return a new context handle as byte-array
  • or null if the native library is not loaded successfully.

Usage Example

import java.util.concurrent.locks.Lock;
import java.util.concurrent.locks.ReentrantLock;

import com.apptelemetry.apm.*;

class InterfaceTestHelpers {
  static void registerFilters(APMApplication application) {

    application.RegisterFilterValue("filter1", "description1");

    // ...

  }

  static void registerEvents(APMModule module) {
    module.RegisterEvent(101, "eventdesc1", null);

    // ...

    module.RegisterEvent(121, "eventParams1", "int32;int64;String");

  }

}

class InterfaceTestRunnable implements Runnable {
  public final Lock lock = new ReentrantLock();

  public byte[] m_syncMark = null;

  public byte[] m_context = null;

  private APMApplication m_application;

  private APMModule m_module;

  public InterfaceTestRunnable(APMApplication app) {
    m_application = app;

  }

  public void run(){
    lock.lock();

    // create modules and register filters and events (application already created outside)

    if (m_context == null) {
      m_module = new APMModule("JavaTestService1");

      // sleep 5sec

      m_application.CreateContext("filter1");

    } else {
      m_module = new APMModule("JavaTestService2");

      // sleep 5sec

      m_application.AttachContext(m_context);

    }

    InterfaceTestHelpers.registerEvents(m_module);
    InterfaceTestHelpers.registerFilters(m_application);

    m_module.EventStr(101, APM.EVENT_LEVEL_DEBUG, APM.FLAG_NONE, "start of the request");

    if (m_context == null) {
      m_context = m_application.GetContext();

    } else {
      m_syncMark = m_application.GetSyncMark();

      module.EventStr(101, APM.EVENT_LEVEL_DEBUG, APM.FLAG_NONE, "end of the request 2");

      m_application.ReleaseContext();

      lock.unlock();

      return;

    }

    lock.unlock();

    // sleep 3sec

    lock.lock();
    lock.unlock();

    m_application.SetSyncMark(m_syncMark);

    m_module.EventStr(101, APM.EVENT_LEVEL_DEBUG, APM.FLAG_NONE, "end of the request 1");

    m_application.ReleaseContext();

  }
}

public class InterfaceTestJava {

  public static void main(String args[]) {
    APMApplication app = new APMApplication("InterfaceTestJava Application", appId, "testAppTier
NameJava", "testAppTierIdJava");

    // sleep 1sec
    InterfaceTestRunnable application1 = new InterfaceTestRunnable();

    // start 2 parallel application threads
    //  (that will communicate with each other and pass the context)

    new Thread(app).start();
    // sleep 1sec

    new Thread(app).start();

  }

}

Method AttachContext (Java)Permanent link for this heading

Call AttachContext to restore the context acquired through GetContext in another thread or process.

For more information see also “Passing Context” and “Method GetContext (Java)”.

Syntax

public void AttachContext(byte[] context);

Parameters:

  • context: The context which you want to attach to. You get such a context by calling GetContext.

Return Value:

This function does not return any value.

Usage Example

See Method GetContext (Java)

Method GetSyncMark (Java)Permanent link for this heading

Call the GetSyncMark-method to get a synchronization handle that can be passed to another thread/process/module to synchronize control flow.

The difference between a sync-marks and a context is:

  • A context is used to associate with one request. It is created by the initiator and attached to by other threads/process/modules belonging to the same request.
  • A sync-mark is only a time synchronization handle between the different threads/processes/modules which can be used several times to synchronize the control flow exactly (different systems may have different timestamps and different time precision).

For more information see also “Synchronizing Timeline with SyncMarks”.

Syntax

public byte[] GetSyncMark();

Parameters:

This function does not take any arguments.

Return Value:

  • This function will return a new synchronization handle as byte-array
  • or null if the native library is not loaded successfully.

Usage Example

See Method GetContext (Java)

Method SetSyncMark (Java)Permanent link for this heading

Call the SetSyncMark-method to pass and submit a synchronization handle that you got from the GetSyncMark-call to synchronize the sequence of events.

For more information see also “Synchronizing Timeline with SyncMarks”, “Method GetSyncMark (Java)” and “Method GetContext (Java)”.

Syntax

public void SetSyncMark(byte[] syncMark);

Parameters:

  • syncMark: The synchronization handle that was acquired by GetSyncMark from another thread/process/module.

Return Value:

This function does not return any value.

Usage Example

See Method GetContext (Java)

Method HasActiveContext (Java)Permanent link for this heading

The API method HasActiveContext defined in the APMApplication class will tell you if there is currently a Software-Telemetry session for the given log level for the application (the one that is instrumented with the APM SDK) running.

This information should be used to avoid costly operations preparing parameters for events that are currently not logged.

Syntax

public boolean HasActiveContext(byte level);

Parameters:

  • level (byte): Software-Telemetry log level to be checked.

Return Value:

  • true: if logging is active for this application for the given log level.
  • false: otherwise (if logging is not active for the given log level) or if the native Software-Telemetry library is not loaded correctly.

Remarks:

If the native Software-Telemetry library could not be loaded within your Java process a log statement will be sent to the Java logging facility with log level FINE and namespace com.apptelemetry.apm.APM.

Usage Example

public static void main(String[] args) {
    // create application and module and context

    // ... application logic

    if (app.HasActiveContext(APM.EVENT_LEVEL_DETAIL) {
        // do complex preparation of log message

        String logmsg = calcProgressInfo(...);  

        // time-consuming operation - do only if telemetry active

        module.EventStr(123, APM.EVENT_LEVEL_DETAIL, APM.FLAG_NONE, logmsg);
    }

    // finish application logic and release context
}

Method Report (Java)Permanent link for this heading

Call the Report-method from the APMApplication class to create a new feedback report.

The filter value will be matched to the description using the registered filter values.

Use the textual description of the feedback entered by the user or generated by the application to identify the report session later again.

Syntax

public void Report(String filtervalue, String keyvalue, String description);

Parameters:

  • filtervalue (String): the raw filter value, which was registered with RegisterFilterValue
  • reportkey (String): A key value may be generated by the calling application to associate further descriptions to a feedback. If empty, a new feedback report will be generated on each call.
  • description (String): Textual description of the feedback entered by the user or generated by the application. The maximum length of the description is 32 768 Bytes.

Return Value:

This function does not return any value.

Usage Example

public void generateReport(String username, String description, String reportkey) {

    app.Report(username, reportkey, description);

    app.ReportValue(reportkey, "username", username);

    // read file content into byte array and pass it to report function
    File file = new File("document.html");

    FileInputStream fileInputStream = new FileInputStream(file);

    byte[] data = new byte[(int) file.length()];

    fileInputStream.read(data);

    fileInputStream.close();

    app.ReportContent(reportkey, "document.html", "text/html", data);
}

Method ReportValue (Java)Permanent link for this heading

Call ReportValue to add a key/value pair to an existing report.

For more information see "Method Report (Java)”.

Syntax

public void ReportValue(String reportkey, String key, String value);

Parameters:

  • reportkey (String): match the reportkey of the Report function to associate the value with the report session.
  • key (String): A key describes the meaning of the value. Only one value can be associated to a key in one report session.
  • value (String): Textual value (max. 32 kBytes).

Return Value:

This function does not return any value.

Usage Example

See "Method Report (Java)

Method ReportContent (Java)Permanent link for this heading

Call ReportContent to add content to an existing report.

For more information see "Method Report (Java)”.

Syntax

public void ReportContent(String reportkey, String filename, String mimeType, byte[] content);

Parameters:

  • reportkey (String): match the reportkey of the Report function to associate the content with the report session.
  • filename (String): A filename describing the content of the file. (max. 256 Bytes) – this is the name of the file in the reported session with which the data is persisted.
  • mimeType (String): MIME-Type of content – (e.g.: text/plain, image/png, ...) – later used for presentation of content.
  • content (byte[]): Byte array containing binary data.

Return Value:

This function does not return any value.

Usage Example

See "Method Report (Java)

APMModule Class and Methods (Java)Permanent link for this heading

The APMModule-class represents a registered Module. You have to register a module to set telemetry points. You may register a module multiple times with the same name. Events of equally named modules will show up in the same column.

Note: At the end of your program lifecycle you should call the Unregister()-function to be sure that also the native library (JNI) objects are released (to prevent memory leaks).

Constructor APMModule (Java)Permanent link for this heading

The constructor registers the module with the given name directly on app.telemetry agent/server.

Syntax

public APMModule(string name);

Method Unregister (Java)Permanent link for this heading

Call Unregister at the end of your program to tell the Fabasoft app.telemetry agent that your program lifetime ends now.

The automatic unregister call via the object destructor may not work properly because the Java native library (JNI) also keeps a reference on the object which may prevent the destructor from run after the object is not used any longer in your application code.

The explicit call of Unregister will release any references to the APMModule also in the Java native library (JNI).

Syntax

public void Unregister();

Method RegisterEvent (Java)Permanent link for this heading

It is required and important to register the events used in your application in order to get the correct event names and parameter descriptions as provided. The RegisterEvent-method will tell the app.telemetry server a name for every event-ID and optionally parameter descriptions for the parameters used in the event calls.

Syntax

public void RegisterEvent(long eventid, String eventDescription, String parameterDescription);

Parameters:

  • eventid (long): Unique ID of event which is used later on for every instrumentation point.
  • eventDescription (String): Description string of event. A describing name for that event.
  • parameterDescription (String): Name of event parameters. If more parameters are used in one event, separate the parameter names by semi-colon (;). For example: "name;count;size"

Return Value:

This function does not return any value.

Usage Example

public class InstrumentedApplication {
  public static final int EVENT_HTTP_GET = 200;

  public static final int EVENT_HTTP_POST = 201;

  public static final int EVENT_REQUEST = 210;

  public static final int EVENT_PARAM_IN = 211;

  public static final int EVENT_PARAM_OUT = 212;

  public static final int EVENT_PARAMS = 213;

  public void registerEvents(APMModule module) {
    module.RegisterEvent(EVENT_HTTP_GET, "HTTP Get Request", "");

    module.RegisterEvent(EVENT_HTTP_POST, "HTTP Post Request", "");

    module.RegisterEvent(EVENT_REQUEST, "Process HTTP Request", "");

    module.RegisterEvent(EVENT_PARAM_IN, "Process HTTP Request - Enter", "request");

    module.RegisterEvent(EVENT_PARAM_OUT, "Process HTTP Request - Leave", "response");
    module.RegisterEvent(EVENT_PARAMS, "Process HTTP Request - Evaluate Parameters", "id;thread;stock");

  }

  public static void main(String[] args) {
     // create application and module

     APMApplication app = new APMApplication();

     APMModule mod = new APMModule();

     registerEvents(mod);// register all events

     // request and event calls
     app.CreateContext("filtervalue");

     mod.Event(EVENT_PARAM_IN, APM.EVENT_LEVEL_LOG, APM.FLAG_ENTER, "request-data...");

     //...

     mod.Event(EVENT_PARAM_OUT, APM.EVENT_LEVEL_LOG, APM.FLAG_LEAVE, "response-data...");

     app.ReleaseContext();

  }

}

Method Event (Java)Permanent link for this heading

Call the simple Event-method to log events without parameters.

Only the event-ID and the flags define the representation of the event that will be displayed with the registered event name for the used id.

This method is part of the APMModule class and has to be called on your own module implementation class.

Syntax

public void Event(long eventid, byte level, bytes flags);

Parameters:

  • eventid (long): id of the event being processed. Should be defined as constant in your module implementation class.
  • level (byte): event detail level for filtering. For the list of available log levels see chapter “Log Level (Java)”.
  • flags (byte): flags to mark events with Enter-, Leave- and/or Wait-semantic. More than one flags can be added together with a logic OR (|). For the list of available flags see chapter “Predefined Events (Java)”.

Return Value:

This function does not return any value.

Usage Example

private void processData(String input) {
    // ...

    // fire enter event without parameters ...

    m_module.Event(EVENT_REQUEST, APM.EVENT_LEVEL_NORMAL,
APM.FLAG_ENTER);

    // fire event with String parameter ...
    m_module.EventStr(EVENT_PARAM_IN, APM.EVENT_LEVEL_DETAIL, APM.FLAG_NONE, input);

    // ... process the data and do all the internal work ...

    // fire event with generic parameters ...
    APMParameter param = new APMParameter();

    param.AddInt64(id);

    param.AddInt32(threads);

    param.AddInt32(stock);

    m_module.EventParam(EVENT_PARAMS, APM.EVENT_LEVEL_DEBUG, APM.FLAG_NONE, param);

    // ...
    // fire leave enter event without parameters ...

    m_module.Event(EVENT_REQUEST, APM.EVENT_LEVEL_NORMAL, APM.FLAG_LEAVE);

}

Method EventStr (Java)Permanent link for this heading

Call the EventStr-method to log events with a single textual (string) parameter.

In addition to the event-ID (with the registered event name) and the flags a single string parameter value will be logged.

For more information see “Method Event (Java)”.

Syntax

public void EventStr(long eventid, byte level, bytes flags, String param);

Parameters:

  • eventid (long): id of the event being processed. Should be defined as constant in your module implementation class.
  • level (byte): event detail level for filtering. For the list of available log levels see chapter “Log Level (Java)”.
  • flags (byte): flags to mark events with Enter-, Leave- and/or Wait-semantic. More than one flags can be added together with a logic OR (|). For the list of available flags see chapter “Predefined Events (Java)”.
  • param (String): a string parameter to be logged – can be any textual or preformatted message.

Return Value:

This function does not return any value.

Usage Example

SeeMethod Event (Java)

Method EventParam (Java)Permanent link for this heading

Call the EventParam-method to log events with a generic parameter structure - with any number and combination of textual (string) values and integer values (32- and 64-bit).

To use the EventParam-method you have to allocate a new APMParameter. With a few helper methods you can add values to this parameter object and finally you can use the parameter object in the event function to be logged. For details how to allocate and fill the APMParameter object see chapter “APMParameter Class and Methods (Java)”.

Syntax

public void EventParam(long eventid, byte level, byte flags, APMParameter param);

Parameters:

  • eventid (long): id of the event being processed. Should be defined as constant in your module implementation class.
  • level (byte): event detail level for filtering. For the list of available log levels see chapter “Log Level (Java)”.
  • flags (byte): flags to mark events with Enter-, Leave- and/or Wait-semantic. More than one flags can be added together with a logic OR (|). For the list of available flags see chapter “Predefined Events (Java)”.
  • param (APMParameter): the parameter object containing any number of values to be logged.

Return Value:

This function does not return any value.

Usage Example

SeeMethod Event (Java)

APMParameter Class and Methods (Java)Permanent link for this heading

The APMParameter-class is an object structure for storing and managing parameter values that can be used for logging complex value structures with more than one or different type of values.

See also “Method EventParam (Java)”.

Constructor APMParameter (Java)Permanent link for this heading

Call the APMParameter-constructor to allocate a new parameter object where you can add any number of textual (string) values and integer values (32- and 64-bit).

Syntax

public APMParameter();

Method AddInt32 (Java)Permanent link for this heading

Call the method AddInt32 on your APMParameter-instance to add a simple integer value (32-bit) to that object.

Syntax

public void AddInt32(int value);

Parameters:

  • value (int): 32-bit integer value to be added to the parameter object.

Return Value:

This function does not return any value.

Usage Example

See Method EventParam (Java)”.

Method AddInt64 (Java)Permanent link for this heading

Call the method AddInt64 on your APMParameter-instance to add a simple integer value (64-bit) to that object.

Syntax

public void AddInt64(long value);

Parameters:

  • value (long): 64-bit integer/long value to be added to the parameter object.

Return Value:

This function does not return any value.

Usage Example

See Method EventParam (Java)”.

Method AddString (Java)Permanent link for this heading

Call the method AddString on your APMParameter-instance to add a textual (string) value to that object.

Syntax

public void AddString(String value);

Parameters:

  • value (String): textual parameter value to be added to the parameter object.

Return Value:

This function does not return any value.

Usage Example

See Method EventParam (Java)”.