The Common Trace API (CTA) is an interface-based specification of a common trace representation to allow a monitoring-tool-format-independent access of trace data. The CTA supports the exchange of monitoring data between stakeholders (e.g., Ops and Dev, or different research groups) while the consumer accesses the data with the CTA.
Implementations of the CTA can be tool- and case-specific. However the following points should be considered:
- The target application that uses the trace data provided by a certain monitoring tool needs access to the specific implementation (i.e. Java Classes) of the CTA.
- Whether a certain CTA implementation directly contains all trace information within the implementation objects, or whether the CTA implementation uses lazy loading to calculate the information from a third source is up to the implementation. However, in the case when trace data is (CTA Implementation objects) are transferred remotely, lazy loading may become a problem as the underlying data source may be gone. This needs to be kept in mind when providing implementations for the CTA.
A trace that traverses multiple locations is divided into subtraces. Hence, a subtrace is identified by the Location tuple (Host (e.g. IP), Container(e.g. JVM Id), Application Id, Business Transaction Id). Subtraces are structured along a composite pattern (tree structure). In this way, subtraces provide a coarse-frained view on the logical trace. A subtrace, in turn, contains a tree of Callables, hence, a trace covering one Location.
| Operation | Return Type | Description | Notes / Uncertainties |
|---|---|---|---|
| Trace | |||
| getLogicalTraceId() | long | returns the identifier of the entire logical trace (encapsulating all subtraces that belong to the logical trace) | |
| getRoot() | SubTrace | returns the root of the subtrace composite structure. This is usually the entry point to the application. | |
| maxDepth() | long | the maximum depth of the sub trace | |
| size() | long | the number of nodes (i.e. Callables) in the tree structure of the corresponding sub trace | |
| subTraceIterator() | java.lang.Iterator<SubTrace> | returns an iterator on the tree structure of the sub traces | |
| SubTrace | |||
| getRoot() | Callable | returns the root Callable of the sub trace (i.e. operation that represents the root of the call tree) | |
| getParent() | SubTrace | returns the parent sub trace within the composite (i.e. tree) structure of sub traces. Returns null if no parent exists. | |
| getSubTraces() | List<SubTrace> | returns the child sub traces within the composite (i.e. tree) structure of sub traces. Returns an emty list if no sub traces exist. | |
| getLocation() | Location | returns the unique location of the sub trace (in particular: two operation executions with different locations belong to different sub traces) | |
| getContainingTrace() | Trace | returns the Trace that contains this SubTrace | |
| getId() | long | unique identifier of the sub trace | |
| maxDepth() | long | the maximum depth of the sub trace | |
| size() | long | the number of nodes (i.e. Callables) in the tree structure of the corresponding sub trace | |
| Location | |||
| getHost() | String | host name or IP of the corresponding system node where the underlying sub trace has been executed | |
| getRuntimeEnvironment() | String | identifier of the run-time container (in Java: JVM, in .NET: CLR, etc.) | |
| getApplication() | String | identifier of the application the sub trace belongs to | |
| getBusinessTransaction() | String | identifier of the business transaction a sub trace belongs to | |
| Callable | |||
| getParent() | Callable | returns the parent callable of the current callable within the tree structure of the corresponding sub trace. If the current callable is the root of the current sub trace that has been called by another sub trace then this method returns the TraceInvocation instance of the (other) calling sub trace. If the current callable is a root and the current sub trace is a root of the entire logical trace then this method returns null. | |
| getCallees() | List<Callable> | returns a list of all callables invoked by the current callable. The list contains the callables in the order they have been called. | |
| getContainingSubTrace() | SubTrace | returns the SubTrace this Callable belongs to | |
| getSignature() | String | full qualified signature of the corresponding operation (including all full-qualified types of the parameters)(e.g. for method "org.my.Class.myMethod(org.my.Parameter)" would return "org.my.Class.myMethod(org.my.Parameter)") | |
| getSimpleName() | String | simple name of the corresponding method (e.g. for method "org.my.Class.myMethod(org.my.Parameter)" would return "myMethod") | |
| getFullName() | String | full name of the corresponding method including package name (e.g. for method "org.my.Class.myMethod(org.my.Parameter)" would return "org.my.Class.myMethod") | |
| getExecutionTime() | long | operation duration in ms | |
| getEntryTime() | long | entry timestamp in ms | |
| getExitTime() | long | exit timestamp in ms | |
| getLables() | List<String> | returns a list of labels (lables convey simple additional information) | e.g. "Servlet", "Hibernate", "Invoice", etc. |
| hasLabel(String label) | boolean | checks whether the Callable is labled with the given value | |
| int | returns a bit-encoded integer providing the information about used modifiers | shell we leave this information here, or move it to CTA AIC (additional information part). Rationale: this information might be not language independent, at least the encoding of the returned integer | |
| isConstructor() | boolean | returns true if this callable is a constructor | do we need this method? do we need other analogous helper methods? |
| getPosition() | long | returns the position (i.e. index) of this Callable in the corresponding SubTrace. The order of the indexes is analgous to the original execution order of the Callables. The root element of the corresponding SubTrace has an index of 0. | |
| getDepth() | long | returns the depth of this Callable relative to the root of the correspoding SubTrace. The root has a depth of 0. | |
| getAdditionalInformation() | List<AdditionalInformation> | returns a list of all additional information objects | |
| getAdditionalInformation(java.lang.Class<T extends AdditionalInformation> type) | List<T> | returns a list of all additional information objects of the provided type | |
| TraceInvocation | |||
| getTargetTrace() | SubTrace | returns the sub trace that has been invoked by this trace invocation node | |
| isSync() | boolean | returns true, if the current sub trace blocks while the invoked sub trace is executing | |
| getCallees() // inherited | List<Callable> | returns a list with only ONE element containing the root of the invoked trace | |
| getSignature() // inherited | String | returns the signature of the root element of the invoked trace | |