Dynatrace OpenKit API methods

Dynatrace OpenKit offers a number of API methods that enable you to integrate OpenKit into your application. The sections below describe how to use each of these OpenKit methods.

Obtain an OpenKit instance

To obtain a new OpenKit instance, use DynatraceOpenKitBuilder.

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

SSL/TLS security

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. You can configure a custom trust manager using the builder.

Enable verbose logging

By default, OpenKit uses a logger implementation that logs to stdout. If the default logger is used, you can enable verbose logging via DynatraceOpenKitBuilder. When the verbose mode is enabled, info and debug messages are logged.

You can also configure a custom logger. For details, see Dynatrace OpenKit logging.

Initialize OpenKit

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 you need 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 applications, OpenKit allows to wait for the initialization in two ways:

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

Create a session

You can create a new session using the OpenKit instance obtained from the builder. When creating a new session, you can also provide an IP address.

Tag specific users

You can tag the user assigned to a session. This enables you to search and filter specific user sessions and analyze individual user behavior over time in the backend. See User tagging for more details.

Finish a session

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

Report a crash

You can report unexpected application crashes on a session. The crash details are sent immediately after you've reported a crash.

Create custom and child actions

You can define and report custom actions. After you create a custom action, you can add a child action to it or enhance an action with additional information before finally closing it. You should create custom actions from a session and child actions from a custom action.

There's no limit on the number of child actions attached to a custom action. However, note that you can have only one level of child actions—you can't create a child action for another child action (child actions can't have their own child actions). Also, refer to User session structure for individual user.

Child actions are not displayed on the user session details page, but you can view them on the waterfall analysis page for a custom action to which these child actions are attached.

End an action

To record accurate timing information for actions, you should leave actions once they're finished.

Cancel an action

Canceling an action is similar to leaving an action, except that the action is discarded and is not sent to Dynatrace. Open child objects, like child actions and web request tracers, are discarded as well. Child objects that have been closed previously are sent to the backend and might be processed, depending on the event type.

Report an event

You can report named events on actions.

Report a value

The reportValue method allows you to report key-value pairs of metadata that you can later view in the Dynatrace web UI and convert into user action and user session properties. The reported values must be part of a user action.

You can report values of the following data types:

To view the reported values in Dynatrace, go to the details of the user action that should contain that metadata and scroll down to the Reported values section.

To add action and session properties based on the reported values and then use these properties to create powerful queries, segmentations, and aggregations, see Define user action and user session properties for custom applications.

Report an error

You can report an error including its name (errorName) and error code (errorCode).

You can also report the following additional information on the error:

The code snippet below shows how to report errors with additional information.

OpenKit Java and OpenKit .NET offer a convenience API to directly report caught exceptions, as demonstrated in the example below.

Report a business event

Dynatrace SaaS version 1.253+

With sendBizEvent, you can report business events. These are standalone events, as Dynatrace sends them separately from user actions or user sessions.

Business events are only captured for monitored sessions. When OpenKit isn't initialized or a session is excluded from monitoring due to cost and traffic control, business events are not reported for such sessions. Note that this behavior might be subject to change in the future, potentially allowing business events to be sent to Dynatrace regardless of session monitoring.

For additional details on business events, refer to Business Analytics.

Trace web requests

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

Configure data privacy

You can dynamically adjust data privacy settings and build your custom applications in compliance with data protection laws and regulations. The privacy API methods allow you to dynamically change the data collection level and activate or deactivate crash reporting.

Data collection levels

The table below describes the available data collection levels and shows whether user tags and custom user actions, events, values, and errors are reported for a particular level.

Crash reporting levels

The following crash reporting levels are available.

Set data collection and crash reporting levels

The code examples below show you how to work with the API:

Terminate an OpenKit instance

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