Dynatrace OpenKit - JavaScript Reference Implementation

!Build Status

:information_source: We changed the default branch name to main. You can find the necessary steps to update your local clone on Scott Hanselman's Blog.
We encourage you to rename the default branch in your forks too.

What is the OpenKit?

The OpenKit provides an easy and lightweight way to get insights into applications with Dynatrace by instrumenting the source code of those applications.

It is best suited for applications running separated from their backend and communicating via HTTP, like rich-client-applications, embedded devices, terminals, and so on.

The big advantages of the OpenKit are that it's designed to

- be as easy-to-use as possible
- be as dependency-free as possible (no third party libraries or Dynatrace Agent needed)
- be easily portable to other languages and platforms

This repository contains the reference implementation in pure TypeScript. Other implementations are listed as follows:

- .NET: https://github.com/Dynatrace/openkit-dotnet/
- Java: https://github.com/Dynatrace/openkit-java/
- C/C++: https://github.com/Dynatrace/openkit-native/

What you can do with the OpenKit-JavaScript

- Create Sessions and User Actions
- Identify users on sessions
- Report values on actions
- Use it together with Dynatrace
- Trace web requests to server-side PurePaths

What you cannot do with the OpenKit

- Create server-side PurePaths (this functionality is provided by OneAgent SDKs)
- Create metrics (use the Custom network devices & metrics API to report metrics)

Design Principles

- API should be as simple and easy-to-understand as possible
- Incorrect usage of the OpenKit should still lead to valid results, if possible
- Design reentrant APIs and document them

Runtime requirements

$3

Promises are required for OpenKit to work at all. If your environment does not support them, they can be
polyfilled using a polyfill library.

$3

If you use a platform without fetch or node.js lower than 18, you have to either polyfill
the fetch API, or provide your own CommunicationChannel implementation, which can use the protocol
you want (e.g. MQTT).

Obtaining OpenKit from npm

OpenKit is available on npm and should be used via npm or yarn.

For browsers a mirroring service like jsDelivr can be used.

``html
type="text/javascript"
src="https://cdn.jsdelivr.net/npm/@dynatrace/openkit-js@1.0.2/dist/browser/openkit.js"
>
`

Contribution & Development

See contribution.md and development.md.

General Concepts

In this part the concepts used throughout OpenKit are explained. A short sample how to use OpenKit is
also provided. For detailed code samples have a look into example.md and the code documentation.

$3

An OpenKitBuilder instance is responsible for getting and setting application relevant information, e.g.
the application's version and device specific information.

$3

The OpenKit is responsible for creating user sessions (see Session).

Although it would be possible to have multiple OpenKit instances connected to the same endpoint
within one process, there should be one unique instance.

$3

A Session represents kind of a user session, similar to a browser session in a web application.
However the application developer is free to choose how to treat a Session.
The Session is used to create Action instances, report application crashes, identify users and
to trace web requests when there is no Action available.

When a Session is no longer required, it's highly recommended to end it, using the Session.end() method.

$3

The Action are named hierarchical nodes for timing and attaching further details.
An Action is created from the Session. Actions provide the possibility to attach key-value pairs,
named events and errors, and can be used for tracing web requests.

$3

When the application developer wants to trace a web request, which is served by a service
instrumented by Dynatrace, a WebRequestTracer should be used, which can be
requested from an Action and Session.

$3

A named Event is attached to an Action and contains a name.

$3

For an Action key-value pairs can also be reported. The key is always a String
and the value may be a number or a string. All reported numbers are handled as floating point
values by Dynatrace.

$3

Errors are a way to report an erroneous condition on an Action.
Crashes are used to report (unhandled) exceptions on a Session.

$3

OpenKit enables you to tag sessions with unique user tags. The user tag is a String
that allows to uniquely identify a single user.

Example

This small example provides a rough overview how OpenKit can be used.
Detailed explanation is available in example.md.

`javascript
const applicationID = 'application-id';
const deviceID = 42;
const endpointURL = 'https://tenantid.beaconurl.com/mbeacon';

const openKit = new OpenKitBuilder(endpointURL, applicationID, deviceID)
.withApplicationVersion('1.0.0.0')
.withOperatingSystem('Windows 10')
.withManufacturer('MyCompany')
.withModelId('MyModelId')
.build();

const timeoutInMilliseconds = 10 * 1000;

openKit.waitForInit((success) => {
if (success) {
const clientIP = '8.8.8.8';
const session = openKit.createSession(clientIP);

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

const actionName = 'rootActionName';
const action = session.enterAction(actionName);

action.leaveAction();
session.end();
openKit.shutdown();
}
}, timeoutInMilliseconds);
``