Package com.newrelic.api.agent

Interface Segment

  • All Superinterfaces:
    AttributeHolder
    public interface Segment
extends AttributeHolder

    Represents a timed unit of work. Like a TracedMethod, reports a single metric, generates a single segment in a transaction trace, and can be reported as an external call. Unlike a TracedMethod, a Segment's timed duration may encompass arbitrary application work; it is not limited to a single method or thread.

    Timing begins when the instance is created via Transaction.startSegment(java.lang.String) and ends when the end() or ignore() method is called. These calls can be issued from distinct application threads. If a Segment is not explicitly ignored or ended it will be timed out according to the segment_timeout value which is user configurable in the yaml file or by a Java system property.

    A Segment will show up in the Transaction Breakdown table, as well as the Transaction Trace page in APM.

    • Method Detail

      • setMetricName

        void setMetricName​(java.lang.String... metricNameParts)
        Sets the metric name by concatenating all given metricNameParts with a '/' separating each part.
        Parameters:
        metricNameParts - The segments of the metric name. These values will be concatenated together separated by a `/` char.
        Since:
        3.37.0

      • reportAsExternal

        void reportAsExternal​(ExternalParameters externalParameters)
        Reports this traced method as an HTTP external call, datastore external call, or generic external call. Use ExternalParameters to create the externalParameters argument. If you are performing an external HTTP call, be sure to call addOutboundRequestHeaders(OutboundHeaders) prior to the request being sent.
        Parameters:
        externalParameters - The appropriate input parameters depending on the type of external call. See available Builders in ExternalParameters for more information.
        Since:
        3.37.0

      • addOutboundRequestHeaders

        void addOutboundRequestHeaders​(OutboundHeaders outboundHeaders)
        Adds headers to the external request so that the request can be recognized on the receiving end. To be called when performing an outbound external request using HTTP or JMS. This method must be called before any headers are written to the output stream. This method is generally used in conjunction with reportAsExternal.
        Parameters:
        outboundHeaders - The headers that will be written to the output stream for the external request. This also determines if the external call is HTTP or JMS.
        Since:
        3.37.0

      • ignore

        void ignore()
        Stops tracking the Segment and does not report it as part of its parent transaction. This method has no effect if the segment has ended. Every Segment instance must be completed by a call to ignore() or to end().
        Since:
        3.37.0

      • end

        void end()
        Stops timing the Segment and complete the execution on this thread. Only the first call to this method will have an effect. Every Segment instance must be completed by a call to ignore() or to end()/endAsync().
        Since:
        3.37.0

      • endAsync

        void endAsync()
        Stops timing the Segment and complete the execution on another thread. This method is preferred over end() when the underlying segment is running on a single threaded event loop. Only the first call to this method will have an effect. Every Segment instance must be completed by a call to ignore() or to end()/endAsync().
        Since:
        5.4.0