Fix hardware metrics markdown?

[trask]

I may not have understood something here, but figured I'd send this PR to find out.

[bertysentry]

As the aggregation of hw.errors and hw.status over different hardware types is meaningful, we should keep it under the same metric. Thank you!

[bertysentry]

Not sure this change is made on purpose (other columns don't follow the same pattern), and same for other similar changes in table formatting.

[bertysentry]

No, there is absolutely no need to use namespaces everywhere.

It's much easier to query hw.status{state="failed"} to cover all devices, rather than hw.battery.status{state="failed"} + hw.cpu.status{state="failed"} + hw.memory.status{state="failed"} + ...

Same goes for all metrics that are common to different classes of hardware devices.

BTW, the very first version of the specification used namespaces heavily, and we simplified it and I think it's great. Let's not go backward and get it more complicated.

[trask]

As the aggregation of hw.errors and hw.status over different hardware types is meaningful, we should keep it under the same metric. Thank you!

got it, should I remove all the duplicate definitions of hw.errors and hw.status instruments then?

[bertysentry]

@trask You could remove the duplicate definitions (i.e. the description and unit). However, I recommend that hw.errors and hw.status are still explicitly listed for the different types of devices. Also, some types of devices include additional values for the error type or state attributes, so this information must remain.

[trask]

ok thanks for answering my questions @bertysentry, I'm going to close this, I suspect it may need to be revisited when converting the hardware metrics to yaml anyways (my understanding is that there can only be a single definition of the metric in yaml)

[joaopgrassi]

(my understanding is that there can only be a single definition of the metric in yaml)

@trask I guess you meant there can only be a single attribute definition in yaml? If so, yes that is correct. if, for example, hw.status has the same meaning on all metrics, we can easily achieve it by defining it in its own namespace hw.* and then re-used across all metrics.

BUT: If the attribute has different a different semantic/meaning/values on different metrics, then we are going to run into problems, as via ref it's not possible to override the member values, only the brief/requirement levels AFAIK. In that case, it will have to be defined under each namespace, like you did in this PR.

@bertysentry since you worked on this initially, can you answer if such attributes have the same meaning across all metrics they are used? That will help when migrating this conventions to YAML.

[bertysentry]

@joaopgrassi The attributes do have the same meaning across all device types. However, we may want to add an additional values that are specific a type of device. Example: we may want to specify the value charging for the state attribute in the hw.status metric, that is applicable to batteries only (charging).

In any case, we shouldn't add namespaces because of the tooling (YAML to Markdown)! 😅

[joaopgrassi]

The attributes do have the same meaning across all device types. However, we may want to add an additional values that are specific a type of device. Example: we may want to specify the value charging for the state attribute in the hw.status metric, that is applicable to batteries only (charging).

I see, thanks for checking. If the attributes that are "common" have the same semantic meaning in all metrics it should be fine then leaving as is - they are already in the hw.* namespace anyway so I guess fulfill the decision on #51 (comment).

But we still have the problem that re-defining enum values (or overwriting them) is currently not supported. So, if we want to keep the attribute as today, we would need to implement it open-telemetry/weaver#479 before we migrate these conventions to YAML.

[trask]

(my understanding is that there can only be a single definition of the metric in yaml)

@trask I guess you meant there can only be a single attribute definition in yaml?

@joaopgrassi hw.status is a metric (instrument), not a metric attribute

[joaopgrassi]

@joaopgrassi hw.status is a metric (instrument), not a metric attribute

A my mistake, I see it now. I thought it was just an attribute repeated over other metrics.

Then it's really a problem. I see that hw.status is a metric in the "general" namespace hw.* but it also appears down the other namespaces, with different set of attribute values for state. The way the page is today, I'm not sure we can migrate it to YAML without introducing a different namespace in all of them =/

The only solution I can see is: Don't include hw.status in each namespace (as is today) and only have it under the hw. namespace once. Then we can instruct in the page that other namespaces can also record it, but adding the corresponding hw.type.

[bertysentry]

@joaopgrassi Thank you for the clarification! I insist that we will not add a different namespace for each device type for the hw.status and hw.errors metrics.

Any chance we can add this ability to the yaml-2-markdown converter?

[joaopgrassi]

Well, everything is possible if we want to do it 😁 , the question is more if it makes sense. The tool today is heavily structured around unique ids to avoid clashes which makes sense to me. I think we can get away with it by doing what I mentioned above and have a mix of automatic vs manual things in the markdown.