Closed jawache closed 7 months ago
Something to discuss, I've used colon as a seperator above (cpu:energy
) however in yaml : has a special meaning and is used all the time so it would look like cpu:energy: 100
. Technically it's fine since colon only has special meaning if it's followed by a space, if it's inside a key then it's fine.
This has some good rules https://www.yaml.info/learn/quote.html
It seems that the best option is to use /
instead of :
grid:carbon-intensity
-> grid/carbon-intensity
cpu:energy:j
-> cpu/energy/j
Going through the current parameters, according to the above rules it should be at least:
Or should it be:
i.e. is embodied and operational, a domain and carbon the metric? or is it fair to say that operational-carbon is a metric?
If the first is ok, then why wouldn't
be ok?
Why is something a domain vs just a more specific particle in a parameter?
Generally I'm leaning to
but I can't figure out a rule as to why that makes sense to me over
Bumping to Sprint 7
now just requires docs at if.greensoftware.foundation
Closing as complete
Story
As a plugin author, I want guidance regarding how I should name my parameters so as to be a healthy participant in the ecosystem
Rationale
As we develop plugins, each plugin will output more parameters, and those parameters become standards that are consumed in downstream plugins. Very quickly, we are going to have 100's if not 1000's of parameters, and we need some rules regarding how they are named.
Implementation details
This naming convention is being proposed after reviewing the current choice of names and their units and a review of metrology literature. The intention is to propose a standard that aligns somewhat with convention, somewhat with existing metrology rules, doesn't require significant changes to the existing ecosystem of plugins for IF, and is future-proofed.
One big issue with the current units.yml is the inconsistency with naming. Taking one example, we have two params currently
cpu-util
andenergy-cpu
. In the first, the cpu is at the start; in the second, the cpu is at the end. We have no rules for where the termcpu
should go. This is the reason we need a naming convention.Types Of Parameters
Looking at the existing units.yml, there seem to be two broad types of parameters.
Each of these will have a different naming convention
Naming Convention - Measurement Parameters
{domain}:{metric}:{type}
{metric}
: metric is a quantifiable measure such as utilization, carbon intensity, bandwidth, or carbon. This is mandatory{domain}
: narrows the scope of a metric to a specific domain, e.g. cpu, mem, grid, cloud, electricity, embodied. This is optional.{type}
: defines the type of parameter; for measurement params, it is likely to link to a specific unit of measurement, e.g., g, lbs, kWh, joules. But could also be a string or any other type in the most generic term. This isn't to be confused with SI units, although there is a relationship. This is optional.datacenter-server-cpu
is preferred overcpu-server-datacenter
.metric
, but the other two particles are optional.carbon
, when used as a parameter, the scope is global (global in respect to the impact graph, it's the carbon for whatever the entire graph is being created to measure) and the type isgCO2e
.carbon-intensity
is a more complex derived metric (a rate), so we used a longer term to define it.energy
is a fundamental metric, so we allow a single word to define it.Examples
energy
is a{metric}
, with a default domain ofglobal
and a unit defaults tokWh
. It's equivalent toglobal:energy:kWh
energy:j
is a{metric}:{unit}
, with a default scope ofglobal
, and the unit isjoules
.cpu:energy
is a{domain:metric}
, the energy consumed by a CPU and the unit defaults tokWh
cpu:energy:j
is a{domain}:{metric}:{unit}
, the energy consumed by a CPU and the type isjoules
carbon
is a{metric}
, with a default domain ofglobal
and a default unit ofgCO2e
. It's effectively short forglobal:carbon:gCO2e
grid:carbon-intensity
is a{domain}:{metric}
with a default unit ofgCO2/kWh
. It's effectively short forgrid:carbon-intensity:gCO2e/kWh
software:carbon-intensity
is a{domain}:{metric}
with a default unit ofR
. It's effectively short forgrid:carbon-intensity:R
(R in this case is defined by the manifest file)cpu:utilization
is a{domain}:{metric}
with a default unit ofpercentage
.Naming Convention - Context Parameters
Context parameters will most likely have a type of
string
, although they may have numeric constants also.{domain}:{context}
{domain}
: narrows the scope of a field to a specific domain, e.g. cloud, cpu etc..{context}
: an id to uniquely identify this context vs. another.cloud-vendor-azure
is preferred overazure-cloud-vendor
.Examples
cloud:instance-type
cpu:physical-processor
Priority
5 since this will form part of the standard that hackathon participants should adopt.
Scope
This affects all the model plugins. The changes proposed here would result in existing model plugins needing to be updated to match the new convention.
Size
Documenting 1d Aligning all the existing model plugins 1-2d.
What does "done" look like?
Does this require updates to documentation or other materials??
Yes, we will need docs in the main if docs repo.
What testing is required?
All model unit tests will need to be updated so they pass.
Is this a known/expected update?
Somewhat discussed in several other places https://github.com/Green-Software-Foundation/if/issues/403