@redthreadlabs/tracelog 1.4.0

package/lib/instrumentation/modules/aws-sdk/dynamodb.js

@@ -0,0 +1,155 @@
+/*
+ * Copyright Elasticsearch B.V. and other contributors where applicable.
+ * Licensed under the BSD 2-Clause License; you may not use this file except in
+ * compliance with the BSD 2-Clause License.
+ */
+
+'use strict';
+
+const TYPE = 'db';
+const SUBTYPE = 'dynamodb';
+const ACTION = 'query';
+
+function getRegionFromRequest(request) {
+  return (
+    request &&
+    request.service &&
+    request.service.config &&
+    request.service.config.region
+  );
+}
+
+function getPortFromRequest(request) {
+  return (
+    request &&
+    request.service &&
+    request.service.endpoint &&
+    request.service.endpoint.port
+  );
+}
+
+function getMethodFromRequest(request) {
+  const method = request && request.operation;
+  if (method) {
+    return method[0].toUpperCase() + method.slice(1);
+  }
+}
+
+function getStatementFromRequest(request) {
+  const method = getMethodFromRequest(request);
+  if (
+    method === 'Query' &&
+    request &&
+    request.params &&
+    request.params.KeyConditionExpression
+  ) {
+    return request.params.KeyConditionExpression;
+  }
+  return undefined;
+}
+
+function getAddressFromRequest(request) {
+  return (
+    request &&
+    request.service &&
+    request.service.endpoint &&
+    request.service.endpoint.hostname
+  );
+}
+
+function getTableFromRequest(request) {
+  const table = request && request.params && request.params.TableName;
+  if (!table) {
+    return '';
+  }
+  return ` ${table}`;
+}
+
+// Creates the span name from request information
+function getSpanNameFromRequest(request) {
+  const method = getMethodFromRequest(request);
+  const table = getTableFromRequest(request);
+  const name = `DynamoDB ${method}${table}`;
+  return name;
+}
+
+function shouldIgnoreRequest(request, agent) {
+  return false;
+}
+
+// Main entrypoint for SQS instrumentation
+//
+// Must call (or one of its function calls must call) the
+// `orig` function/method
+function instrumentationDynamoDb(
+  orig,
+  origArguments,
+  request,
+  AWS,
+  agent,
+  { version, enabled },
+) {
+  if (shouldIgnoreRequest(request, agent)) {
+    return orig.apply(request, origArguments);
+  }
+
+  const ins = agent._instrumentation;
+  const name = getSpanNameFromRequest(request);
+  const span = ins.createSpan(name, TYPE, SUBTYPE, ACTION, { exitSpan: true });
+  if (!span) {
+    return orig.apply(request, origArguments);
+  }
+
+  const region = getRegionFromRequest(request);
+  const dbContext = {
+    type: SUBTYPE,
+    instance: region,
+  };
+  const dbStatement = getStatementFromRequest(request);
+  if (dbStatement) {
+    dbContext.statement = dbStatement;
+  }
+  span.setDbContext(dbContext);
+  span._setDestinationContext({
+    address: getAddressFromRequest(request),
+    port: getPortFromRequest(request),
+    cloud: {
+      region,
+    },
+  });
+
+  const onComplete = function (response) {
+    if (response && response.error) {
+      agent.captureError(response.error);
+    }
+    span.end();
+  };
+  // Bind onComplete to the span's run context so that `captureError` picks
+  // up the correct currentSpan.
+  const parentRunContext = ins.currRunContext();
+  const spanRunContext = parentRunContext.enterSpan(span);
+  request.on(
+    'complete',
+    ins.bindFunctionToRunContext(spanRunContext, onComplete),
+  );
+
+  const cb = origArguments[origArguments.length - 1];
+  if (typeof cb === 'function') {
+    origArguments[origArguments.length - 1] = ins.bindFunctionToRunContext(
+      parentRunContext,
+      cb,
+    );
+  }
+  return ins.withRunContext(spanRunContext, orig, request, ...origArguments);
+}
+
+module.exports = {
+  instrumentationDynamoDb,
+
+  // exported for testing
+  getRegionFromRequest,
+  getPortFromRequest,
+  getStatementFromRequest,
+  getAddressFromRequest,
+  getMethodFromRequest,
+};

package/lib/instrumentation/modules/aws-sdk/s3.js

@@ -0,0 +1,184 @@
+/*
+ * Copyright Elasticsearch B.V. and other contributors where applicable.
+ * Licensed under the BSD 2-Clause License; you may not use this file except in
+ * compliance with the BSD 2-Clause License.
+ */
+
+'use strict';
+
+// Instrument AWS S3 operations via the 'aws-sdk' package.
+
+const constants = require('../../../constants');
+
+const TYPE = 'storage';
+const SUBTYPE = 's3';
+
+// Return the PascalCase operation name from `request.operation` by undoing to
+// `lowerFirst()` from
+// https://github.com/aws/aws-sdk-js/blob/c0c44b8a4e607aae521686898f39a3e359f727e4/lib/model/api.js#L63-L65
+//
+// For example: 'headBucket' -> 'HeadBucket'
+function opNameFromOperation(operation) {
+  return operation[0].toUpperCase() + operation.slice(1);
+}
+
+// Return an APM "resource" string for the bucket, Access Point ARN, or Outpost
+// ARN. ARNs are normalized to a shorter resource name.
+//
+// Known ARN patterns:
+// - arn:aws:s3:<region>:<account-id>:accesspoint/<accesspoint-name>
+// - arn:aws:s3-outposts:<region>:<account>:outpost/<outpost-id>/bucket/<bucket-name>
+// - arn:aws:s3-outposts:<region>:<account>:outpost/<outpost-id>/accesspoint/<accesspoint-name>
+//
+// In general that is:
+//    arn:$partition:$service:$region:$accountId:$resource
+//
+// This parses using the same "split on colon" used by the JavaScript AWS SDK v3.
+// https://github.com/aws/aws-sdk-js-v3/blob/v3.18.0/packages/util-arn-parser/src/index.ts#L14-L37
+function resourceFromBucket(bucket) {
+  let resource = null;
+  if (bucket) {
+    resource = bucket;
+    if (resource.startsWith('arn:')) {
+      resource = bucket.split(':').slice(5).join(':');
+    }
+  }
+  return resource;
+}
+
+// Instrument an awk-sdk@2.x operation (i.e. a AWS.Request.send or
+// AWS.Request.promise).
+//
+// @param {AWS.Request} request https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Request.html
+function instrumentationS3(
+  orig,
+  origArguments,
+  request,
+  AWS,
+  agent,
+  { version, enabled },
+) {
+  const opName = opNameFromOperation(request.operation);
+  const params = request.params;
+  const bucket = params && params.Bucket;
+  const resource = resourceFromBucket(bucket);
+  let name = 'S3 ' + opName;
+  if (resource) {
+    name += ' ' + resource;
+  }
+
+  const ins = agent._instrumentation;
+
+  const span = ins.createSpan(name, TYPE, SUBTYPE, opName, { exitSpan: true });
+  if (!span) {
+    return orig.apply(request, origArguments);
+  }
+
+  // As for now OTel spec defines attributes for operations that require a Bucket
+  // if that changes we should review this guard
+  // https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/semantic_conventions/trace/instrumentation/aws-sdk.yml#L435
+  if (bucket) {
+    const otelAttrs = span._getOTelAttributes();
+
+    otelAttrs['aws.s3.bucket'] = bucket;
+
+    if (params.Key) {
+      otelAttrs['aws.s3.key'] = params.Key;
+    }
+  }
+
+  const onComplete = function (response) {
+    // `response` is an AWS.Response
+    // https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Response.html
+
+    // Determining the bucket's region.
+    // `request.httpRequest.region` isn't documented, but the aws-sdk@2
+    // lib/services/s3.js will set it to the bucket's determined region.
+    // This can be asynchronously determined -- e.g. if it differs from the
+    // configured service endpoint region -- so this won't be set until
+    // 'complete'.
+    const httpRequest = request.httpRequest;
+    const region = httpRequest && httpRequest.region;
+
+    span.setServiceTarget('s3', resource);
+    const destContext = {};
+    // '.httpRequest.endpoint' might differ from '.service.endpoint' if
+    // the bucket is in a different region.
+    const endpoint = httpRequest && httpRequest.endpoint;
+    if (endpoint) {
+      destContext.address = endpoint.hostname;
+      destContext.port = endpoint.port;
+    }
+    if (region) {
+      destContext.cloud = { region };
+    }
+    span._setDestinationContext(destContext);
+
+    if (response) {
+      // https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/HttpResponse.html
+      const httpResponse = response.httpResponse;
+      let statusCode;
+      if (httpResponse) {
+        statusCode = httpResponse.statusCode;
+
+        // Set HTTP context. Some context not being set, though it is available:
+        // - method: Not that helpful.
+        // - url: Mostly redundant with context.destination.address.
+        // - response.headers: A lot of added size for uncertain utility. The
+        //   inclusion of Amazon's request ID headers might be worth it.
+        const httpContext = {
+          status_code: statusCode,
+        };
+        const encodedBodySize =
+          Buffer.isBuffer(httpResponse.body) && httpResponse.body.byteLength;
+        if (encodedBodySize) {
+          // I'm not actually sure if this might be decoded_body_size.
+          httpContext.response = { encoded_body_size: encodedBodySize };
+        }
+        span.setHttpContext(httpContext);
+      }
+
+      // Follow the spec for HTTP client span outcome.
+      // https://github.com/elastic/apm/blob/main/specs/agents/tracing-instrumentation-http.md#outcome
+      //
+      // For example, a S3 GetObject conditional request (e.g. using the
+      // IfNoneMatch param) will respond with response.error=NotModifed and
+      // statusCode=304. This is a *successful* outcome.
+      if (statusCode) {
+        span._setOutcomeFromHttpStatusCode(statusCode);
+      } else {
+        // `statusCode` will be undefined for errors before sending a request, e.g.:
+        //  InvalidConfiguration: Custom endpoint is not compatible with access point ARN
+        span._setOutcomeFromErrorCapture(constants.OUTCOME_FAILURE);
+      }
+
+      if (response.error && (!statusCode || statusCode >= 400)) {
+        agent.captureError(response.error, { skipOutcome: true });
+      }
+    }
+
+    span.end();
+  };
+
+  // Run context notes: The `orig` should run in the context of the S3 span,
+  // because that is the point. The user's callback `cb` should run outside of
+  // the S3 span.
+  const parentRunContext = ins.currRunContext();
+  const spanRunContext = parentRunContext.enterSpan(span);
+  const cb = origArguments[origArguments.length - 1];
+  if (typeof cb === 'function') {
+    origArguments[origArguments.length - 1] = ins.bindFunctionToRunContext(
+      parentRunContext,
+      cb,
+    );
+  }
+  request.on(
+    'complete',
+    ins.bindFunctionToRunContext(spanRunContext, onComplete),
+  );
+  return ins.withRunContext(spanRunContext, orig, request, ...origArguments);
+}
+
+module.exports = {
+  instrumentationS3,
+};

package/lib/instrumentation/modules/aws-sdk/sns.js

@@ -0,0 +1,232 @@
+/*
+ * Copyright Elasticsearch B.V. and other contributors where applicable.
+ * Licensed under the BSD 2-Clause License; you may not use this file except in
+ * compliance with the BSD 2-Clause License.
+ */
+
+'use strict';
+
+const TYPE = 'messaging';
+const SUBTYPE = 'sns';
+const ACTION = 'publish';
+const PHONE_NUMBER = '<PHONE_NUMBER>';
+const MAX_SNS_MESSAGE_ATTRIBUTES = 10;
+
+function getArnOrPhoneNumberFromRequest(request) {
+  let arn = request && request.params && request.params.TopicArn;
+  if (!arn) {
+    arn = request && request.params && request.params.TargetArn;
+  }
+  if (!arn) {
+    arn = request && request.params && request.params.PhoneNumber;
+  }
+  return arn;
+}
+
+function getRegionFromRequest(request) {
+  return (
+    request &&
+    request.service &&
+    request.service.config &&
+    request.service.config.region
+  );
+}
+
+function getSpanNameFromRequest(request) {
+  const topicName = getDestinationNameFromRequest(request);
+  return `SNS PUBLISH to ${topicName}`;
+}
+
+function getMessageContextFromRequest(request) {
+  return {
+    queue: {
+      name: getDestinationNameFromRequest(request),
+    },
+  };
+}
+
+function getAddressFromRequest(request) {
+  return (
+    request &&
+    request.service &&
+    request.service.endpoint &&
+    request.service.endpoint.hostname
+  );
+}
+
+function getPortFromRequest(request) {
+  return (
+    request &&
+    request.service &&
+    request.service.endpoint &&
+    request.service.endpoint.port
+  );
+}
+
+function getMessageDestinationContextFromRequest(request) {
+  return {
+    address: getAddressFromRequest(request),
+    port: getPortFromRequest(request),
+    cloud: {
+      region: getRegionFromRequest(request),
+    },
+  };
+}
+
+function getDestinationNameFromRequest(request) {
+  const phoneNumber = request && request.params && request.params.PhoneNumber;
+  if (phoneNumber) {
+    return PHONE_NUMBER;
+  }
+
+  const topicArn = request && request.params && request.params.TopicArn;
+  const targetArn = request && request.params && request.params.TargetArn;
+
+  if (topicArn) {
+    const parts = topicArn.split(':');
+    const topicName = parts.pop();
+    return topicName;
+  }
+
+  if (targetArn) {
+    const fullName = targetArn.split(':').pop();
+    if (fullName.lastIndexOf('/') !== -1) {
+      return fullName.substring(0, fullName.lastIndexOf('/'));
+    } else {
+      return fullName;
+    }
+  }
+}
+
+function shouldIgnoreRequest(request, agent) {
+  if (request.operation !== 'publish') {
+    return true;
+  }
+
+  // is the named topic on our ignore list?
+  if (agent._conf && agent._conf.ignoreMessageQueuesRegExp) {
+    const queueName = getArnOrPhoneNumberFromRequest(request);
+    if (queueName) {
+      for (const rule of agent._conf.ignoreMessageQueuesRegExp) {
+        if (rule.test(queueName)) {
+          return true;
+        }
+      }
+    }
+  }
+
+  return false;
+}
+
+// Though our spec only mentions a 10-message-attribute limit for *SQS*, we'll
+// do the same limit here, because
+// https://docs.aws.amazon.com/sns/latest/dg/sns-message-attributes.html
+// mentions the 10-message-attribute limit for SQS subscriptions.
+function propagateTraceContextInMessageAttributes(
+  parentSpan,
+  msgParams,
+  log,
+  targetId,
+) {
+  const msgAttrs = msgParams.MessageAttributes;
+  if (
+    msgAttrs &&
+    Object.keys(msgAttrs).length + 2 > MAX_SNS_MESSAGE_ATTRIBUTES
+  ) {
+    log.warn(
+      'cannot propagate trace-context with SNS message to %s, too many MessageAttributes',
+      targetId,
+    );
+  } else {
+    parentSpan.propagateTraceContextHeaders(
+      msgAttrs,
+      function (msgAttrs, name, value) {
+        if (name.startsWith('elastic-')) {
+          return;
+        }
+        msgAttrs[name] = { DataType: 'String', StringValue: value };
+      },
+    );
+  }
+}
+
+function instrumentationSns(
+  orig,
+  origArguments,
+  request,
+  AWS,
+  agent,
+  { version, enabled },
+) {
+  if (shouldIgnoreRequest(request, agent)) {
+    return orig.apply(request, origArguments);
+  }
+
+  const ins = agent._instrumentation;
+  const log = agent.logger;
+  const parentRunContext = ins.currRunContext();
+  const name = getSpanNameFromRequest(request);
+  const span = ins.createSpan(name, TYPE, SUBTYPE, ACTION, { exitSpan: true });
+
+  // W3C trace-context propagation.
+  const parent =
+    span || parentRunContext.currSpan() || parentRunContext.currTransaction();
+  if (parent) {
+    // Currently only instrumenting a 'publish' operation, for which we want
+    // to propagate trace-context.
+    // https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/SNS.html#publish-property
+    const paramsCopy = Object.assign({}, request.params);
+    paramsCopy.MessageAttributes = Object.assign(
+      {},
+      paramsCopy.MessageAttributes,
+    );
+    request.params = paramsCopy;
+    const targetId = getArnOrPhoneNumberFromRequest(request);
+    propagateTraceContextInMessageAttributes(
+      parent,
+      request.params,
+      log,
+      targetId,
+    );
+  }
+
+  if (!span) {
+    return orig.apply(request, origArguments);
+  }
+
+  span._setDestinationContext(getMessageDestinationContextFromRequest(request));
+  span.setMessageContext(getMessageContextFromRequest(request));
+
+  const onComplete = function (response) {
+    if (response && response.error) {
+      agent.captureError(response.error);
+    }
+    span.end();
+  };
+  // Bind onComplete to the span's run context so that `captureError` picks
+  // up the correct currentSpan.
+  const spanRunContext = parentRunContext.enterSpan(span);
+  request.on(
+    'complete',
+    ins.bindFunctionToRunContext(spanRunContext, onComplete),
+  );
+
+  const cb = origArguments[origArguments.length - 1];
+  if (typeof cb === 'function') {
+    origArguments[origArguments.length - 1] = ins.bindFunctionToRunContext(
+      parentRunContext,
+      cb,
+    );
+  }
+  return ins.withRunContext(spanRunContext, orig, request, ...origArguments);
+}
+
+module.exports = {
+  instrumentationSns,
+
+  // exported for testing
+  getSpanNameFromRequest,
+  getDestinationNameFromRequest,
+  getMessageDestinationContextFromRequest,
+  getArnOrPhoneNumberFromRequest,
+};