docs(detector-alibaba): add details about semantic conventions

[maryliag]

Add details about the Semantic Version used

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 90.45%. Comparing base (dfb2dff) to head (d23dbb0).
Report is 102 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2130      +/-   ##
==========================================
- Coverage   90.97%   90.45%   -0.53%     
==========================================
  Files         146      147       +1     
  Lines        7492     7571      +79     
  Branches     1502     1589      +87     
==========================================
+ Hits         6816     6848      +32     
- Misses        676      723      +47     

see 33 files with indirect coverage changes

[blumamir]

I am not sure these are related together in the same header. what do you think about using the pattern in instrumentations, something like:

## Semantic Conventions

This package uses `@opentelemetry/semantic-conventions` version `1.22+`, which implements Semantic Convention [Version 1.7.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.7.0/semantic_conventions/README.md)

Attributes collected:

| Attribute        | Short Description                                                                |
| ---------------- | -------------------------------------------------------------------------------- |
| `foo`  | text text. |
| `bar`  | text text.                                      |      

[maryliag]

My thinking here (which is different from instrumentation) is that each detector have it's own list that we want to clarify, so the user knows what is being collected for each case, but that means that the list of parameters collected per detector and the table for semantic convention would be the same, so I had two options:

Option 1: List the attributes collected by each detector separately, and also mention which convention is used
Option 2: List the attributes collected by each detector separately, then have a section for semantic convention that combines all the values

So I went with option 1 to not have a lot of duplication.

Maybe an option 3 would be not add the "Semantic Convention" in the title, but still add the message above to clarify the version. What do you think?

[blumamir]

Option 1: List the attributes collected by each detector separately, and also mention which convention is used

If I understood you correctly, then the semantic convention note should be per detector, e.g. moved down to be hosted under the Alibaba Cloud Ecs Detector? and then if there are multiple detectors in the same package then we can state different semantic version for a different header of Detector in the docs.

Maybe an option 3 would be not add the "Semantic Convention" in the title, but still add the message above to clarify the version. What do you think?

That also sounds good to me. As there is just one detector here, It doesn't really matters. I think it would be interesting in a multi-detector package like @opentelemetry/resource-detector-aws package.

• If we want each npm package to implement the same semantic conventions version for all it's detectors, then we need just one note about this version, and then table per detector.
• If each detector can depend on a different semconv version, then we need to add it per detector.

Hope I understood you correctly 🙏

[maryliag]

The version of semantic convention will be the same for all detectors of the same package, but they may use it or not, so this is why it may vary bt detector. One could be using SEMRESATTRS_SERVICE_NAME and the other emanticResourceAttributes.SERVICE_NAME for example.

The package.json would still be the same for all detectors, so one line with the detail about the version on top of all detectors should suffice. As you mention, since this one only has one anyway is easier to just keep the position I added it to.

For this PR, I removed the title part and kept the description about the version.

[maryliag]

@blumamir let me know if you think this is good now, then I can rebase (I keep rebasing and gets out of sync quite quickly)