Benign exceptions - Java SDK

How to mark an Activity error as benign using the Temporal Java SDK

When Activities throw errors that are expected or not severe, they can create noise in your logs, metrics, and OpenTelemetry traces, making it harder to identify real issues. By marking these errors as benign, you can exclude them from your observability data while still handling them in your Workflow logic.

To mark an error as benign, set the category to ApplicationErrorCategory.BENIGN using the ApplicationFailure builder.

Benign errors:

• Have Activity failure logs downgraded to DEBUG level
• Do not emit Activity failure metrics
• Do not set the OpenTelemetry failure status to ERROR

import io.temporal.activity.ActivityInterface;
import io.temporal.activity.ActivityMethod;
import io.temporal.failure.ApplicationErrorCategory;
import io.temporal.failure.ApplicationFailure;

@ActivityInterface
public interface MyActivities {
  @ActivityMethod
  String myActivity();
}

public class MyActivitiesImpl implements MyActivities {
  @Override
  public String myActivity() {
    try {
      return callExternalService();
    } catch (Exception e) {
      // Mark this error as benign since it's expected
      throw ApplicationFailure.newBuilder()
          .setMessage(e.getMessage())
          .setType(e.getClass().getName())
          .setCause(e)
          .setCategory(ApplicationErrorCategory.BENIGN)
          .build();
    }
  }
}

Use benign exceptions for Activity errors that occur regularly as part of normal operations, such as polling an external service that isn't ready yet, or handling expected transient failures that will be retried.