Module co.elastic.apm.api
Package co.elastic.apm.api

Interface Transaction

  • All Superinterfaces:
    Span
    public interface Transaction
extends Span
    A transaction is the data captured by an agent representing an event occurring in a monitored service and groups multiple spans in a logical group.

    To get a reference to the current transaction, call ElasticApm.currentTransaction().

    • Method Detail

      • setName

        @Nonnull
Transaction setName​(String name)
        Override the name of the current transaction.

        For supported frameworks, the transaction name is determined automatically, and can be overridden using this function.

        Specified by:
        setName in interface Span
        Parameters:
        name - A string describing name of the transaction.

      • setType

        @Nonnull
Transaction setType​(String type)
        The type of the transaction.

        There’s a special type called request which is used by the agent for the transactions automatically created when an incoming HTTP request is detected.

        Specified by:
        setType in interface Span
        Parameters:
        type - The type of the transaction.

      • addLabel

        @Nonnull
Transaction addLabel​(String key,
                     String value)
        Description copied from interface: Span

        Labels are used to add indexed information to transactions, spans, and errors. Indexed means the data is searchable and aggregatable in Elasticsearch. Multiple labels can be defined with different key-value pairs.

        • Indexed: Yes
        • Elasticsearch type: object
        • Elasticsearch field: labels (previously context.tags in stack version < 7.0)

        Label values can be a string, boolean, or number. Because labels for a given key are stored in the same place in Elasticsearch, all label values of a given key must have the same data type. Multiple data types per key will throw an exception, e.g. {foo: bar} and {foo: 42}

        Important: Avoid defining too many user-specified labels. Defining too many unique fields in an index is a condition that can lead to a mapping explosion.

        Specified by:
        addLabel in interface Span
        Parameters:
        key - The label key.
        value - The label value.

      • addLabel

        @Nonnull
Transaction addLabel​(String key,
                     Number value)
        Description copied from interface: Span

        Labels are used to add indexed information to transactions, spans, and errors. Indexed means the data is searchable and aggregatable in Elasticsearch. Multiple labels can be defined with different key-value pairs.

        • Indexed: Yes
        • Elasticsearch type: object
        • Elasticsearch field: labels (previously context.tags in stack version < 7.0)

        Label values can be a string, boolean, or number. Because labels for a given key are stored in the same place in Elasticsearch, all label values of a given key must have the same data type. Multiple data types per key will throw an exception, e.g. {foo: bar} and {foo: 42}

        Note: Number and boolean labels were only introduced in APM Server 6.7+. Using this API in combination with an older APM Server versions leads to validation errors.

        Important: Avoid defining too many user-specified labels. Defining too many unique fields in an index is a condition that can lead to a mapping explosion.

        Specified by:
        addLabel in interface Span
        Parameters:
        key - The label key.
        value - The label value.

      • addLabel

        @Nonnull
Transaction addLabel​(String key,
                     boolean value)
        Description copied from interface: Span

        Labels are used to add indexed information to transactions, spans, and errors. Indexed means the data is searchable and aggregatable in Elasticsearch. Multiple labels can be defined with different key-value pairs.

        • Indexed: Yes
        • Elasticsearch type: object
        • Elasticsearch field: labels (previously context.tags in stack version < 7.0)

        Label values can be a string, boolean, or number. Because labels for a given key are stored in the same place in Elasticsearch, all label values of a given key must have the same data type. Multiple data types per key will throw an exception, e.g. {foo: bar} and {foo: 42}

        Note: Number and boolean labels were only introduced in APM Server 6.7+. Using this API in combination with an older APM Server versions leads to validation errors.

        Important: Avoid defining too many user-specified labels. Defining too many unique fields in an index is a condition that can lead to a mapping explosion.

        Specified by:
        addLabel in interface Span
        Parameters:
        key - The label key.
        value - The label value.

      • addCustomContext

        @Nonnull
Transaction addCustomContext​(String key,
                             String value)
        Custom context is used to add non-indexed, custom contextual information to transactions. Non-indexed means the data is not searchable or aggregatable in Elasticsearch, and you cannot build dashboards on top of the data. However, non-indexed information is useful for other reasons, like providing contextual information to help you quickly debug performance issues or errors.
        Parameters:
        key - The custom context key.
        value - The custom context value.

      • addCustomContext

        @Nonnull
Transaction addCustomContext​(String key,
                             Number value)
        Custom context is used to add non-indexed, custom contextual information to transactions. Non-indexed means the data is not searchable or aggregatable in Elasticsearch, and you cannot build dashboards on top of the data. However, non-indexed information is useful for other reasons, like providing contextual information to help you quickly debug performance issues or errors.
        Parameters:
        key - The custom context key.
        value - The custom context value.

      • addCustomContext

        @Nonnull
Transaction addCustomContext​(String key,
                             boolean value)
        Custom context is used to add non-indexed, custom contextual information to transactions. Non-indexed means the data is not searchable or aggregatable in Elasticsearch, and you cannot build dashboards on top of the data. However, non-indexed information is useful for other reasons, like providing contextual information to help you quickly debug performance issues or errors.
        Parameters:
        key - The custom context key.
        value - The custom context value.

      • setUser

        Transaction setUser​(String id,
                    String email,
                    String username)
        Call this to enrich collected performance data and errors with information about the user/client.

        This method can be called at any point during the request/response life cycle (i.e. while a transaction is active). The given context will be added to the active transaction.

        If an error is captured, the context from the active transaction is used as context for the captured error.

        Parameters:
        id - The user's id or null, if not applicable.
        email - The user's email address or null, if not applicable.
        username - The user's name or null, if not applicable.

      • setResult

        Transaction setResult​(String result)
        A string describing the result of the transaction. This is typically the HTTP status code, or e.g. "success" for a background task
        Parameters:
        result - a string describing the result of the transaction

      • setStartTimestamp

        Transaction setStartTimestamp​(long epochMicros)
        Description copied from interface: Span
        Sets the start timestamp of this event.
        Specified by:
        setStartTimestamp in interface Span
        Parameters:
        epochMicros - the timestamp of when this event happened, in microseconds (µs) since epoch
        Returns:
        this for chaining

      • end

        void end()
        End tracking the transaction.

        Should be called e.g. at the end of a request or when ending a background task.

        Specified by:
        end in interface Span

      • getId

        @Nonnull
String getId()
        Returns the id of this transaction (never null)

        If this transaction represents a noop, this method returns an empty string.

        Specified by:
        getId in interface Span
        Returns:
        the id of this transaction (never null)

      • ensureParentId

        @Nonnull
String ensureParentId()

        If the transaction does not have a parent-ID yet, calling this method generates a new ID, sets it as the parent-ID of this transaction, and returns it as a `String`.

        This enables the correlation of the spans the JavaScript Real User Monitoring (RUM) agent creates for the initial page load with the transaction of the backend service. If your backend service generates the HTML page dynamically, initializing the JavaScript RUM agent with the value of this method allows analyzing the time spent in the browser vs in the backend services.

        To enable the JavaScript RUM agent when using an HTML templating language like Freemarker, add ElasticApm.currentTransaction() with the key "transaction" to the model.

        Also, add a snippet similar to this to the body of your HTML pages, preferably before other JS libraries: 

        
 <script src="elastic-apm-js-base/dist/bundles/elastic-apm-js-base.umd.min.js"></script>
 <script>
   elasticApm.init({
     serviceName: "service-name",
     serverUrl: "http://localhost:8200",
     pageLoadTraceId: "${transaction.traceId}",
     pageLoadSpanId: "${transaction.ensureParentId()}",
     pageLoadSampled: ${transaction.sampled}
   })
 </script>

        See the JavaScript RUM agent documentation for more information.

        Returns:
        the parent-ID for this transaction. Updates the transaction to use a new parent-ID if it has previously been unset.

      • activate

        Scope activate()
        Makes this transaction the active transaction on the current thread until Scope.close() has been called.

        Scopes should only be used in try-with-resource statements in order to make sure the Scope.close() method is called in all circumstances. Failing to close a scope can lead to memory leaks and corrupts the parent-child relationships.

        This method should always be used within a try-with-resources statement: 

         Transaction transaction = ElasticApm.startTransaction();
 // within the try block the transaction is available on the current thread via ElasticApm.currentTransaction()
 // this is also true for methods called within the try block
 try (final Scope scope = transaction.activate()) {
     transaction.setName("MyController#myAction");
     transaction.setType(Transaction.TYPE_REQUEST);
     // do your thing...
 } catch (Exception e) {
     transaction.captureException(e);
     throw e;
 } finally {
     transaction.end();
 }

        Note: activate() and Scope.close() have to be called on the same thread.

        Specified by:
        activate in interface Span
        Returns:
        a scope which has to be Scope.close()d