[mdatagen] Add semconv reference for attributes in metadata schema

[osullivandonal]

Description

This PR adds support in mdatagen for defining semantic conventions references for attributes.

Updating your attribute in metadata.yaml:

attributes:
  state:
    description: Breakdown of memory usage by type.
    type: string
    enum: [buffered, cached, inactive, free, slab_reclaimable, slab_unreclaimable, used]
    semantic_convention:
      ref: system.md#system-memory-state

Important

This work also updates the semantic_convention: ref: to use a relative URL, this was done as we want to ensure the same semconv version from the metadata schema is used, otherwise the end user could have a full url in ref with one semconv version and the schema version being a different version. A new method has been introduced in mdatagen that builds the semconv url at runtime.

Creates this table in the generated docs for that component:

Attributes

Name	Description	Values	Requirement Level	Semantic Convention
state	Breakdown of memory usage by type.	Str: buffered, cached, inactive, free, slab_reclaimable, slab_unreclaimable, used	Recommended	state

Link to tracking issue

This work is linked to #13297 but doesn't close it.

Testing

• loader_test.go was updated with attributes for cpu and state.
• Also cmd/mdatagen/internal/samplereciever was updated and generate code created which creates tests.

Documentation

The documentation template has been updated to reference the semconv definition for attributes if provided in the schema.

[codecov]

Codecov Report

❌ Patch coverage is 65.89595% with 59 lines in your changes missing coverage. Please review.
✅ Project coverage is 91.35%. Comparing base (fc354be) to head (b7dc46e).

Files with missing lines	Patch %	Lines
...plereceiver/internal/metadata/generated_metrics.go	69.15%	31 Missing and 2 partials ⚠️
...mplereceiver/internal/metadata/generated_config.go	31.57%	24 Missing and 2 partials ⚠️

❌ Your patch check has failed because the patch coverage (65.89%) is below the target coverage (95.00%). You can increase the patch coverage or adjust the target coverage.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #14646      +/-   ##
==========================================
- Coverage   91.45%   91.35%   -0.11%     
==========================================
  Files         688      688              
  Lines       43824    43992     +168     
==========================================
+ Hits        40081    40187     +106     
- Misses       2631     2688      +57     
- Partials     1112     1117       +5     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[dmathieu]

While I agree that not having to specify a full URL every time, this assumes all semantic conventions are on the semantic-conventions repository, which may be problematic in the future with open-telemetry/opentelemetry-specification#4906

[ChrsMark]

I think we can proceed with this as is now and revisit once things are more clear in general about how we will link/define semconv and registries in Collector components in the future.

[osullivandonal]

Sounds good to me.

[ChrsMark]

I think that addition will be helpful at the moment to link existing attributes to defined Semantic Conventions.

I would like to use this already in https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/processor/k8sattributesprocessor/documentation.md as part of open-telemetry/opentelemetry-collector-contrib#44483.

@mx-psi @dmitryax please take a look

[ChrsMark]

Maybe we can be more explicit and use a - or something similar to state that there is no semantic convention definition for this. Having this just empty might raise questions.

[osullivandonal]

I agree, this is good to have, rows with an empty semantic_conventions ref now uses "-":

Attributes

Name	Description	Values	Requirement Level	Semantic Convention
string_attr	Attribute with any string value.	Any Str	Recommended	-
state	Integer attribute with overridden name.	Any Int	Recommended	-
enum_attr	Attribute with a known set of string values.	Str: red, green, blue	Recommended	-
slice_attr	Attribute with a slice value.	Any Slice	Recommended	-
map_attr	Attribute with a map value.	Any Map	Recommended	-

[ChrsMark]

Can we also add the full generated url as an example here?
i.e. the https://github.com/open-telemetry/semantic-conventions/blob/v1.38.0/docs/registry/attributes/system.md#system-memory-state

[osullivandonal]

Yup this makes sense, I have updated all references of this to have a full example.