Adding an error to a sub/segment, forces a fault flag.

[Tanbouz]

Details

this.addFaultFlag();

aws-xray-sdk-node/packages/core/lib/segments/segment.js

Lines 228 to 234 in b899614

	Segment.prototype.addError = function addError(err, remote) {
	if (!isObject(err) && typeof(err) !== 'string') {
	throw new Error('Failed to add error:' + err + ' to subsegment "' + this.name +
	'". Not an object or string literal.');
	}
	this.addFaultFlag();

AWS X-ray concepts regarding error categorization

X-Ray tracks errors that occur in your application code, and errors that are returned by downstream services. Errors are categorized as follows.

Error – Client errors (400 series errors)
Fault – Server faults (500 series errors)
Throttle – Throttling errors (429 Too Many Requests)

Issue

if addError refers directly to client errors then it is a bit confusing that it flags it as a "Fault" and not an "Error" flag.

If addError is more of an abstract method for all x-ray error types, then I don't have the option to specifiy which kind of x-ray error it is per the categorizations above. And I'm forced to have it flagged as a "Fault".

[haotianw465]

Sorry for the confusion. The error here means "exception". This method is designed to be called when there is an unhandled error. It adds both error message, stack trace and flag as fault since unhandled errors are programing errors which usually result in program behave unexpectedly. If you want to flag a segment as error you can use addErrorFlag

aws-xray-sdk-node/packages/core/lib/segments/segment.js

Line 267 in b899614

Segment.prototype.addErrorFlag = function addErrorFlag() {

. Could you elaborate more on your use case of manually adding an error (exception) but need to set a non-fault flag so we can evaluable an API improvement?

[Tanbouz]

It is no big deal. I'm new to X-Ray and wished to understand and use the terminology better.

I simply wanted to use custom segments and sub-segments in manual mode to wrap sections of my functions and didn't like 😛 that I was forced to flag all "exceptions" as Faults because I wanted to categorize them like so:

1- Flag the exception as a fault if it something that is handled but I still wish to track. Something like a 3rd party service that fails (HTTP request). I can also see the stack trace on why it failed.

addError()
addFaultFlag()

2- Flag the exception as an unhandled error otherwise. Something needs to be handled or fixed due my own code logic/syntax.

addError()
addErrorFlag()

3- Flag it as throttling if I have my own throttling logic

addError()
addThrottleFlag()

4- Flag it as throttling and a fault if a 3rd party service throttles.

addError()
addThrottleFlag()
addFaultFlag()

5- Flag it as a fault and error if a 3rd party service fault is unhandled.

addError()
addErrorFlag()
addFaultFlag()

I can always implement my own tagging in the segment's metadata. So it is no issue I guess. I will leave it up to you 😄

[haotianw465]

These are definitely valid use cases. I think we should add an argument on the addError API that takes an optional flag so you can flag it to error/throttle other than fault. Right now you will have to manually call other add flag method and manually remove the fault flag. Please let me know if you need additional help. A PR is also welcome.

[icholy]

Another option would be to allow passing a value to addFaultFlag and addErrorFlag.

/**
 * Adds fault flag to the subsegment.
 */

Segment.prototype.addFaultFlag = function addFaultFlag(fault = true) {
  this.fault = fault;
};

/**
 * Adds error flag to the subsegment.
 */

Segment.prototype.addErrorFlag = function addErrorFlag(error = true) {
  this.error = error;
};

Then I could just do:

segment.addError(err);
segment.addFaultFlag(false);

I'm currently using:

function traceError(err: any, fault?: boolean): void {
  const seg = getSegment();
  if (seg) {
    seg.addError(err);
    if (!fault) {
      // @ts-ignore
      seg.fault = false;
      seg.addErrorFlag();
    }
  }
}