Add details about extracting topic name in the SNS publish API

[estolfo]

Another update to the AWS services spec with details about the topic name in SNS.

[apmmachine]

💚 Build Succeeded

the below badges are clickable and redirect to their specific view in the CI or DOCS

Expand to view the summary

Build stats

• Build Cause: Started by timer

• Start Time: 2021-04-26T05:46:00.778+0000

• Duration: 3 min 56 sec

• Commit: a219569

Trends 🧪

[eyalkoren]

As long as we maintain consistency with the messaging spec, should the name be: SNS PUBLISH to <TOPIC-NAME>?

[trentm]

https://github.com/elastic/apm/blob/master/specs/agents/tracing-instrumentation-messaging.md#naming says the name should be <MSG-FRAMEWORK> SEND/RECEIVE/POLL to/from <QUEUE-NAME>, so should the name here be SNS SEND to <TOPIC-NAME>?

[trentm]

From team discussion earlier today it was decided to use SNS PUBLISH to <TOPIC-NAME> (with span.action = 'publish'). According to #446, Ruby is already doing this. Go doesn't have the " to".

[astorm]

👍

[trentm]

I'm no expert here, but I don't think accesspoints for SNS are a thing. AFAICT there are:

1. s3 access points (https://aws.amazon.com/s3/features/access-points/) which result in ARNs with the format arn:aws:s3:region:account-id:accesspoint/access-point-name/object/resource (per https://docs.amazonaws.cn/en_us/AmazonS3/latest/userguide/using-access-points.html)
2. EFS access points (https://docs.aws.amazon.com/efs/latest/ug/efs-access-points.html) which result in ARNs with the format ^arn:aws[-a-z]*:elasticfilesystem:[0-9a-z-:]+:access-point/fsap-[0-9a-f]{8,40}$ (per https://docs.aws.amazon.com/efs/latest/ug/API_CreateAccessPoint.html#API_CreateAccessPoint_ResponseSyntax)

Neither of these are usable with SNS Publish (https://docs.aws.amazon.com/sns/latest/api/API_Publish.html), as far as I can tell.

Does anyone have an example or a reference that shows access point ARNs are relevant for SNS Publish? If not, I think we should remove mention of them here.

[trentm]

A possible alternative section for span.name, which also addresses a cardinality issue that I think exists for TargetArn usage (i.e. sending to mobile devices):

Raw spec text:

- `span.name`: ([SNS Publish API reference](https://docs.aws.amazon.com/sns/latest/api/API_Publish.html))
    - For a publish call including a `TopicArn`, the span name MUST be `SNS PUBLISH $topicName`. For example, for a TopicArn of `arn:aws:sns:us-east-2:123456789012:My-Topic` the topicName is `My-Topic`. (Implementation note: this can extracted with the equivalent of this Python expression: `topicArn.split(':').pop()`.)
    - For a publish call including a `TargetArn` (an endpoint ARN created via CreatePlatformEndpoint), the span name MUST be `SNS PUBLISH $applicationName`. For example, for a TargetArn of `arn:aws:sns:us-west-2:123456789012:endpoint/GCM/gcmpushapp/5e3e9847-3183-3f18-a7e8-671c3a57d4b3` the applicationName is `endpoint/GCM/gcmpushapp`. The endpoint UUID represents a device and mobile app. For manageable cardinality, the UUID must be excluded from the span name. (Implementation note: this can be extracted with the equivalent of this Python expression: `targetArn.split(':').pop().rsplit('/', 1)[0]`)
    - For a publish call including a `PhoneNumber`, the span name MUST be `SNS PUBLISH <PHONE_NUMBER>`. The actual phone number MUST NOT be included because it is [PII](https://en.wikipedia.org/wiki/Personal_data) and cardinality is too high. 

Rendered spec text:

• span.name: (SNS Publish API reference)
  • For a publish call including a TopicArn, the span name MUST be SNS PUBLISH $topicName. For example, for a TopicArn of arn:aws:sns:us-east-2:123456789012:My-Topic the topicName is My-Topic. (Implementation note: this can extracted with the equivalent of this Python expression: topicArn.split(':').pop().)
  • For a publish call including a TargetArn (an endpoint ARN created via CreatePlatformEndpoint), the span name MUST be SNS PUBLISH $applicationName. For example, for a TargetArn of arn:aws:sns:us-west-2:123456789012:endpoint/GCM/gcmpushapp/5e3e9847-3183-3f18-a7e8-671c3a57d4b3 the applicationName is endpoint/GCM/gcmpushapp. The endpoint UUID represents a device and mobile app. For manageable cardinality, the UUID must be excluded from the span name. (Implementation note: this can be extracted with the equivalent of this Python expression: targetArn.split(':').pop().rsplit('/', 1)[0])
  • For a publish call including a PhoneNumber, the span name MUST be SNS PUBLISH <PHONE_NUMBER>. The actual phone number MUST NOT be included because it is PII and cardinality is too high.

[trentm]

Thoughts on [PhoneNumber] or [PHONENUMBER] instead of <PHONE_NUMBER>?

• We already use [REDACTED] as a replacement value elsewhere -- i.e. with square brackets.
• I like that PhoneNumber matches the API doc parameter name.

[trentm]

The cardinality issues apply to context.destination.service.resource as well.

[trentm]

From team discussion today, there were no objections to the proposed text above. Eyal expressed a slight preference for [PHONENUMBER] (all caps) for the placeholder string. I'll add a new PR comment here with a proposed diff.

[trentm]

(GitHub PRs don't allow a suggested diff over a deleted line.) Suggested replacement:

- `span.name`:
    - For a publish action including a `TopicArn`, the span name MUST be `SNS PUBLISH to $topicName`. For example, for a TopicArn of `arn:aws:sns:us-east-2:123456789012:My-Topic` the topicName is `My-Topic`. (Implementation note: this can extracted with the equivalent of this Python expression: `topicArn.split(':').pop()`.)
    - For a publish action including a `TargetArn` (an endpoint ARN created via [CreatePlatformEndpoint](https://docs.aws.amazon.com/sns/latest/api/API_CreatePlatformEndpoint.html)), the span name MUST be `SNS PUBLISH to $applicationName`. For example, for a TargetArn of `arn:aws:sns:us-west-2:123456789012:endpoint/GCM/gcmpushapp/5e3e9847-3183-3f18-a7e8-671c3a57d4b3` the applicationName is `endpoint/GCM/gcmpushapp`. The endpoint UUID represents a device and mobile app. For manageable cardinality, the UUID must be excluded from the span name. (Implementation note: this can be extracted with the equivalent of this Python expression: `targetArn.split(':').pop().rsplit('/', 1)[0]`)
    - For a publish action including a `PhoneNumber`, the span name MUST be `SNS PUBLISH to [PHONENUMBER]`. The actual phone number MUST NOT be included because it is [PII](https://en.wikipedia.org/wiki/Personal_data) and cardinality is too high. 

[trentm]

Suggested change

	- **`span.action`**: 'publish'

[estolfo]

Superseded by #478