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().

  • Field Details

  • Method Details

    • 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.

    • setFrameworkName

      @Nonnull Transaction setFrameworkName(String frameworkName)
      Provides a way to manually set the service.framework.name field. Any value set through this method will take precedence over automatically-set value for supported frameworks.
      Parameters:
      frameworkName - The name of the framework. null and empty values will cause the exclusion of the framework name from the transaction context.

    • setServiceInfo

      @Nonnull Transaction setServiceInfo(String serviceName, String serviceVersion)
      Sets the service name and version for this transaction and its child spans.

      NOTE: If this method is called after child spans are already created, they may have the wrong service name and version.

      Parameters:
      serviceName - the service name
      serviceVersion - the service version

    • useServiceInfoForClassLoader

      @Nonnull Transaction useServiceInfoForClassLoader(ClassLoader classLoader)
      Sets the service name and version, that are associated with the given class loader (see: ElasticApm.setServiceInfoForClassLoader(ClassLoader, String, String)), for this transaction and its child spans.

      NOTE: If this method is called after child spans are already created, they may have the wrong service name and version.

      Parameters:
      classLoader - the class loader that should be used to set the service name and version

    • addTag

      @Nonnull @Deprecated Transaction addTag(String key, String value)
      Deprecated.
      use addLabel(String, String) instead
      Specified by:
      addTag in interface Span

    • addLabel

      @Nonnull @Deprecated Transaction addLabel(String key, String value)
      Deprecated.
      use setLabel(String, String) instead
      Specified by:
      addLabel in interface Span
      Parameters:
      key - The label key.
      value - The label value.

    • addLabel

      @Nonnull @Deprecated Transaction addLabel(String key, Number value)
      Deprecated.
      use setLabel(String, Number) instead
      Specified by:
      addLabel in interface Span
      Parameters:
      key - The label key.
      value - The label value.

    • addLabel

      @Nonnull @Deprecated Transaction addLabel(String key, boolean value)
      Deprecated.
      use setLabel(String, boolean) instead
      Specified by:
      addLabel in interface Span
      Parameters:
      key - The label key.
      value - The label value.

    • setLabel

      @Nonnull Transaction setLabel(String key, String value)

      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:
      setLabel in interface Span
      Parameters:
      key - The label key.
      value - The label value.

    • setLabel

      @Nonnull Transaction setLabel(String key, Number value)

      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:
      setLabel in interface Span
      Parameters:
      key - The label key.
      value - The label value.

    • setLabel

      @Nonnull Transaction setLabel(String key, boolean value)

      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:
      setLabel 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.

    • setUser

      Transaction setUser(String id, String email, String username, String domain)
      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.
      domain - The user's domain 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

    • setOutcome

      Transaction setOutcome(Outcome outcome)
      Sets the transaction outcome
      Specified by:
      setOutcome in interface Span
      Parameters:
      outcome - Outcome.SUCCESS to indicate success, Outcome.FAILURE for failure, Outcome.UNKNOWN to indicate unknown outcome
      Returns:
      this

    • 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

    • createSpan

      @Nonnull @Deprecated Span createSpan()
      Deprecated.
      NOTE: THIS METHOD IS DEPRECATED AND WILL BE REMOVED IN VERSION 2.0. Instead, start a new span through Span.startSpan() or Span.startSpan(String, String, String).
      Specified by:
      createSpan in interface Span
      Returns:
      the started span, never null

    • 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://127.0.0.1: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