Adding oversampling mitigation example to core package ReadMe (#545)

* added oversampling mitigation example to core package ReadMe

* update logged message

* added code snippet to wrap downstream SDK calls with unsampled subsegment

* updated code snippet

* nit: style improvements

* changed wording for oversampling mitigation APIs

* nit: style improvements

Author: carolabadeer

packages/core/README.md

@@ -401,6 +401,70 @@ subsegment.addSubsegment(newSubseg);
 newSubseg.close();
 ```
 
+### Oversampling Mitigation 
+To modify the sampling decision at the subsegment level, subsegments that inherit the decision of their direct parent (segment or subsegment) can be created using the `addNewSubsegment` and `addSubsegment` APIs, and unsampled subsegments can be created using the `addNewSubsegmentWithoutSampling` and `addSubsegmentWithoutSampling` APIs. 
+
+The code snippet below demonstrates creating a sampled or unsampled subsegment based on the sampling decision of each SQS message processed by Lambda.
+
+```js
+exports.handler = async function(event, context) { 
+    event.Records.forEach(message => {
+
+        const { attributes } = message;
+        let facade = xrayContext.getSegment();
+
+        if(SqsMessageHelper.isSampled(message)){
+          
+          let sampledSubsegment = facade.addNewSubsegment('sqs-subsegment-sampled');
+          xrayContext.setSegment(sampledSubsegment);
+          console.log("processing SQS message - sampled");
+          sampledSubsegment.close();
+
+        } else {
+          let unsampledSubsegment = facade.addNewSubsegmentWithoutSampling('sqs-subsegment-unsampled');
+          xrayContext.setSegment(unsampledSubsegment);
+          console.log("processing SQS message - unsampled");
+          unsampledSubsegment.close();
+        }
+
+        xrayContext.setSegment(facade);
+    });
+
+    return 'Success';
+}
+```
+
+The code snippet below demonstrates wrapping a downstream AWS SDK request with an unsampled subsegment.
+```js
+const { Segment } = require('aws-xray-sdk');
+const xray = require('aws-xray-sdk');
+ 
+// Instrument AWS SDK Clients
+const AWS = xray.captureAWS(require('aws-sdk'));
+ 
+exports.handler = async (event, context) => {
+  const facade = xray.getSegment();
+ 
+  // Create a not-sampled subsegment, which will coerce the downstream request to be unsampled
+  const unsampled = facade.addNewSubsegmentWithoutSampling('sqs-subsegment-unsampled');
+ 
+  // Set unsampled subsegment in context
+  xray.setSegment(unsampled);
+ 
+  try {
+    const sqs = new AWS.SQS();
+    const data = await sqs.listQueues().promise();
+    console.log(data);
+  } catch (error) {
+    console.log("retrieveFromSqs error:", error);
+    throw error;
+  }
+  unsampled.close();
+  return 'Success';
+}
+
+```
+
 ## Automatic Mode Examples
 
 ### Capture through function calls