Specifying Records

The instrumentation record language (IRL) uses an object-oriented paradigm based on two main elements, records, which we call entities, and templates, which are not storable types. Records and templates both allow to comprise properties of primitive and array types. The array feature is experimental and not officially supported by Kieker. To share properties entities can inherit one parent entity type and in addition multiple templates. Templates can only inherit other templates. It is not allowed to define cyclic dependencies, however, the dependency graph for templates can be a complete directed cycle free graph.

Lets start to define a simple entity. We want to define an entity to collect entry level calls. An entry level call is an invocation of a system operation from outside. Depending on the technology, this can be a web service call, an RPC call, or any other type of exposed API. For our example lets assume we want to limit that to web-services.

package org.example.entry

entity EntryCall {
   string session = "<no session>"
   long entryTime
   long exitTime
   string operationSignature = "<no operation>"
   string componentSignature = "<no component>"
}

In this example, we have defined five properties representing the session id, the entry and exit time, the called operation, and the component where the operation belongs to. The string properties all have attached primitive constants, which are automatically applied when they are not initialized during monitoring. The IRL provides as usual set of types which are boolean, byte, short, char, int, long, float, double, and string. In future it will most likely support time, which will be mapped internally to long in Java, but might use other relationships in other languages.

It is also possible to specify constants for numerical values, however, they might not be passed as null values. Constants can be helpful to programmers to label special values. Therefore, we support this feature. Lets add an entry for payload size.

entity EntryCall {
   string session = "<no session">
   long entryTime
   long exitTime
   string operationSignature = "<no operation>"
   string componentSignature = "<no component>"
   long payloadSize = 0
}

In Java and C this would automatically result in an constant named PAYLOAD_SIZE and ENTRY_CALL_PAYLOAD_SIZE, respectively. However, it is not directly visible in the entity definition. Therefore, constants con also be specified explicitly.

entity EntryCall {
   const long PAYLOAD_SIZE = 0
   string session = "<no session">
   long entryTime
   long exitTime
   string operationSignature = "<no operation>"
   string componentSignature = "<no component>"
   long payloadSize
}

As Kieker and the IRL support different technologies and languages, this entity type might not cover all potential types of remote calls. For example, there could be state less interfaces, which no not know anything about sessions. Or in other contexts might be important to get additional values, e.g., the hostname and the geo location. In these cases is would be helpful to specify only the difference in special entities, while the common properties are described together.

template EntryCall {
   const long PAYLOAD_SIZE = 0
   long entryTime
   long exitTime
   long payloadSize
}

entity EJBEntryCall : EntryCall {
   string operationSignature = "<no operation>"
   string componentSignature = "<no component>"
   string session = "<no session>"
}

entity RPCEntityCall : EntryCall {
   string remoteHost // this means a value must be specified
   int port
}

template GeoLocation {
   int countryId
}

entity CloudEJBEntryCall extends CloudEJBEntryCall : GeoLocation 

entity WebService : EntryCall, GenoLocation {
   string operationSignature = "<no operation>"
   string componentSignature = "<no component>"
   string session = "<no session>"
}

The last two entities show how entities can inherit from both parent (super) types and templates. And how to specify multiple templates. The language also supports an import declaration similar to Java and Xtend, which allows to distribute types in different packages.

package org.example

import org.example.calls.EntryCall

entity EJBEntryCall : EntryCall {
   string operationSignature = "<no operation>"
   string componentSignature = "<no component>"
   string session = "<no session>"
}

In the last example, the EntryCall is imported from another file.