The Atatus Java agent provides annotations to simplify creating custom transactions and spans. By adding these annotations to your methods, the agent will automatically create, activate, and report the corresponding transaction or span. It will also capture any uncaught exceptions.

Note:

You must configure application_packages. Otherwise, these annotations will be ignored.

Example:

Most Java projects define a root package (e.g., com.myproject). You can set the application package using Java system properties:

-Datatus.application_packages=com.myproject

If you want to include specific subpackages, separate them with commas:

-Datatus.application_packages=com.myproject.api,com.myproject.impl

Required Imports

import com.atatus.apm.api.CaptureTransaction;
import com.atatus.apm.api.CaptureSpan;
import com.atatus.apm.api.Traced;

Available Annotations

1. @CaptureTransaction

Creates a transaction for the annotated method. This is only applied when there is no active transaction on the same thread.

Attributes

  • value: Name of the transaction (default: ClassName#methodName)
  • type: Type of the transaction (default: request)

Behavior

  • Starts and activates a transaction on method entry
  • Ends and deactivates the transaction on method exit

Example 

@CaptureTransaction(value="Checkout Process", type="request")
public void checkout() {
    // business logic
}

2. @CaptureSpan

Creates a span as the child of the currently active span or transaction. If no transaction or span is active, nothing will be created.

Attributes

  • value: Name of the span (default: ClassName#methodName)
  • type: Type of the span (default: app)
  • subtype: Span subtype (e.g., mysql)
  • action: Related action (e.g., query)
  • discardable: Set to false to ensure the span is always reported
  • exit: Set to true to represent calls to external systems (e.g., DB or third-party APIs)

Behavior

  • Starts and activates a span on method entry
  • Ends and deactivates the span on method exit

Example 

@CaptureSpan(value="Fetch Orders", type="db", subtype="mysql", action="query")
public List<Order> getOrders() {
    // database query logic
}

3. @Traced

Annotating a method with @Traced automatically decides whether to create a transaction or a span based on the context: it creates a child span if a span or transaction is active, otherwise it starts a new transaction.

Use @Traced when a method may act as either an entry point (transaction) or a unit of work within an existing transaction (span).

Attributes

  • value: Name of the span/transaction (default: ClassName#methodName)
  • type: Type (default: request for transactions, app for spans)
  • subtype: Span subtype (ignored if a transaction is created)
  • action: Span action (ignored if a transaction is created)
  • discardable: Set to false to ensure the span is always reported (ignored for transactions)

Behavior

  • Automatically chooses between transaction or span
  • Starts and activates on method entry
  • Ends and deactivates on method exit

Example 

@Traced(value="Process Payment", type="request")
public void processPayment() {
    // payment logic
}