@instana/core - npm Package Compare versions

Comparing version 2.24.0 to 2.25.0

CHANGELOG.md

@@ -6,2 +6,13 @@ # Change Log
 
+# [2.25.0](https://github.com/instana/nodejs/compare/v2.24.0...v2.25.0) (2023-06-16)
+
+
+### Features
+
+* **sdk:** add method to mark the current span as erroneous ([2cfcc7b](https://github.com/instana/nodejs/commit/2cfcc7b921518b4dc174b8296cff0122f523d532))
+
+
+
+
+
 # [2.24.0](https://github.com/instana/nodejs/compare/v2.23.0...v2.24.0) (2023-06-13)
@@ -8,0 +19,0 @@

package.json

 {
   "name": "@instana/core",
-  "version": "2.24.0",
+  "version": "2.25.0",
   "description": "Core library for Instana's Node.js packages",
@@ -143,3 +143,3 @@ "main": "src/index.js",
   },
-  "gitHead": "c12ff39a612bcd353bdc774876bb9df1f520e0a6"
+  "gitHead": "a0ca4681e7c3cb948ea2eba0f8e91e537ee03ed4"
 }

src/tracing/spanHandle.js

@@ -10,2 +10,8 @@ /*
 
+/** @type {import('../logger').GenericLogger} */
+let logger;
+logger = require('../logger').getLogger('tracing/spanHandle', newLogger => {
+  logger = newLogger;
+});
+
 /**
@@ -128,4 +134,13 @@ * Provides very limited access from client code to the current active span.
 /**
- * @param {string} path
- * @param {*} value
+ * Adds an annotation (also known as a tag or custom tag) to the span. The path can be provided as a dot-separated
+ * string or as an array of strings. That is, the following two calls are equivalent:
+ * - span.annotate('sdk.custom.tags.myTag', 'My Value'), and
+ * - span.annotate(['sdk', 'custom', 'tags', 'myTag'], 'My Value').
+ *
+ * Note that custom tags should always be prefixed by sdk.custom.tags. You can also use this method to override standard
+ * tags, like the HTTP path template (example: span.annotate('http.path_tpl', '/user/{id}/details')), but it is not
+ * recommended, unless there are very good reasons to interfere with Instana's auto tracing.
+ *
+ * @param {string|Array.<string>} path the path of the annotation in the span object
+ * @param {*} value the value for the annotation
  */
@@ -179,3 +194,3 @@ SpanHandle.prototype.annotate = function annotate(path, value) {
  * @param {Object.<string, *>} target
- * @param {string} path
+ * @param {Array.<string>} path
  * @param {*} value
@@ -201,2 +216,100 @@ */
 /**
+ * Marks the span as an error (that is, it sets the error count for the span to 1). You can optionally provide an error
+ * message. If no message is provided, a default error message will be set.
+ *
+ * @param {string?} errorMessage the error message to add as an annotation
+ * @param {string|Array.<string>} errorMessagePath the annotation path where the error message will be written to;
+ *   there is usually no need to provide this argument as this will be handled automatically
+ */
+SpanHandle.prototype.markAsErroneous = function markAsErroneous(
+  errorMessage = 'This call has been marked as erroneous via the Instana Node.js SDK, no error message has been ' +
+    'supplied.',
+  errorMessagePath
+) {
+  this.span.ec = 1;
+  this._annotateErrorMessage(errorMessage, errorMessagePath);
+};
+
+/**
+ * Marks the span as being not an error (that is, it sets the error count for the span to 0). This is useful if the span
+ * has been marked erroneous previously (either by autotracing or via span.markAsErroneous) and that earlier decision
+ * needs to be reverted.
+ * @param {string|Array.<string>} errorMessagePath the annotation path where the error message has been written to
+ *   earlier; there is usually no need to provide this argument as this will be handled automatically
+ */
+SpanHandle.prototype.markAsNonErroneous = function markAsNonErroneous(errorMessagePath) {
+  this.span.ec = 0;
+  // reset the error message as well
+  this._annotateErrorMessage(undefined, errorMessagePath);
+};
+
+/**
+ * @param {string?} errorMessage
+ * @param {string|Array.<string>} errorMessagePath
+ */
+SpanHandle.prototype._annotateErrorMessage = function _annotateErrorMessage(errorMessage, errorMessagePath) {
+  if (errorMessagePath) {
+    this.annotate(errorMessagePath, errorMessage);
+  } else {
+    findAndAnnotateErrorMessage(this.span, errorMessage);
+  }
+};
+
+/**
+ * @param {import('./cls').InstanaBaseSpan} span
+ * @param {string|Array.<string>} message
+ */
+function findAndAnnotateErrorMessage(span, message) {
+  const data = span.data;
+  if (!data) {
+    logger.warn(
+      'The error message annotation cannot be set in span.markAsErroneous/span.markAsNonErroneous, since the ' +
+        `${span.n} span has no data object.`
+    );
+    return;
+  }
+
+  let potentialSpanTypeSpecificDataKeys = Object.keys(data).filter(
+    key =>
+      // Some db instrumentations add a span.data.peer object in addition to their main section.
+      key !== 'peer' &&
+      // We are only interested in actual object properties, not string properties like span.data.service etc.
+      data[key] != null &&
+      typeof data[key] === 'object' &&
+      !Array.isArray(data[key])
+  );
+
+  if (potentialSpanTypeSpecificDataKeys.length === 0) {
+    logger.warn(
+      'The error message annotation cannot be set in span.markAsErroneous/span.markAsNonErroneous, since the ' +
+        `data object of the ${span.n} span has no keys. Please provide the path to the error message annotation ` +
+        'explicitly.'
+    );
+    return;
+  }
+  if (potentialSpanTypeSpecificDataKeys.length > 1 && potentialSpanTypeSpecificDataKeys.includes('sdk')) {
+    // Example: span.data.(http|rpc|mysql|whatever) _and_ span.data.sdk.custom.tags can legitimately exist on the same
+    // span when custom annotations have been added to an autotrace span.
+    // In that case, we want to add the error message to the autotrace span data.
+    potentialSpanTypeSpecificDataKeys = potentialSpanTypeSpecificDataKeys.filter(key => key !== 'sdk');
+  }
+  if (potentialSpanTypeSpecificDataKeys.length > 1) {
+    logger.warn(
+      'The error message annotation cannot be set in span.markAsErroneous/span.markAsNonErroneous, since the ' +
+        `data object of the ${span.n} span has more than one key: ${potentialSpanTypeSpecificDataKeys.join(
+          ', '
+        )}. Please provide the path to the error message annotation explicitly.`
+    );
+    return;
+  }
+
+  const spanTypeSpecificData = data[potentialSpanTypeSpecificDataKeys[0]];
+  if (message != null) {
+    spanTypeSpecificData.error = message;
+  } else {
+    delete spanTypeSpecificData.error;
+  }
+}
+
+/**
  * Switches the span into manual-end-mode. Calls to span#transmit() as used by automatic tracing instrumentation will be
@@ -311,2 +424,6 @@ * ignored. Instead, client code needs to finish the span (and trigger transmission) by calling spanHandle#end();
 
+NoopSpanHandle.prototype.markAsErroneous = function markAsErroneous() {};
+
+NoopSpanHandle.prototype.markAsNonErroneous = function markAsNonErroneous() {};
+
 NoopSpanHandle.prototype.disableAutoEnd = function disableAutoEnd() {
@@ -335,1 +452,7 @@ // provide dummy operation when automatic tracing is not enabled
 };
+
+// Only exported for testing purposese.
+exports._SpanHandle = SpanHandle;
+
+// Only exported for testing purposese.
+exports._NoopSpanHandle = NoopSpanHandle;

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

748619

increased by0.76%

Lines of code

19663

increased by0.57%

No dependency changes