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:

• API calls never throw any exception
• API calls never return null values. e. g. they returning NOOP Objects in case of any issue or required parameters are null.

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.
static java.lang.String	DYNATRACE_MESSAGE_PROPERTYNAME Using this propertyname to transport Dynatrace tag along with the message, 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.
DatabaseInfo	createDatabaseInfo(java.lang.String name, java.lang.String vendor, ChannelType channelType, java.lang.String channelEndpoint) Initializes a DatabaseInfo instance that is required for tracing database requests.
InProcessLink	createInProcessLink() Creates a link for in-process-linking.
MessagingSystemInfo	createMessagingSystemInfo(java.lang.String vendorName, java.lang.String destinationName, MessageDestinationType destinationType, ChannelType channelType, java.lang.String channelEndpoint) Initializes a MessagingSystemInfo instance that is required for tracing messages.
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.
TraceContextInfo	getTraceContextInfo() Returns the current W3C trace context for log enrichment (not meant for tagging and context-propagation but for log-enrichment).
void	setLoggingCallback(LoggingCallback loggingCallback) Installs a callback that gets informed, if any SDK action has failed.
CustomServiceTracer	traceCustomService(java.lang.String serviceMethod, java.lang.String serviceName) Creates a tracer for a custom transaction (Dynatrace calls them Custom service).
IncomingMessageProcessTracer	traceIncomingMessageProcess(MessagingSystemInfo messagingSystem) Creates a tracer for processing (consuming) a received message (onMessage).
IncomingMessageReceiveTracer	traceIncomingMessageReceive(MessagingSystemInfo messagingSystem) Creates a tracer for an incoming asynchronous message (blocking receive).
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.
OutgoingMessageTracer	traceOutgoingMessage(MessagingSystemInfo messagingSystem) Creates a tracer for an outgoing asynchronous message (send).
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.
DatabaseRequestTracer	traceSqlDatabaseRequest(DatabaseInfo databaseInfo, java.lang.String statement) Creates a tracer for tracing outgoing SQL database requests.

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

DYNATRACE_MESSAGE_PROPERTYNAME

static final java.lang.String DYNATRACE_MESSAGE_PROPERTYNAME

Using this propertyname to transport Dynatrace tag along with the message, ensures compatibility to Dynatrace built-in sensors.

See Also:

Constant Field Values

Method Detail

createDatabaseInfo

DatabaseInfo createDatabaseInfo(java.lang.String name,
                                java.lang.String vendor,
                                ChannelType channelType,
                                java.lang.String channelEndpoint)

Initializes a DatabaseInfo instance that is required for tracing database requests.

Parameters:

name - name of the database

vendor - database vendor name (e.g. Oracle, MySQL, ...), can be a user defined name If possible use a constant defined in DatabaseVendor

channelType - communication protocol used to communicate with the database.

channelEndpoint - this represents the communication endpoint for the database. This information allows Dynatrace to tie the database requests to a specific process or cloud service. It is optional. * for TCP/IP: host name/IP of the server-side (can include port in the form of "host:port") * for UNIX domain sockets: name of domain socket file * for named pipes: name of pipe

Returns:

DatabaseInfo instance to work with

Since:

1.7.0

traceSqlDatabaseRequest

DatabaseRequestTracer traceSqlDatabaseRequest(DatabaseInfo databaseInfo,
                                              java.lang.String statement)

Creates a tracer for tracing outgoing SQL database requests.

Parameters:

databaseInfo - information about database

statement - database SQL statement

Returns:

DatabaseRequestTracer to work with

Since:

1.7.0

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

createMessagingSystemInfo

MessagingSystemInfo createMessagingSystemInfo(java.lang.String vendorName,
                                              java.lang.String destinationName,
                                              MessageDestinationType destinationType,
                                              ChannelType channelType,
                                              java.lang.String channelEndpoint)

Initializes a MessagingSystemInfo instance that is required for tracing messages.

Parameters:

vendorName - one of MessageSystemVendor if well known vendor. Custom provided in any other case.

destinationName - destination name (e.g. queue name, topic name)

destinationType - destination type - see MessageDestinationType.

channelType - communication protocol used

channelEndpoint - optional and depending on protocol: * for TCP/IP: host name/IP of the server-side (can include port) * for UNIX domain sockets: name of domain socket file * for named pipes: name of pipe

Returns:

MessagingSystemInfo instance to work with

Since:

1.5

traceOutgoingMessage

OutgoingMessageTracer traceOutgoingMessage(MessagingSystemInfo messagingSystem)

Creates a tracer for an outgoing asynchronous message (send).

Parameters:

messagingSystem - information about the messaging system (see createMessagingSystemInfo methods).

Returns:

OutgoingMessageTracer to work with

Since:

1.5

traceIncomingMessageReceive

IncomingMessageReceiveTracer traceIncomingMessageReceive(MessagingSystemInfo messagingSystem)

Creates a tracer for an incoming asynchronous message (blocking receive).

Parameters:

messagingSystem - information about the messaging system (see createMessagingSystemInfo methods).

Returns:

IncomingMessageReceiveTracer to work with

Since:

1.5

traceIncomingMessageProcess

IncomingMessageProcessTracer traceIncomingMessageProcess(MessagingSystemInfo messagingSystem)

Creates a tracer for processing (consuming) a received message (onMessage).

Parameters:

messagingSystem - information about the messaging system (see createMessagingSystemInfo methods).

Returns:

IncomingMessageProcessTracer to work with

Since:

1.5

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

traceCustomService

CustomServiceTracer traceCustomService(java.lang.String serviceMethod,
                                       java.lang.String serviceName)

Creates a tracer for a custom transaction (Dynatrace calls them Custom service). Used whenever a transaction should be traced, that does not match any of the specialised transaction types (e. g. DB-request, webrequest, ...).

Parameters:

serviceMethod - service method being used for service creation.

serviceName - service name being used for service creation.

Returns:

CustomServiceTracer to work with

Since:

1.8

getTraceContextInfo

TraceContextInfo getTraceContextInfo()

Returns the current W3C trace context for log enrichment (not meant for tagging and context-propagation but for log-enrichment). See TraceContextInfo for details.

Returns:

current trace context at the time of the call - never null (but may contain all-zero ID).

Since:

1.9