com.dynatrace.oneagent.sdk.api
Interface OneAgentSDK


public interface OneAgentSDK

Root interface contains provided Agent SDK API calls. Basically the whole API is designed according to following rules:

Single API calls might differ from that rules. Those rules are explicitly documented.


Field Summary
static java.lang.String DYNATRACE_HTTP_HEADERNAME
          Using this headername to transport Dynatrace tag inside an outgoing http request ensures compatibility to Dynatrace built-in sensors.
 
Method Summary
 void addCustomRequestAttribute(java.lang.String key, double value)
          Does exactly the same as addCustomRequestAttribute(String, String), but request-attribute type double.
 void addCustomRequestAttribute(java.lang.String key, long value)
          Does exactly the same as addCustomRequestAttribute(String, String), but request-attribute type long.
 void addCustomRequestAttribute(java.lang.String key, java.lang.String value)
          Adds a custom request attribute to currently traced service call.
 InProcessLink createInProcessLink()
          Creates a link for in-process-linking.
 WebApplicationInfo createWebApplicationInfo(java.lang.String webServerName, java.lang.String applicationID, java.lang.String contextRoot)
          Initializes a WebApplicationInfo instance that is required for tracing incoming web requests.
 SDKState getCurrentState()
          Returns the current SDKState.
 void setLoggingCallback(LoggingCallback loggingCallback)
          Installs a callback that gets informed, if any SDK action has failed.
 IncomingRemoteCallTracer traceIncomingRemoteCall(java.lang.String serviceMethod, java.lang.String serviceName, java.lang.String serviceEndpoint)
          Traces an incoming remote call.
 IncomingWebRequestTracer traceIncomingWebRequest(WebApplicationInfo webApplicationInfo, java.lang.String url, java.lang.String method)
          Traces an incoming web request.
 InProcessLinkTracer traceInProcessLink(InProcessLink inProcessLink)
          Traces the start of in-process-linking.
 OutgoingRemoteCallTracer traceOutgoingRemoteCall(java.lang.String serviceMethod, java.lang.String serviceName, java.lang.String serviceEndpoint, ChannelType channelType, java.lang.String channelEndpoint)
          Traces an outgoing remote call.
 OutgoingWebRequestTracer traceOutgoingWebRequest(java.lang.String url, java.lang.String method)
          Traces an outgoing web request.
 

Field Detail

DYNATRACE_HTTP_HEADERNAME

static final java.lang.String DYNATRACE_HTTP_HEADERNAME
Using this headername to transport Dynatrace tag inside an outgoing http request ensures compatibility to Dynatrace built-in sensors.

See Also:
Constant Field Values
Method Detail

createWebApplicationInfo

WebApplicationInfo createWebApplicationInfo(java.lang.String webServerName,
                                            java.lang.String applicationID,
                                            java.lang.String contextRoot)
Initializes a WebApplicationInfo instance that is required for tracing incoming web requests. This information determines the identity and name of the resulting Web Request service in dynatrace. Also see https://www.dynatrace.com/support/help/server-side-services/introduction/how-does-dynatrace-detect-and-name-services/#web-request-services for detail description of the meaning of the parameters.

Parameters:
webServerName - logical name of the web server. In case of a cluster every node in the cluster must report the same name here. Attention: Make sure not to use the host header for this parameter. Host headers are often spoofed and contain things like google or baidoo which do not reflect your setup.
applicationID - application ID of the web application
contextRoot - context root of the application. All URLs traced with the returned WebApplicationInfo, should start with provided context root.
Returns:
WebApplicationInfo instance to work with
Since:
1.3

traceIncomingWebRequest

IncomingWebRequestTracer traceIncomingWebRequest(WebApplicationInfo webApplicationInfo,
                                                 java.lang.String url,
                                                 java.lang.String method)
Traces an incoming web request.

Parameters:
webApplicationInfo - information about web application
url - (parts of a) URL, which will be parsed into: scheme, hostname/port, path & query Note: the hostname will be resolved by the Agent at start() call
method - HTTP request method
Returns:
IncomingWebRequestTracer to work with
Since:
1.3

traceOutgoingWebRequest

OutgoingWebRequestTracer traceOutgoingWebRequest(java.lang.String url,
                                                 java.lang.String method)
Traces an outgoing web request.

Parameters:
url - URL, which will be parsed into: scheme, hostname/port, path & query Note: the hostname will be resolved by the Agent at start() call
method - HTTP request method
Returns:
OutgoingWebRequestTracer to work with
Since:
1.4

traceIncomingRemoteCall

IncomingRemoteCallTracer traceIncomingRemoteCall(java.lang.String serviceMethod,
                                                 java.lang.String serviceName,
                                                 java.lang.String serviceEndpoint)
Traces an incoming remote call.

Parameters:
serviceMethod - name of the called remote method. (required)
serviceName - name of the remote service. (required)
serviceEndpoint - endpoint on the server side. (required)
Returns:
IncomingRemoteCallTracer instance to work with
Since:
1.0

traceOutgoingRemoteCall

OutgoingRemoteCallTracer traceOutgoingRemoteCall(java.lang.String serviceMethod,
                                                 java.lang.String serviceName,
                                                 java.lang.String serviceEndpoint,
                                                 ChannelType channelType,
                                                 java.lang.String channelEndpoint)
Traces an outgoing remote call.

Parameters:
serviceMethod - name of the called remote method. (required)
serviceName - name of the remote service. (required)
serviceEndpoint - endpoint on the server side. (required)
channelType - communication protocol used by remote call. See ChannelType for available types. (required)
channelEndpoint - optional and depending on channelType:
  • for TCP/IP: host name/IP of the server-side (can include port)
  • for UNIX domain sockets: path of domain socket file
  • for named pipes: name of pipe
Returns:
OutgoingRemoteCallTracer instance to work with
Since:
1.0

createInProcessLink

InProcessLink createInProcessLink()
Creates a link for in-process-linking.

Returns:
InProcessLink instance to work with. Use it with traceInProcessLink(InProcessLink)
Since:
1.1

traceInProcessLink

InProcessLinkTracer traceInProcessLink(InProcessLink inProcessLink)
Traces the start of in-process-linking.

Parameters:
inProcessLink - a InProcessLink received via createInProcessLink()
Returns:
InProcessLinkTracer to work with.
Since:
1.1

addCustomRequestAttribute

void addCustomRequestAttribute(java.lang.String key,
                               java.lang.String value)
Adds a custom request attribute to currently traced service call. Might be called multiple times, to add more than one attribute. Check via setLoggingCallback(LoggingCallback) if error happened. If two attributes with same key are set, both attribute-values are captured.

Parameters:
key - key of the attribute. required parameter.
value - value of the attribute. required parameter.
Since:
1.2

addCustomRequestAttribute

void addCustomRequestAttribute(java.lang.String key,
                               long value)
Does exactly the same as addCustomRequestAttribute(String, String), but request-attribute type long.

Since:
1.2

addCustomRequestAttribute

void addCustomRequestAttribute(java.lang.String key,
                               double value)
Does exactly the same as addCustomRequestAttribute(String, String), but request-attribute type double.

Since:
1.2

setLoggingCallback

void setLoggingCallback(LoggingCallback loggingCallback)
Installs a callback that gets informed, if any SDK action has failed. For details see LoggingCallback interface. The provided callback must be thread-safe, when using this OneAgentSDK instance in multi-threaded environments.

Parameters:
loggingCallback - may be null, to remove current callback. provided callback replaces any previously set callback.
Since:
1.0

getCurrentState

SDKState getCurrentState()
Returns the current SDKState. See SDKState for details.

Returns:
current state - never null.
Since:
1.0