[chore] Clean up Entity snippets - make sure they include identifying vs. descriptive roles

[jsuereth]

• Re-use same macros both in registry and entity snippets.
• Make sure identifying/descriptive attributes show up in snippets.
• Ensure warning about identifying/descriptive attributes and stability shows up in snippets.
• Move all attributes for an entity into a single table.

[lmolkova]

WDYT about something like

Attribute	Type	Description	Examples	Requirement Level	Stability
service.name	string	Logical name of the service. [1]	shoppingcart	Required
service.instance.id	string	The string ID of the service instance. [2]	627cc493-f310-47de-96bd-71410b7dec09	Recommended
service.namespace	string	A namespace for service.name. [3]	Shop	Recommended
service.version	string	The version string of the service API or implementation. The format is not defined by these conventions.	2.0.0; a01dbef8a	Recommended

vs (in the current version)

	Attribute	Type	Description	Examples	Requirement Level	Stability
identity
	service.name	string	Logical name of the service. [1]	shoppingcart	Required
	service.instance.id	string	The string ID of the service instance. [2]	627cc493-f310-47de-96bd-71410b7dec09	Recommended
	service.namespace	string	A namespace for service.name. [3]	Shop	Recommended
description
	service.version	string	The version string of the service API or implementation. The format is not defined by these conventions.	2.0.0; a01dbef8a	Recommended

it might work similar to @joaopgrassi 's proposal for sampling-relevant attrs here
#2678 (comment)

[jsuereth]

@lmolkova I'd prefer to have it (a) sorted so identity is first and (b) a clear separation between identity + description. I think, going forward, it's going to be important to delineate what these mean to folks using entities.

Anyone in @open-telemetry/entities-maintainers have thoughts?

[joaopgrassi]

Also I guess we want to align the columns with #2867?

[jsuereth]

@lmolkova PTAL at latest incarnation of the table - it's a blend of what you did and what I did

[thompson-tomo]

Some general comments to tackle repeated empty lines.

Also is it still the plan to remove the resource pages as per #2327

[jsuereth]

Also is it still the plan to remove the resource pages as per #2327

Yes, with the caveat - there's a lot more urgent things to sort out first.

[joaopgrassi]

I liked the badges 😞. Hopefully we can find a long-term solution with the html limitation with the OTel website. CC @chalin we cannot use html inside markdown tables, right?

[chalin]

@joaopgrassi - OTel.io isn't the limitation. Here's my take on all this. IMHO:

• The tables are complicated enough already. Adding raw HTML is just going to make editing them more of a challenge.

• I see this repo as the raw source of the semconv -- that's why pages are written in Markdown rather than a markup language or Rich Text Format. We should avoid stylistic embellishments and focus on semantics/content.

• Previewing markdown pages via GH is a convenience. As you know GH preview has limitations that are by design: you can't use custom styling, nor redirects, etc. In order to use features such as styles, etc., GH recommends using GH Pages or, like we do, other tools such as Hugo.

We can fix the badge styling in OTel.io using CSS. (We could even implement an auto-rendering of badges for certain (solo) keywords like "Stable" and "Development" that might appear in tables (maybe via a special marker !Stable))

Thoughts?

As I looked at the semconv pages on OTel.io, I just noticed that badges aren't rendering properly. I'll create an issue for that.

/cc @open-telemetry/docs-maintainers

[chalin]

@jsuereth wrote:

Do you remember why we needed to avoid HTML tags in our markdown for opentelemetry.io?

You can have HTML inside a Markdown table cell.

Maybe you are remembering #2536? The problem there was that links inside HTML-encoded tables weren't getting processed correctly.

[chalin]

Let me know if you want me to look into the badge-size issue. FYI, I'll be fixing the current bug with badge display via:

• [semconv] Badges aren't being displayed properly opentelemetry.io#8288

[jsuereth]

@chalin AH yes, I think you're right. I couldn't emember the details and wanted to avoid breaking opentelemetry.io. Thanks for the links, so images are ok, but that gets into your other comment.

I absolutely agree with what you're saying - github pages are a convenience and we need rich markup going forward. If you think this is fixable on opentelemetry.io I'm happy to defer to that. I agree these tables are already too complicated.