Java API Reference

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 Project

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)

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

Flags (Java)

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)

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)

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

Usage Example

APMModule mod1 = new APMModule(APM.MODULE_NAME_OS);

APMModule mod2 = new APMModule(APM.MODULE_NAME_XMLHTTP);

Predefined Events (Java)

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 “

HttpRequestThe HttpRequest Module is used to trace the parameters of http requests such as URL, method, status, header fields and message bodies.The constant names are prefixed with “APM_” for the C/C++ API (APM_<constant>) and in the other object-oriented languages they are members of the APM base class (APM.<constant>).NameValueEventnameParametersAPM_MODULE_NAME_HTTPAPM.MODULE_NAME_HTTP"HttpRequest"APM_EVENT_HTTP_URLAPM.EVENT_HTTP_URL2000"URL"“scheme;host;path;extra”APM_EVENT_HTTP_METHODAPM.EVENT_HTTP_METHOD2001"Method"“method”APM_EVENT_HTTP_STATUSAPM.EVENT_HTTP_STATUS2002"Status"“code;message”APM_EVENT_HTTP_AUTHENTICATIONAPM.EVENT_HTTP_AUTHENTICATION2003"Authentication"“type;credential”APM_EVENT_HTTP_PROXYAPM.EVENT_HTTP_PROXY2004"Proxy"“server;username”APM_EVENT_HTTP_REQUEST_HEADERAPM.EVENT_HTTP_REQUEST_HEADER2010"Request Header"“header;value”APM_EVENT_HTTP_REQUEST_CONTENTTYPEAPM.EVENT_HTTP_REQUEST_CONTENTTYPE2011"Request Content Type"“media-type;charset;boundary”APM_EVENT_HTTP_REQUEST_CONTENTBODYAPM.EVENT_HTTP_REQUEST_CONTENTBODY2012"Request Body Part"APM_EVENT_HTTP_RESPONSE_HEADERAPM.EVENT_HTTP_RESPONSE_HEADER2020“Response Header”“header;value”APM_EVENT_HTTP_RESPONSE_CONTENTTYPEAPM.EVENT_HTTP_RESPONSE_CONTENTTYPE2021"Response Content Type"“media-type;charset;boundary”APM_EVENT_HTTP_RESPONSE _CONTENTBODYAPM.EVENT_HTTP_RESPONSE _CONTENTBODY2022"Response Body Part"
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

Predefined Application Property Keys and Names (Java)

View the language agnostic Application Properties section for an explanation of the properties listed below.

All predefined application property keys and names are available as public constants on the APM class.

PROPERTY_INSTANCE_GUID_KEY with name PROPERTY_INSTANCE_GUID_NAME

Predefined Application Value Keys and Names (Java)

View the language agnostic Application Values section for an explanation of the properties listed below.

All predefined application value keys and names are available as public constants on the APM class.

VALUE_VERSION_KEY with name VALUE_VERSION_NAME
VALUE_INSTANCE_NAME_KEY with name VALUE_INSTANCE_NAME_NAME

Data Types / Class Overview (Java)

APM (Java)

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)

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)

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)

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)

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; }

Type Declaration

package com.apptelemetry.apm;

public class APMCompatibilityInfo {

public boolean compatible;
public String message;

}

APM Class and Methods (Java)

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)

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); }

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)

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); } }

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)

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(); } }

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)

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)

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)

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(); }

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 RegisterApplicationProperty (Java)

Call RegisterApplicationProperty to register additional application registration properties immediately after you call to the APMApplication class constructor to ensure proper operation.

Syntax
public void RegisterApplicationProperty(String propertyKey, String propertyName, String propertyValue);

Parameters:

propertyKey: The application defined key of the property or the predefined PROPERTY_INSTANCE_GUID_KEY. Limited to 256 utf-8 encoded Bytes. Keys starting with “apm:” are reserved for internal use.
propertyName: The display name of the property (PROPERTY_INSTANCE_GUID_NAME for the example above). Limited to 512 utf-8 encoded Bytes.
propertyValue: The value of the property. Limited to 32768 utf-8 encoded Bytes.

Remarks:

Application registration Properties cannot be changed after they have been set.

Method RegisterApplicationValue (Java)

Syntax
public void RegisterApplicationValue(String valueKey, String valueName, String value);

Parameters:

valueKey: The application defined key of the value or one of the predefined (VALUE_VERSION_KEY, VALUE_INSTANCE_NAME_KEY, ...). Limited to 256 utf-8 encoded Bytes. Keys starting with “apm:” are reserved for internal use.
valueName: The display name of the property (VALUE_VERSION_NAME, VALUE_INSTANCE_NAME_NAME,... for the examples above). Limited to 512 utf-8 encoded Bytes.
value: The value of the property. Limited to 32768 utf-8 encoded Bytes.

Remarks:

Application values may be changed at runtime but must not have a high change frequency and do not have any history of previous values.

Method Unregister (Java)

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)

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 appTierName, String appTierId) { super(appName, appId, appTierName, 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

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 appTierName, String appTierId) {
        super(appName, appId, appTierName, 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)

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 “Application Properties” 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)

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)

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, "testAppTierNameJava", "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(); } }

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, "testAppTierNameJava", "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)

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)

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)

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)

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 }

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)

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); }

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)

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)

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)

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)

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

Syntax
public APMModule(string name);

Method Unregister (Java)

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

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)

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(); } }

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)

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); }

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)

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
See “Method Event (Java)”

Method EventParam (Java)

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
See “Method Event (Java)”

APMParameter Class and Methods (Java)

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)

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)

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)

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)

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

Java API Reference

Configure Eclipse for Java Project

Constants (Java)

Flags (Java)

Log Level (Java)

Predefined Modules (Java)

Predefined Events (Java)

Predefined Application Property Keys and Names (Java)

Predefined Application Value Keys and Names (Java)

Data Types / Class Overview (Java)

APM (Java)

APMApplication (Java)

APMModule (Java)

APMParameter (Java)

APMCompatibilityInfo (Java)

APM Class and Methods (Java)

Method IsConnected (Java)

Method IsCompatible (Java)

Method DetachThread (Java)

Method AttachThread (Java)

APMApplication Class and Methods (Java)

Constructor APMApplication (Java)

Method RegisterApplicationProperty (Java)

Method RegisterApplicationValue (Java)

Method Unregister (Java)

Method RegisterFilterValue (Java)

Method CreateContext (Java)

Method ReleaseContext (Java)

Method GetContext (Java)

Method AttachContext (Java)

Method GetSyncMark (Java)

Method SetSyncMark (Java)

Method HasActiveContext (Java)

Method Report (Java)

Method ReportValue (Java)

Method ReportContent (Java)

APMModule Class and Methods (Java)

Constructor APMModule (Java)

Method Unregister (Java)

Method RegisterEvent (Java)

Method Event (Java)

Method EventStr (Java)

Method EventParam (Java)

APMParameter Class and Methods (Java)

Constructor APMParameter (Java)

Method AddInt32 (Java)

Method AddInt64 (Java)

Method AddString (Java)

Download PDF

Download PDF