Add Semantic conventions for TLS/SSL encrypted communication

[svrnm]

Fixes #1652

Changes

Add trace/span semantic conventions for TLS/SSL.

I created a similar PR (#1854) a long while back that stalled eventually, I wanted to give it another try. Before doing so I did some scrubbing, added some references, removed some things where I was uncertain and updated a few things to match the APIs or RFCs (e.g. "not_before" and "not_after" are used for validity instead of valid_from and valid_to)

Reference implementation: https://github.com/open-telemetry/opentelemetry-js-contrib/blob/main/plugins/node/opentelemetry-instrumentation-net/src/instrumentation.ts#L121

References:

• node.js tls api
• python api
• SSL_get_version
• rfc5246
• rfc5280

[github-actions]

This PR was marked stale due to lack of activity. It will be closed in 7 days.

[svrnm]

@open-telemetry/specs-approvers any feedback?:)

[github-actions]

This PR was marked stale due to lack of activity. It will be closed in 7 days.

[github-actions]

This PR was marked stale due to lack of activity. It will be closed in 7 days.

[svrnm]

anything missing, any additional feedback?

[joaopgrassi]

Please also add a changelog entry: https://github.com/open-telemetry/opentelemetry-specification/blob/main/CHANGELOG.md?plain=1#L29

[github-actions]

This PR was marked stale due to lack of activity. It will be closed in 7 days.

[joaopgrassi]

Now that the ECS OTEP was merged, do we also want maybe to adopt the attributes from there for these? https://www.elastic.co/guide/en/ecs/current/ecs-tls.html

[svrnm]

Now that the ECS OTEP was merged, do we also want maybe to adopt the attributes from there for these? https://www.elastic.co/guide/en/ecs/current/ecs-tls.html

@joaopgrassi
makes sense to me, what would need to be done for that?

[trask]

Now that the ECS OTEP was merged, do we also want maybe to adopt the attributes from there for these? https://www.elastic.co/guide/en/ecs/current/ecs-tls.html

@joaopgrassi

makes sense to me, what would need to be done for that?

@joaopgrassi thx for bringing that up here!

@svrnm check out open-telemetry/semantic-conventions#1012 and #3409 for some examples, and see if it makes sense to rename the new attributes you've proposed to align with the ECS names.

We will bring over ECS attributes more proactively in the future, but for now we just want to avoid new divergence in cases where alignment makes sense.

[svrnm]

@joaopgrassi , @trask thank you!

I gave it a try, a few notable changes:

• ECS does not use "peer" and "host" but "server" and "client", I used the first initially to be consistent with net.*, but doing some reading on TLS the use of "server" and "client" is more reasonable, because they have distinct meaning and distinct properties in a secure communication
• I skipped some attributes from ECS for now, namely because they require arrays, which I was not sure if we have that already in the SemConv
• The hashes are formatted differently, I picked the one of ECS over the one suggested here initially

[github-actions]

This PR was marked stale due to lack of activity. It will be closed in 7 days.

[joaopgrassi]

LGTM, thanks for putting the effort on this!

About the array attributes, I think we should be OK in adding them, as there's already some conventions using it like

opentelemetry-specification/semantic_conventions/resource/cloud_provider/aws/logs.yaml

Line 9 in abf540c

type: string[]

and also HTTP headers.

I'm not an expert in this, so I don't know how crucial those array attributes are, but I guess the goal is to take over all ECS attributes. @trask @AlexanderWert what do you think?

[svrnm]

LGTM, thanks for putting the effort on this!

About the array attributes, I think we should be OK in adding them, as there's already some conventions using it like

opentelemetry-specification/semantic_conventions/resource/cloud_provider/aws/logs.yaml

Line 9 in abf540c

type: string[]

and also HTTP headers.
I'm not an expert in this, so I don't know how crucial those array attributes are, but I guess the goal is to take over all ECS attributes. @trask @AlexanderWert what do you think?

I added certificate and certificate_chain now, please give it a look.

[reyang]

@svrnm heads up - most likely this PR will be closed, and we'll ask you to resubmit the PR in a new repo, please refer to #3474 (comment).

[svrnm]

@svrnm heads up - most likely this PR will be closed, and we'll ask you to resubmit the PR in a new repo, please refer to #3474 (comment).

I assumed that, let me find some time to bring it over to the new semconv repo!

[jsuereth]

Please move this to https://github.com/open-telemetry/semantic-conventions

[svrnm]

moved to https://github.com/open-telemetry/semantic-conventions