Package com.appoptics.api.ext

Class Trace

  • public class Trace
extends java.lang.Object
    API for initiating traces and creating events, for use by non-web / background apps, etc.

    A Trace is a unit of instrumented work, usually mapped to a web request.

    Each trace consists of exactly one top span, more spans can be added below and each of those spans can contain multiple "spans" which are marked by exactly one entry and exit event and optionally info events in between. A span usually represents duration of an operation.

    See Also:
    Java Agent - Instrumentation SDK

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static TraceEvent continueTrace​(java.lang.String layer, java.lang.String inXTraceID)
      Continues a trace from external span, respecting the sampling rate.
      static TraceEvent createEntryEvent​(java.lang.String layer)
      Creates an entry event of a new span with the given name.
      static TraceEvent createExitEvent​(java.lang.String layer)
      Creates an exit event of the current span with the given name.
      static TraceEvent createInfoEvent​(java.lang.String layer)
      Creates an info event for the named span.
      static java.lang.String endTrace​(java.lang.String layer)
      Ends a trace by creating an exit event and reporting it for the named span.
      static java.lang.String endTrace​(java.lang.String layer, java.lang.Object... info)
      Ends a trace by creating an exit event and reporting it for the named span.
      static java.lang.String endTrace​(java.lang.String layer, java.util.Map<java.lang.String,​java.lang.Object> info)
      Ends a trace by creating an exit event and reporting it for the named span.
      static java.lang.String getCurrentLogTraceID()
      Returns a compact form of current context's Metadata suitable for logging purpose
      static java.lang.String getCurrentXTraceID()
      Returns XTraceID associated with current context's Metadata as a hex string This is suitable for propagating to other spans (HTTP -> App servers, etc.) Take note that in order to correlate logs with traces, please use getCurrentLogTraceID()
      static void logException​(java.lang.Throwable error)
      Creates and sends an error event for an exception (throwable), including a back trace.
      static boolean setTransactionName​(java.lang.String transactionName)
      Sets a transaction name to the current active trace, the transaction name will be reported along with the corresponding trace and metrics.
      static TraceEvent startTrace​(java.lang.String layer)
      Starts a trace, respecting the sampling rate.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Method Detail

      • startTrace

        public static TraceEvent startTrace​(java.lang.String layer)
        Starts a trace, respecting the sampling rate.

        To start a trace, you must call the startTrace method with your span name. This would typically be done when a new request enters your system. You can then add key / value pairs to the event containing information about the request.

        Take note that this method does not report the event. The TraceEvent must be reported by invoking TraceEvent.report().

        Example: 

         
 TraceEvent event = Trace.startTrace("my_layer");
 event.addInfo("my_key", "my_value");
 event.report();
        Note that startTrace automatically takes into account sampling settings - for testing, set tracingMode to always and sampleRate to 1000000. (See Configuring Java Instrumentation.)
        Parameters:
        layer - The name of the top span
        Returns:
        TraceEvent: an entry TraceEvent that can be populated with name/value pairs and reported. This event is the entry of the top extent.

      • continueTrace

        public static TraceEvent continueTrace​(java.lang.String layer,
                                       java.lang.String inXTraceID)
        Continues a trace from external span, respecting the sampling rate.

        If your application receive requests through a higher layer, such as an instrumented web server, you will receive an identifier for that trace. This identifier, the X-Trace ID, should be provided to the continueTrace method along with the span name. If you are instrumenting a standalone application, you will not need to use this call. Note that you should not use startTrace in this case.

        Take note that this method does not report the event. The TraceEvent must be reported by invoking TraceEvent.report().

        Example: 

         
 TraceEvent event= Trace.continueTrace("my_layer", xTraceID);
 event.addInfo("my_key", "my_value");
 event.report();
        Parameters:
        layer - The name of the span added below the existing span above
        inXTraceID - XTrace ID from incoming/previous span
        Returns:
        TraceEvent: an entry TraceEvent that can be populated with name/value pairs and reported. This event is the entry of the extent added below the external span

      • endTrace

        public static java.lang.String endTrace​(java.lang.String layer)
        Ends a trace by creating an exit event and reporting it for the named span. Metadata is then cleared and the XTrace ID is returned. This is just a convenience method, as createExitEvent could also be used.

        To end a trace, you must call the endTrace method with your span name. This would typically be done when your request is done processing. The X-Trace ID of the reported event is returned. If you are returning control to a higher span (such as an instrumented web server), you will need to return that ID using the appropriate method (such as an HTTP response header). If you are tracing a standalone application, it can be ignored.

        Example: 

         
 String xTraceID = Trace.endTrace("my_layer");
        Parameters:
        layer - The name of the trace's top span
        Returns:
        XTrace ID that can be returned to calling span

      • endTrace

        public static java.lang.String endTrace​(java.lang.String layer,
                                        java.util.Map<java.lang.String,​java.lang.Object> info)
        Ends a trace by creating an exit event and reporting it for the named span. Metadata is then cleared and the XTrace ID is returned. This is just a convenience method, as createExitEvent could also be used.

        To end a trace, you must call the endTrace method with your span name. This would typically be done when your request is done processing. The X-Trace ID of the reported event is returned. If you are returning control to a higher span (such as an instrumented web server), you will need to return that ID using the appropriate method (such as an HTTP response header). If you are tracing a standalone application, it can be ignored.

        Example: 

         
 String xTraceID = Trace.endTrace("my_layer");
        Parameters:
        layer - The name of the trace's top span
        info - name/value pairs reported with exit event
        Returns:
        XTrace ID that can be returned to calling span

      • endTrace

        public static java.lang.String endTrace​(java.lang.String layer,
                                        java.lang.Object... info)
        Ends a trace by creating an exit event and reporting it for the named span. Metadata is then cleared and the XTrace ID is returned. This is just a convenience method, as createExitEvent could also be used.

        To end a trace, you must call the endTrace method with your span name. This would typically be done when your request is done processing. The X-Trace ID of the reported event is returned. If you are returning control to a higher span (such as an instrumented web server), you will need to return that ID using the appropriate method (such as an HTTP response header). If you are tracing a standalone application, it can be ignored.

        Example: 

         
 String xTraceID = Trace.endTrace("my_layer");
        Parameters:
        layer - The name of the trace's top span
        info - name/value pairs reported with exit event
        Returns:
        XTrace ID that can be returned to calling span

      • createEntryEvent

        public static TraceEvent createEntryEvent​(java.lang.String layer)
        Creates an entry event of a new span with the given name. The entry event indicates the start of the newly created span. It is up to you, the application developer, to decide how to segment your application's modules and subsystems into spans. The event must be created, populated with name/value pairs.

        Take note that this method does not report the event. The TraceEvent must be reported by invoking TraceEvent.report().

        Example: 

         
 TraceEvent event = Trace.createEntryEvent("some_other_layer");
 event.addInfo("name2","value2");
 event.report();
        Parameters:
        layer - The name of the new span to be created
        Returns:
        TraceEvent: an entry TraceEvent that can be populated with name/value pairs and reported later

      • createExitEvent

        public static TraceEvent createExitEvent​(java.lang.String layer)
        Creates an exit event of the current span with the given name. The exit event indicates the end of the current span. It can be populated with name/value pairs just like the entry event. There should be a matching exit event for each entry.

        Take note that this method does not report the event. The TraceEvent must be reported by invoking TraceEvent.report().

        Example: 

         
 TraceEvent event = Trace.createExitEvent("some_other_layer");
 event.addInfo("name1", "value1");
 event.addInfo("name2", "value2");
 event.report();
        Parameters:
        layer - The name of the current span to be ended
        Returns:
        TraceEvent: an exit TraceEvent that can be populated with name/value pairs and reported later

      • createInfoEvent

        public static TraceEvent createInfoEvent​(java.lang.String layer)
        Creates an info event for the named span. You may need to report various information as your application executes, in between the entry and exit events of a particular span. This can be done using info events. Note that the span name of the info event can be null if you wish to inherit the current span.

        Take note that this method does not report the event. The TraceEvent must be reported by invoking TraceEvent.report().

        Example: 

         
 TraceEvent event = Trace.createInfoEvent("some_other_layer");
 event.addInfo("something", "interesting");
 event.report();
        Parameters:
        layer - The name of the span which the info event is created for. null if the current span name is to be used.
        Returns:
        TraceEvent: an info event that can be populated with name/value pairs and reported

      • logException

        public static void logException​(java.lang.Throwable error)
        Creates and sends an error event for an exception (throwable), including a back trace.

        Example: 

         
 try {
     // your code that might throw an exception goes here ...
 } catch(YourException exception) {
     Trace.logException(exception);
     // the rest of your exception handler ...
 }
        Parameters:
        error - throwable to be logged

      • setTransactionName

        public static boolean setTransactionName​(java.lang.String transactionName)
        Sets a transaction name to the current active trace, the transaction name will be reported along with the corresponding trace and metrics. This overrides the transaction name provided by out-of-the-box instrumentation. If multiple transaction names are set on the same trace, then the last one would be used. Take note that transaction name might be truncated with invalid characters replaced. Empty string and null are considered invalid transaction name values and will be ignored
        Parameters:
        transactionName - transaction name to be used, should not be null or empty string.
        Returns:
        true if there is an active trace and transaction name is not null or empty string.

      • getCurrentXTraceID

        public static java.lang.String getCurrentXTraceID()
        Returns XTraceID associated with current context's Metadata as a hex string This is suitable for propagating to other spans (HTTP -> App servers, etc.) Take note that in order to correlate logs with traces, please use getCurrentLogTraceID()
        Returns:
        a full id for current context

      • getCurrentLogTraceID

        public static java.lang.String getCurrentLogTraceID()
        Returns a compact form of current context's Metadata suitable for logging purpose
        Returns:
        a compact id for current context