com.newrelic.api.agent

Interface Transaction

public interface Transaction

A transaction represents a unit of work in an application. It may be a single web request or a scheduled background task. To indicate that a method is the starting point of a transaction, mark it with a Trace annotation and set Trace.dispatcher() to true.

Custom Transport Channel API

Use this API to implement cross application tracing support for a transport not supported by New Relic, such as a proprietary RPC transport.

Example:

Server A	Server B
String requestMetadata = NewRelic.getAgent().getTransaction().getRequestMetadata(); // send request containing requestMetadata to Server B.
	// read request metadata sent by Server A. NewRelic.getAgent().getTransaction().processRequestMetadata(requestMetadata);
	// right before responding to Server A's request: String responseMetadata = NewRelic.getAgent().getTransaction().getResponseMetadata(); // send response containing responseMetadata to Server A.
// read response metadata sent by Server B. NewRelic.getAgent().getTransaction().processResponseMetadata(responseMetadata);

Note: not all transports support a response. In these cases, responses are optional.

See Also:

Agent.getTransaction(), Trace.dispatcher()

Method Summary

Methods

Modifier and Type	Method and Description
void	addOutboundResponseHeaders() Instruct the transaction to write the outbound response headers.
void	convertToWebTransaction() Turns the current transaction from a background transaction into a web transaction.
TracedMethod	getLastTracer() Deprecated. use getTracedMethod().
java.lang.String	getRequestMetadata() Get transaction metadata to include in an outbound call.
java.lang.String	getResponseMetadata() Get transaction metadata to include in an outbound response.
TracedMethod	getTracedMethod() Returns the TracedMethod enclosing the caller.
void	ignore() Ignore this transaction so that none of its data is reported to the New Relic service.
void	ignoreApdex() Ignore the current transaction for calculating Apdex score.
boolean	isTransactionNameSet() Returns true if the transaction name has been set.
boolean	isWebTransaction() Returns true if in a web transaction.
boolean	markResponseSent() Marks the time when the last byte of the response left the server as the current timestamp.
void	processRequestMetadata(java.lang.String requestMetadata) Provide the metadata string from a remote transaction's call to getRequestMetadata() to the current transaction.
void	processResponseMetadata(java.lang.String responseMetadata) Provide the metadata string from a remote transaction's call to getResponseMetadata() to the current transaction.
void	processResponseMetadata(java.lang.String responseMetadata, java.net.URI uri) Provide the metadata string from a remote transaction's call to getResponseMetadata() to the current transaction.
boolean	setTransactionName(TransactionNamePriority namePriority, boolean override, java.lang.String category, java.lang.String... parts) Sets the current transaction's name using the given priority.
void	setWebRequest(ExtendedRequest request) Web Frameworks API ******************************** /** Sets the request for the current transaction.
void	setWebResponse(Response response) Sets the response for the current transaction.

Method Detail

setTransactionName

boolean setTransactionName(TransactionNamePriority namePriority,
                         boolean override,
                         java.lang.String category,
                         java.lang.String... parts)

Sets the current transaction's name using the given priority. Higher priority levels are given precedence, and if the name is set many times with the same priority, the first call wins unless override is true.

Parameters:

namePriority - The priority of the new transaction name.

override - Overrides the current transaction name if it has the same priority level (or lower).

category - The type of transaction. This is the second segment of the full transaction metric name.

parts - The category and all of the parts are concatenated together with / characters to create the full name.

Returns:

Returns true if the transaction name was successfully changed, else false.

Since:

3.9.0

isTransactionNameSet

boolean isTransactionNameSet()

Returns true if the transaction name has been set. This method is inherently unreliable in the presence of transactions with multiple threads, because another thread may set the transaction name after this method returns but before the caller can act on the return value.

Returns:

True if the transaction name has already been set, else false.

Since:

3.9.0

getLastTracer

@Deprecated
TracedMethod getLastTracer()

Deprecated. use getTracedMethod().

Returns this transaction's last tracer.

Since:

3.9.0

getTracedMethod

TracedMethod getTracedMethod()

Returns the TracedMethod enclosing the caller.

Returns:

The TracedMethod enclosing the caller. The return value is null if the caller is not within a transaction.

Since:

3.9.0

ignore

void ignore()

Ignore this transaction so that none of its data is reported to the New Relic service.

Since:

3.9.0

ignoreApdex

void ignoreApdex()

Ignore the current transaction for calculating Apdex score.

Since:

3.9.0

getRequestMetadata

java.lang.String getRequestMetadata()

Get transaction metadata to include in an outbound call. Use this method when implementing cross application tracing support for a transport not supported by New Relic, such as a proprietary RPC transport.

Server A

String requestMetadata = NewRelic.getAgent().getTransaction().getRequestMetadata();

...send requestMetadata to Server B as part of an outbound call.

Returns:

A string representation of the metadata required for linking this transaction to a remote child transaction, or null if no metadata should be sent.

Since:

3.16.1

processRequestMetadata

void processRequestMetadata(java.lang.String requestMetadata)

Provide the metadata string from a remote transaction's call to getRequestMetadata() to the current transaction. Use this method when implementing cross application tracing support for a transport not supported by New Relic, such as a proprietary RPC transport.

Server B

... get requestMetadata from request.

NewRelic.getAgent().getTransaction().processRequestMetadata(requestMetadata);

Parameters:

requestMetadata - metadata string received from an inbound request.

Since:

3.16.1

getResponseMetadata

java.lang.String getResponseMetadata()

Get transaction metadata to include in an outbound response. Use this method when implementing cross application tracing support for a transport not supported by New Relic, such as a proprietary RPC transport.

This call is time sensitive and should be made as close as possible to the code that writes the response.

Server B

String responseMetadata = NewRelic.getAgent().getTransaction.getResponseMetadata();

... send response containing responseMetadata to server A.

Returns:

A string representation of the metadata required when responding to a remote transaction's call, or null if no metadata should be sent.

Since:

3.16.1

processResponseMetadata

void processResponseMetadata(java.lang.String responseMetadata)

Provide the metadata string from a remote transaction's call to getResponseMetadata() to the current transaction. This should only be called on the originating transaction when processing response to a remote call. Use this method when implementing cross application tracing support for a transport not supported by New Relic, such as a proprietary RPC transport.

Server A

... get response containing responseMetadata from call to server B.

NewRelic.getAgent().getTransaction().processResponseMetadata(responseMetadata); If a URI is available, please use processResponseMetadata(String, URI).

Parameters:

responseMetadata - metadata string from a remote transaction (generated by getResponseMetadata()).

Since:

3.16.1

processResponseMetadata

void processResponseMetadata(java.lang.String responseMetadata,
                           java.net.URI uri)

Provide the metadata string from a remote transaction's call to getResponseMetadata() to the current transaction. This should only be called on the originating transaction when processing response to a remote call. Use this method when implementing cross application tracing support for a transport not supported by New Relic, such as a proprietary RPC transport.

Server A

... get response containing responseMetadata from call to server B.

NewRelic.getAgent().getTransaction().processResponseMetadata(responseMetadata, uri); Note that the URI parameter should include a valid scheme, host, and port.

Parameters:

responseMetadata - metadata string from a remote transaction (generated by getResponseMetadata()).

uri - The external URI for the call.

Since:

3.36.0

setWebRequest

void setWebRequest(ExtendedRequest request)

Web Frameworks API ******************************** /** Sets the request for the current transaction. Setting the request will convert the current transaction into a web transaction. Successive calls will have no effect (first wins).

Parameters:

request - The current transaction's request.

Since:

3.36.0

setWebResponse

void setWebResponse(Response response)

Sets the response for the current transaction. Setting the response will convert the current transaction into a web transaction. Successive calls will have no effect (first wins).

Parameters:

response - The current transaction's response.

Since:

3.36.0

markResponseSent

boolean markResponseSent()

Marks the time when the last byte of the response left the server as the current timestamp. Successive calls will have no effect (first wins).

Returns:

True if the call to set the response time was successful

Since:

3.36.0

isWebTransaction

boolean isWebTransaction()

Returns true if in a web transaction.

Returns:

true if this is a web transaction, else false.

Since:

3.36.0

convertToWebTransaction

void convertToWebTransaction()

Turns the current transaction from a background transaction into a web transaction.

Since:

3.36.0

addOutboundResponseHeaders

void addOutboundResponseHeaders()

Instruct the transaction to write the outbound response headers. This must be called before response headers are sent and the response is committed. Successive calls will have no effect (first wins). This must be called after setWebRequest(ExtendedRequest) and setWebResponse(Response), which together provide the Agent with the inbound request headers and a place to record the outbound headers.

Since:

3.36.0