Package 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.
    See Also:
    Agent.getTransaction(), Trace.dispatcher()

    • 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.
        Returns:
        deprecated
        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

        @Deprecated
java.lang.String getRequestMetadata()
        Deprecated.
        Instead, use the Distributed Tracing API insertDistributedTraceHeaders(Headers) to create a distributed tracing payload and acceptDistributedTraceHeaders(TransportType, Headers) to link the services together.
        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

        @Deprecated
void processRequestMetadata​(java.lang.String requestMetadata)
        Deprecated.
        Instead, use the Distributed Tracing API insertDistributedTraceHeaders(Headers) to create a distributed tracing payload and acceptDistributedTraceHeaders(TransportType, Headers) to link the services together.
        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

        @Deprecated
java.lang.String getResponseMetadata()
        Deprecated.
        Instead, use the Distributed Tracing API. There is no equivalent of this method in Distributed Tracing.
        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

        @Deprecated
void processResponseMetadata​(java.lang.String responseMetadata)
        Deprecated.
        Instead, use the Distributed Tracing API. There is no equivalent of this method in Distributed Tracing.
        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

        @Deprecated
void processResponseMetadata​(java.lang.String responseMetadata,
                             java.net.URI uri)
        Deprecated.
        Instead, use the Distributed Tracing API. There is no equivalent of this method in Distributed Tracing.
        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)
        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). If this method is used, it's important to also use setWebResponse(com.newrelic.api.agent.Response) in order to capture information like the response code for this Transaction.
        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). If this method is used, it's important to also use setWebRequest(com.newrelic.api.agent.ExtendedRequest) in order to name the Transaction properly.
        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

      • ignoreErrors

        void ignoreErrors()
        Ignore throwable and http status code errors resulting from this transaction.
        Since:
        4.12.0

      • convertToWebTransaction

        void convertToWebTransaction()
        Turns the current transaction from a background transaction into a web transaction.
        Since:
        3.36.0

      • addOutboundResponseHeaders

        void addOutboundResponseHeaders()
        Adds headers to the external response so that the response can be recognized on the receiving end. 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

      • getToken

        Token getToken()
        Creates a Token for linking asynchronous work to the current Transaction. Subsequent calls to getToken() will return a new Token. A single Token can be passed between multiple threads of work that should be linked to the transaction. A transaction will remain open until all tokens are expired or timed out. If getToken() is called outside of a Transaction a NoOpToken will be returned which will always return false when calling a method on the Token object.
        Returns:
        A token to pass to another thread with work for the current transaction.
        Since:
        3.37.0

      • startSegment

        Segment startSegment​(java.lang.String segmentName)
        Starts and returns a Segment. This Segment will show up in the Transaction Breakdown table, as well as the Transaction Trace page. This Segment will be reported in the "Custom/" metric category by default. If you want to specify a custom category use startSegment(String, String) instead.
        Parameters:
        segmentName - Name of the Segment segment in APM. This name will show up in the Transaction Breakdown table, as well as the Transaction Trace page. if null or an empty String, the agent will report "Unnamed Segment".
        Returns:
        A started Segment.
        Since:
        3.37.0

      • startSegment

        Segment startSegment​(java.lang.String category,
                     java.lang.String segmentName)
        Starts and returns a Segment. This Segment will show up in the Transaction Breakdown table, as well as the Transaction Trace page.
        Parameters:
        category - Metric category that will be used for this segment. If null or an empty String, the agent will report this Segment under the "Custom/" category.
        segmentName - Name of the Segment segment in APM. This name will show up in the Transaction Breakdown table, as well as the Transaction Trace page. if null or an empty String, the agent will report "Unnamed Segment".
        Returns:
        A started Segment.
        Since:
        3.37.0

      • insertDistributedTraceHeaders

        void insertDistributedTraceHeaders​(Headers headers)
        Generate distributed trace headers and insert them into the Headers. The header names inserted will depend on the Headers.getHeaderType().
        Parameters:
        headers - The headers to be updated with distributed trace header names and values.
        Since:
        6.5.0

      • acceptDistributedTraceHeaders

        void acceptDistributedTraceHeaders​(TransportType transportType,
                                   Headers headers)
        Accept the distributed trace headers. Accepting distributed trace headers sent from one service to another in a distributed system will result in those services being linked together in a trace of the system. Distributed trace payloads must be accept within an active New Relic Transaction. The header names accepted will depend on the Headers.getHeaderType().
        Parameters:
        transportType - The transport type of headers being accepted.
        headers - The headers to be accepted.
        Since:
        6.5.0

      • getSecurityMetaData

        java.lang.Object getSecurityMetaData()
        Returns the associated security related metadata from this Transaction.
        Returns:
        securityMetaData object associated with this transaction.