Dynatrace OpenKit API methods

To obtain a new OpenKit instance, use DynatraceOpenKitBuilder.

String applicationID = "application-id";
long deviceID = Util.getDeviceID();
String endpointURL = "https://tenantid.beaconurl.com/mbeacon";

OpenKit openKit = new DynatraceOpenKitBuilder(endpointURL, applicationID, deviceID).build();

string applicationName = "My OpenKit application";
string applicationID = "application-id";
long deviceID = Util.GetDeviceID();
string endpointURL = "https://tenantid.beaconurl.com/mbeacon";

// by default verbose logging is disabled
IOpenKit openKit = new DynatraceOpenKitBuilder(endpointURL, applicationID, deviceID).Build();

• endpointURL denotes the Dynatrace endpoint that OpenKit communicates with. The endpoint URL can be found in the settings page of the custom application. More information can be found here.
• applicationID is the unique identifier of the application. The application's id can be found in the settings page of the custom application. More information can be found here.
• deviceID is a unique identifier, which can be used to uniquely identify a device.

Optional Configuration

In addition to the mandatory parameters described above, the builder provides additional methods to further customize OpenKit. These include device specific information like operating system, manufacturer, or model id.

All OpenKit communication to the backend happens via HTTPS. By default, OpenKit expects valid server certificates. However it is possible, if needed, to bypass certificate validation. A custom trust manager can be configured using the builder.

Note: We do NOT recommend bypassing TLS/SSL server certificate validation, since this allows man-in-the-middle attacks.

class MyCustomTrustManager implements SSLTrustManager {
    // implement interface methods
}

SSLTrustManager trustManager = new MyCustomTrustManager()

OpenKit openKit = new DynatraceOpenKitBuilder(endpointURL, applicationID, deviceID)
    .withTrustManager(trustManager)
    .build();

class MyCustomTrustManager : ISSLTrustManager {
    // implement interface methods
}

ISSLTrustManager trustManager = new MyCustomTrustManager()

OpenKit openKit = new DynatraceOpenKitBuilder(endpointURL, applicationID, deviceID)
    .WithTrustManager(trustManager)
    .Build();

By default, OpenKit uses a logger implementation that logs to stdout. If the default logger is used, verbose logging can be enabled using DynatraceOpenKitBuilder. By enabling verbose mode, info and debug messages are logged. It is also possible to configure a custom logger. See logging for OpenKit for details

When obtaining an OpenKit instance from the builder, the instance starts an automatic initialization phase. By default, initialization is performed asynchronously.

There might be situations when a developer wants to ensure that initialization is completed before proceeding with the program logic, for example, in case of short-lived applications, where a valid init and shutdown cannot be guaranteed. For such cases OpenKit allows to wait for the initialization in two ways:

• with timeout: The calling threads waits a given amount of time for OpenKit to initialize. The method returns false in case the timeout expired or a shutdown was performed in the meantime and true to indicate successful initialization.
• without timeout: The calling thread blocks until OpenKit is initialized. In case of misconfiguration this might block the calling thread indefinitely. The return value indicates whether the OpenKit instance has been initialized or a shutdown was performed meanwhile.

// wait until the OpenKit instance is fully initialized
boolean success = openKit.waitForInitCompletion();

// wait 10 seconds for OpenKit to complete initialization
long timeoutInMilliseconds = 10 * 1000;
boolean success = openKit.waitForInitCompletion(timeoutInMilliseconds);

// wait until the OpenKit instance is fully initialized
bool success = openKit.WaitForInitCompletion();

// wait 10 seconds for OpenKit to complete initialization
int timeoutInMilliseconds = 10 * 1000;
bool success = openKit.WaitForInitCompletion(timeoutInMilliseconds);

In addition, OpenKit enables you to verify whether or not it's been initialized.

boolean isInitialized = openKit.isInitialized();
if (isInitialized) {
    System.out.println("OpenKit is initialized");
} else {
    System.out.println("OpenKit is not yet initialized");
}

bool isInitialized = openKit.IsInitialized;
if (isInitialized) {
    Console.WriteLine("OpenKit is initialized");
} else {
    Console.WriteLine("OpenKit is not yet initialized");
}

New sessions can be created using the OpenKit instance obtained from the builder. When creating a new session an optional IP address can be provided.

• If a valid IPv4 or IPv6 address is provided it will be assigned to the session.
• If no IP address or an invalid IP address is provided, the IP address of the session will be auto-detected and assigned on the server side.

This example shows how to create sessions.

// create a session and pass an IP address
String clientIPAddress = "12.34.56.78";
Session sessionWithArgument = openKit.createSession(clientIPAddress);

// create a session and let the IP be assigned on the server side
Session sessionWithoutArgument = openKit.createSession(null);

// create a session and pass an IP address
string clientIPAddress = "12.34.56.78";
ISession sessionWithArgument = openKit.CreateSession(clientIPAddress);

// create a session and let the IP be assigned on the server side
ISession sessionWithoutArgument = openKit.CreateSession(null);

The user assigned to a session can be identified. This enables you to search and filter specific user sessions and analyze individual user behavior over time in the backend.

session.identifyUser("jane.doe@example.com");

session.IdentifyUser("jane.doe@example.com");

When a session is no longer needed, it should be ended explicitly. Although all open sessions are automatically ended when OpenKit is shut down, it's highly recommended to manually end sessions, which are no longer in use.

session.end();
session = null; // not needed, just used to indicate that the session is no longer valid.

session.End();
session = null; // not needed, just used to indicate that the session is no longer valid.

Unexpected application crashes can be reported on a session. The example below shows how an exception might be reported.

private static int div(int numerator, int denominator) {
	return numerator / denominator;
}

public static void divWithCrash() {
    int numerator = 5;
    int denominator = 0;
    try {
        System.out.println("Got: " + div(numerator, denominator));
    } catch (Exception e) {
        String errorName = e.getClass().getName();
        String reason = e.getMessage();
        String stacktrace = getStackTraceAsString(e); // get the stacktrace as string, similar as e.printStackTrace()
        // and now report the application crash via the session
        session.reportCrash(errorName, reason, stacktrace);
    }
}

private static int Div(int numerator, int denominator)
{
    return numerator / denominator;
}

public static void DivWithCrash()
{
    int numerator = 5;
    int denominator = 0;
    try
    {
        Console.WriteLine("Got: " + Div(numerator, denominator));
    }
    catch (Exception e)
    {
        string errorName = e.GetType().ToString();
        string reason = e.Message;
        string stacktrace = e.StackTrace;
        // and now report the application crash via the session
        session.ReportCrash(errorName, reason, stacktrace);
    }
}

Root actions and actions are hierarchically named events, where a root action represents the first level of the hierarchy. A root action can have child actions and is created from a session. Child actions are created from a root action.

String rootActionName = "rootActionName";
String childActionName = "childActionName";
// create a root action for a session
RootAction rootAction = session.enterAction(rootActionName);
// create a child action for the root action
Action childAction = rootAction.enterAction(childActionName);

string rootActionName = "rootActionName";
string childActionName = "childActionName";
// create a root action for a session
IRootAction rootAction = session.EnterAction(rootActionName);
// create a child action for the root action
IAction childAction = rootAction.EnterAction(childActionName);

To record accurate timing information for actions, actions must be "left" once they're finished. The return value of the leave method will always return the parent action. For root actions null is returned.

Action parentAction = action.leave(); // returns the root action
Action parent = parentAction.leave(); // will always return null

IAction parentAction = action.Leave(); // returns the appropriate RootAction
IAction parent = parentAction.Leave(); // will always return null

Named events can be reported on actions.

String eventName = "eventName";
action.reportEvent(eventName);

// also report on the RootAction
rootAction.reportEvent(eventName);

string eventName = "eventName";
action.ReportEvent(eventName);

// also report on the RootAction
rootAction.ReportEvent(eventName);

Key-value pairs can be reported for actions, as shown in the example below. Overloaded methods exist for the following value types:

• Integer
• Double
• String

// first report an int value
String keyIntType = "intType";
int valueInt = 42;
action.reportValue(keyIntType, valueInt);

// then let's report a double value
String keyDoubleType = "doubleType";
double valueDouble = 3.141592653589793;
action.reportValue(keyDoubleType, valueDouble);

// and also a string value
String keyStringType = "stringType";
String valueString = "The quick brown fox jumps over the lazy dog";
action.reportValue(keyStringType, valueString);

// first report an int value
string keyIntType = "intType";
int valueInt = 42;
action.ReportValue(keyIntType, valueInt);

// then let's report a double value
string keyDoubleType = "doubleType";
double valueDouble = 3.141592653589793;
action.ReportValue(keyDoubleType, valueDouble);

// and also a string value
string keyStringType = "stringType";
string valueString = "The quick brown fox jumps over the lazy dog";
action.ReportValue(keyStringType, valueString);

An action also has the possibility to report an error with a given name, code, and reason. The code fragment below shows how this can be done.

String errorName = "Unknown Error";
int errorCode = 42;
String reason = "Not sure what's going on here";

action.reportError(errorName, errorCode, reason);

string errorName = "Unknown Error";
int errorCode = 42;
string reason = "Not sure what's going on here";

action.ReportError(errorName, errorCode, reason);

One of the most powerful OpenKit features is web request tracing. When the application starts a web request (e.g. HTTP GET), a special tag can be attached to the header. This header allows Dynatrace to correlate actions with a server-side PurePath. An example is shown below.

// create URL and open URLConnection
URL url = new URL("http://www.my-backend.com/api/v3/users");
URLConnection urlConnection = url.openConnection();

// create the WebRequestTracer
WebRequestTracer webRequestTracer = action.traceWebRequest(urlConnection);
webRequestTracer.start();

// consume data
BufferedReader in = new BufferedReader(new InputStreamReader(uc.getInputStream()));
String inputLine;
while ((inputLine = in.readLine()) != null) {
    // TODO - do something useful with response
}
in.close();

// stop web request tracing when done
webRequestTracer.setResponseCode(200); // would use the HTTP response code normally.
webRequestTracer.stop();

// --------------------------------------------
// alternative solution not using URLConnection
// --------------------------------------------

String url = "http://www.my-backend.com/api/v3/users";

// create the WebRequestTracer
WebRequestTracer webRequestTracer = action.traceWebRequest(url);

// this is the HTTP header name & value which needs to be added to the HTTP request.
String headerName = OpenKitConstants.WEBREQUEST_TAG_HEADER;
String headerValue = webRequestTracer.getTag();

webRequestTracer.start();

// perform the request here & do not forget to add the HTTP header

webRequestTracer.setBytesSent(12345);     // 12345 bytes sent
webRequestTracer.setBytesReceived(67890); // 67890 bytes received
webRequestTracer.setResponseCode(200);    // 200 was the response code
webRequestTracer.stop();

string url = "http://www.my-backend.com/api/v3/users";

// create the WebRequestTracer
IWebRequestTracer webRequestTracer = action.TraceWebRequest(url);

// this is the HTTP header name & value which needs to be added to the HTTP request.
string headerName = OpenKitConstants.WEBREQUEST_TAG_HEADER;
string headerValue = webRequestTracer.Tag;

// perform the request here & do not forget to add the HTTP header
using (HttpClient httpClient = new HttpClient()) {

    // start timing
    webRequestTracer.Start();

    // set the tag
    httpClient.DefaultRequestHeaders.Add(headerName, headerValue);

    // ... perform the request and process the response ...

    // set metadata
    webRequestTracer.SetBytesSent(12345);     // 12345 bytes sent
    webRequestTracer.SetBytesReceived(67890); // 67890 bytes received
    webRequestTracer.SetResponseCode(200);    // 200 was the response code

    // stop timing
    webRequestTracer.Stop();
}

When an OpenKit instance is no longer needed (for example, when the application using OpenKit is shut down), the obtained instance can be cleared by invoking. A call to shutdown blocks the calling thread up to 10 seconds, while the OpenKit flushes data which hasn't been transmitted yet to the backend.

openKit.shutdown();

openKit.Shutdown();