Feeling bold?
Sentry's Docs BotAsk A Bot
Product
API
Changelog
Sandbox
Sign In

Custom Instrumentation

To instrument certain regions of your code, you can create transactions to capture them.

The following example creates a transaction that contains an expensive operation (for example, processOrderBatch), and sends the result to Sentry:

Copied
import io.sentry.ITransaction;
import io.sentry.Sentry;
import io.sentry.SpanStatus;

// A good name for the transaction is key, to help identify what this is about
ITransaction transaction = Sentry.startTransaction("processOrderBatch()", "task");
try {
  processOrderBatch();
} catch (Exception e) {
  transaction.setThrowable(e);
  transaction.setStatus(SpanStatus.INTERNAL_ERROR);
  throw e;
} finally {
  transaction.finish();
}

By default, transactions are not bound to the scope. Transaction has to be passed manually as a method parameter to enable attaching nested spans. When creating nested span, you can choose the value of operation and description.

Copied
import java.io.FileNotFoundException;

import io.sentry.ISpan;
import io.sentry.ITransaction;
import io.sentry.Sentry;
import io.sentry.SpanStatus;

// A good name for the transaction is key, to help identify what this is about
ITransaction transaction = Sentry.startTransaction("processOrderBatch()", "task");
try {
  processOrderBatch(transaction);
} catch (Exception e) {
  transaction.setThrowable(e);
  transaction.setStatus(SpanStatus.INTERNAL_ERROR);
  throw e;
} finally {
  transaction.finish();
}

void processOrderBatch(ISpan span) {
  if (span == null) {
    span = Sentry.startTransaction("processOrderBatch()", "task");
  }
  // span operation: task, span description: operation
  ISpan innerSpan = span.startChild("task", "operation");
  try {
    // omitted code
  } catch (FileNotFoundException e) {
    innerSpan.setThrowable(e);
    innerSpan.setStatus(SpanStatus.NOT_FOUND);
    throw e;
  } finally {
    innerSpan.finish();
  }
}

Keep in mind that each individual span also needs to be manually finished; otherwise, spans will not show up in the transaction.

Spans are sent together with their parent transaction when the transaction is finished. Make sure to call finish() on transaction once all the child spans have finished.

Our SDK can bind a transaction to the scope making it accessible to every method running within this scope by calling Sentry#startTransaction method with bindToScope parameter to true.

bindToScope additionally ensures that your new transaction replaces any one that may be already started. This is useful if you want custom instrumentation to co-exist with auto-instrumented transactions.

In cases where you want to attach Spans to an already ongoing Transaction you can use Sentry#getSpan. This method will return a SentryTransaction in case there is a running Transaction or a Span in case there is already a running Span, otherwise it returns null.

Copied
import java.io.FileNotFoundException;

import io.sentry.ISpan;
import io.sentry.ITransaction;
import io.sentry.Sentry;
import io.sentry.SpanStatus;
import io.sentry.TransactionOptions;

// A good name for the transaction is key, to help identify what this is about
TransactionOptions txOptions = new TransactionOptions();
txOptions.setBindToScope(true);
ITransaction transaction = Sentry.startTransaction("processOrderBatch()", "task", txOptions);
try {
  processOrderBatch();
} catch (Exception e) {
  transaction.setThrowable(e);
  transaction.setStatus(SpanStatus.INTERNAL_ERROR);
  throw e;
} finally {
  transaction.finish();
}

void processOrderBatch() {
  ISpan span = Sentry.getSpan();
  if (span == null) {
    span = Sentry.startTransaction("processOrderBatch()", "task");
  }
  ISpan innerSpan = span.startChild("task", "operation");
  try {
    // omitted code
  } catch (FileNotFoundException e) {
    innerSpan.setThrowable(e);
    innerSpan.setStatus(SpanStatus.NOT_FOUND);
    throw e;
  } finally {
    innerSpan.finish();
  }
}

Sentry errors can be linked with transactions and spans.

Errors reported to Sentry while transaction or span bound to the scope is running are linked automatically:

Copied
import io.sentry.Sentry;
import io.sentry.ISpan;
import io.sentry.ITransaction;
import io.sentry.TransactionOptions;

TransactionOptions txOptions = new TransactionOptions();
txOptions.setBindToScope(true);
ITransaction span = Sentry.startTransaction(item.getTransactionName(), "task", txOptions);
try {
  processItem();
} catch (Exception e) {
  Sentry.captureException(e);
} finally {
  span.finish();
}

Exceptions may be thrown within spans that can finish before exception gets reported to Sentry. To attach span information to this exception, you must link it by calling setThrowable method:

Copied
import io.sentry.Sentry;
import io.sentry.ISpan;

ISpan span = Sentry.getSpan();
if (span == null) {
  span = Sentry.startTransaction(item.getTransactionName(), "task");
}
try {
  processItem();
} catch (Exception e) {
  span.setThrowable(e);
  throw e;
} finally {
  span.finish();
}
Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").
Suggest an edit to this page   |  Contribute to Docs   |  Report a problem
Package:
maven:io.sentry:sentry-log4j2
Version:
7.8.0
Repository:
https://github.com/getsentry/sentry-java
API Documentation:
https://javadoc.io/doc/io.sentry
    Related Guides