Add S3 Downstream Span Pointers

[nhulston]

What does this PR do?

Adds span pointers to spans for Lambdas triggered by putObject, copyObject, and completeMultipartUpload events.

Span pointers are similar to Span Links, but for cases when it is impossible to pass the Trace ID and Span ID between the spans that need to be linked.

When the calculated hashes for the upstream and downstream lambdas match, the Datadog backend will automatically link the two traces together.

When clicking on the linked span, a new tab opens linking to the downstream Lambda function that was triggered by this S3 object update.

Motivation

This feature already exists in Python, and I'm working on adding it to all other runtimes (Node, .NET, Java, Golang).

Testing Guidelines

Easy: Checkout this span, enable the feature flag, and you will see that it's pointing to the downstream Lambda.

More thorough: Run this Lambda function with the event payload

{
  "shouldPutObject": false,
  "shouldCopyObject": false,
  "shouldMultipartUpload": false,
  "useV2": true
}

and change one of the bools to true. Also, try both with AWS SDK v2 and v3. Enable the span pointers feature flag, and check Datadog to ensure that the spans are properly linked.

Additional Notes

• This handles the 'downstream' case, for Lambdas that make S3 requests. This PR adds span pointers on the upstream case.
• S3 and Dynamo are supported in Python. I will soon open another PR to add support for Dynamo.

Types of Changes

• Bug fix
• New feature
• Breaking change
• Misc (docs, refactoring, dependency upgrade, etc.)

Check all that apply

• This PR's description is comprehensive
• This PR contains breaking changes that are documented in the description
• This PR introduces new APIs or parameters that are documented and unlikely to change in the foreseeable future
• This PR impacts documentation, and it has been updated (or a ticket has been logged)
• This PR's changes are covered by the automated tests
• This PR collects user input/sensitive content into Datadog
• This PR passes the integration tests (ask a Datadog member to run the tests)

[apiarian-datadog]

the span pointer stuff looks fine, though some aspects of the api are a little strange. we may want someone with more js experience to take a look as well.

[apiarian-datadog]

why not let the generate pointer hash function actually run?

[nhulston]

I already have tests for generatePointerHash in the tracer; i just wanted to test only the logic behind the functions created in this PR. That way, if we ever make changes to how the generatePointerHash function works in the tracer, it won't break the tests here. And the changes will be automatically propagated to here, requiring no code updates.

[purple4reina]

@duncanista, can you help answer a question for me?

I recall when you added support for w3c trace propagation to datadog-lambda-js, you said that instead of directly importing the tracer from dd-trace, we create an interface to wrap it.

If that's correct, then is there any issue with us requiring other files from ddtrace here?

[duncanista]

There might be an issue when customer is not using the tracer (some do it), it would essentially crash, ideally, we'd have a better way to get this type of data

[nhulston]

@duncanista Could you take another look at the updated code from my latest commit? It should be safe and avoid any crashing:

  let S3_PTR_KIND;
  let SPAN_POINTER_DIRECTION;
  let generatePointerHash;
  try {
    const constants = require("dd-trace/packages/dd-trace/src/constants");
    const util = require("dd-trace/packages/dd-trace/src/util");

    ({ S3_PTR_KIND, SPAN_POINTER_DIRECTION } = constants);
    ({ generatePointerHash } = util);
  } catch (err) {
    if (err instanceof Error) {
      logDebug("Failed to load dd-trace span pointer dependencies", err);
    }
    return spanPointerAttributesList;
  }

[purple4reina]

@duncanista, Can you give more details (or point me to a doc somewhere) about how "customer is not using the tracer" is implemented? Do you mean they just aren't including ddtrace in their package.json file? I'd like to be able to create a small sample app that I can test this PR with that "is not using the tracer".

[duncanista]

Yeah correct, just the lambda library, not the tracer. Let me review the whole PR

[duncanista]

This should be fine – I'm approving to unblock, but this is not ideal on how we are importing it. I guess its fail-safe, yet this is not making it friendly to eventually make this package ESBuild compatible

[duncanista]

Please add integration tests for this, due to how you are requiring this packages from the external package