Attribute names in semantic guidelines should be hierarchical

[sebastien-rosset]

What are you trying to achieve?

Fix the names of the attributes in the semantic guidelines to make them hierarchical. Some names are not hierarchical in hardware, system.

What did you expect to see?

Under the hardware semantic guidelines, the names of the attributes should be hierarchical.

Elsewhere, HTTP, RPC, Database, System, Process, Runtime Environment, FaaS are consistently using hierarchical names, with state noted as an exception. However, in the Hardware guidelines, many names have a flat structure, which is not compliant with the naming guidelines.

If exceptions to the naming hierarchy requirement are allowed, IMO that should be explicit in the spec.

Additional context.

The spec states:

Metric names and attributes exist within a single universe and a single hierarchy. Metric names and attributes MUST be considered within the universe of all existing metric names. When defining new metric names and attributes, consider the prior art of existing standard metrics and metrics from frameworks/libraries.

Defining lots of attributes with no name hierarchy has the side effect of preventing any future use of that word as a namespace. These attributes are declared with a flat naming structure:

1. In hardware: direction, vendor, model, serial_number, vendor, firmware_version, bios_version, driver_version, firmware_version, id, name, parent, chemistry, capacity, limit_type, state, sensor_location, type, task, raid_level, logical_addresses, physical_addresses, smart_attribute.
2. In system: state, type, direction, device, cpu, mode, mountpoint, protocol, status.
3. In process: state, direction, type.
4. In runtime environment: state, pool, type, daemon, gc, action.

capacity is defined as the capacity in Watts-hours or Amper-hours, which is highly specific to batteries. However, the word capacity is contextual, it could mean something entirely different in another namespace. It seems that by allowing names to be flat, more flat-names will be created in short order, which inevitably will lead to collisions or other naming problems. At some point, shouldn't there be a registry of namespaces, similar to what was done at the IETF or IEEE?

Device

1. The device attribute is defined under disk controller metrics
2. The device.id attribute is defined in device attributes

This means the word device is both a namespace and attribute name. This breaks this attribute naming rule:

Names SHOULD NOT coincide with namespaces. For example, if service.instance.id is an attribute name then it is no longer valid to have an attribute named service.instance because service.instance is already a namespace. Adhering to this rule necessitates careful choice of names: every existing name prohibits existence of an equally named namespace in the future, and vice versa: any existing namespace prohibits existence of an equally named attribute key in the future.

State

Out of curiosity, I looked at all the possible values for state:

state: idle | user | system | ...
state: used | cached | free | ...
state: idle, used (for database connection pool)
state: idle, user, system, interrupt, etc
state: used, free, cached, etc.
state: used, free, reserved
state: close, close_wait, closing, delete, established, fin_wait_1, fin_wait_2, last_ack, listen, syn_recv, syn_sent, time_wait.
state: system, user, wait
state: ok, degraded, failed
state: charging, discharging
state: ok, degraded, failed, charging, discharging
state: ok, degraded, failed, predicted_failure
state: ok, degraded, failed, open
state: remaining
state: ok, degraded, failed, needs_cleaning

[trask]

3. In process: state, direction, type.

I created PR #3431 to explore what namespaced metric attributes could look like for process metrics

[jmacd]

I wonder if there's a way for us to preserve the short attribute names we have and add an attribute-namespace concept to be determined at the instrument-level, for example. A hardware metric can use "state" and we'll know that it's a hardware "state" because of perhaps a scope-level attribute ("attribute.namespace=hardware").

[dyladan]

Attribute names are indeed namespaced now. If you have any examples not yet converted please open issues for them in the semconv repo.