👍🏼 Update IF to report runtime information to outputs

[jmcook1186]

Sub of: #629 -> #650

Why

As a user I want to capture everything needed to audit and verify the results from my IF run. Currently, the IF outputs do not include information about the machine the code is run on, versions, environment details etc.

Context
Providing granular runtime details in the output file will help to audit and verify IF outputs.

SoW

• Implement the feature in IF source code
• Test and QA
• Documentation is updated to describe new info in outputs

Prerequisites

None

Acceptance Criteria

• Output manifest file records all the information required to understand and replicate the environment it was run in.

GIVEN the user is in a folder
WHEN they compute the manifest file
THEN the output manifest file has these nodes

• execution

  • command: The exact command line used to run
  • environment: Information about the runtime environment
    • os: Name of OS
    • os-version: Version of OS
    • node version: Version of Node
    • date-time: Datetime of the run including timezone.
    • dependancies: The dependancies gathered from running npm list
      • <package-name> : <package-version>
      • @grnsft/if-plugins: @v0.3.2 (git+ssh://[email protected]/Green-Software-Foundation/if-plugins.git#8056a9593e3d41786d32dddb3e080bba75a8aa54)
      • @grnsft/if-unofficial-plugins: 0.3.1

• Documentation is updated to describe new info in outputs.

Example Manifest
There are no changes required to the manifest format, but when it is executed additional information should be added to the output file. We can use the following manifest as an example (this is basic.yml from IF repo):

name: basic-demo
description:
tags:
initialize:
  plugins:
    teads-curve: 
      path: '@grnsft/if-unofficial-plugins'
      method: TeadsCurve
      global-config:
        interpolation: spline
tree:
  children:
    child-0:
      defaults:
        cpu/thermal-design-power: 100
      pipeline:
        - teads-curve
      inputs:
        - timestamp: 2023-07-06T00:00
          duration: 1
          cpu/utilization: 20
        - timestamp: 2023-07-06T00:01
          duration: 1
          cpu/utilization: 80
        - timestamp: 2023-07-06T00:02
          duration: 1
          cpu/utilization: 20

The output file should look as follows:

name: basic-demo
description:
tags:
initialize:
  plugins:
    teads-curve: 
      path: '@grnsft/if-unofficial-plugins'
      method: TeadsCurve
      global-config:
        interpolation: spline
execution:
  command: ie --manifest examples/basic.yml
  environment:
    os: ubuntu
    os-version: 22.04.6
    node version: v21.4.0
    date-time: 2023-12-12T00:00:00.000Z (UTC)
    dependencies: 
      - '@babel/[email protected]'
      - '@babel/[email protected]'
      - '@commitlint/[email protected]'
      - '@commitlint/[email protected]'
      - '@grnsft/[email protected]'
      - '@grnsft/[email protected]'
      - '@jest/[email protected]'
      - '@types/[email protected]'
      - '@types/[email protected]'
      - '@types/[email protected]'
      - '@types/[email protected]'
      - [email protected]
      - [email protected]
      - [email protected]
      - [email protected]
      - [email protected]
      - [email protected]
      - [email protected]
      - [email protected]
      - [email protected]
      - [email protected]
      - [email protected]
      - [email protected]
      - [email protected]
tree:
  children:
    child-0:
      defaults:
        cpu/thermal-design-power: 100
      pipeline:
        - teads-curve
      inputs:
        - timestamp: 2023-07-06T00:00
          duration: 1
          cpu/utilization: 20
        - timestamp: 2023-07-06T00:01
          duration: 1
          cpu/utilization: 80
        - timestamp: 2023-07-06T00:02
          duration: 1
          cpu/utilization: 20
      outputs:
        - timestamp: 2023-07-06T00:00
          duration: 1
          cpu/utilization: 20
          cpu/thermal-design-power: 100
          cpu/energy: 0.000013270071138211382
        - timestamp: 2023-07-06T00:01
          duration: 1
          cpu/utilization: 80
          cpu/thermal-design-power: 100
          cpu/energy: 0.000025568089430894314
        - timestamp: 2023-07-06T00:02
          duration: 1
          cpu/utilization: 20
          cpu/thermal-design-power: 100
          cpu/energy: 0.000013270071138211382

[jawache]

@jmcook1186 the acceptance criteria for this for me is:

• Output manifest files record important logs an an execution node.
• execution
  • command: The exact command used to run
  • environment: Information about the runtime environment
    • os: Name of OS
    • os-version: Version of OS
    • node version: Version of Node
    • date-time: Datetime of the run including timezone.
• execution node has enough information to replicate the runtime environment as close as possible.
• documentation is updated to describe new info in outputs.

Once the ticket is updated to the new format and the acceptance criteria added I'll 👍🏽

[jmcook1186]

@jawache ok updated and awaiting approval

[jmcook1186]

added example manifest and output file to the ticket

[zanete]

Revising one field, making the OS more clear. a solution is reserved to be tried out

[jawache]

@jmcook1186 thanks for adding example manifest files but I think dependencies need to be a map, I believe the way you wrote it is as a long single multiline string.

So each entry like

@grnsft/[email protected] extraneous -> ./../if-plugins

Should be either as a list

• @grnsft/[email protected] extraneous -> ./../if-plugins

Or I think a map is more useful like so:

"@grnsft/if-plugins": "v0.3.2 extraneous -> ./../if-plugins"

So the key being the path we would have put in to load the plugin and the value being the version and optionally the part from where it was installed.

[jmcook1186]

ah, I see what you mean - yes it was intended to be a list, not a multiline string. I believe @narekhovhannisyan implemented it as a list in his PR #665.

@narekhovhannisyan can you confirm how a package installed from github looks in your implementation - does it satisfy the requirements described here?

[narekhovhannisyan]

@jmcook1186 GitHub links were ignored, pushed update for it

[zanete]

@jmcook1186 please confirm what should happen with the timezones in the output
cc @MariamKhalatova

[zanete]

Note that the feature is implemented in a way that if required information is not present, we use the defaults that Node.js provides:

os.platform()#
Added in: v0.5.0
Returns: <string>
Returns a string identifying the operating system platform for which the Node.js binary was compiled. The value is set at compile time. Possible values are 'aix', 'darwin', 'freebsd','linux', 'openbsd', 'sunos', and 'win32'.

The return value is equivalent to process.platform.

The value 'android' may also be returned if Node.js is built on the Android operating system. Android support is experimental.

[jmcook1186]

IIUC the timezone is always converted to UTC before being reported in the manifest. As long as the documentation makes this clear I don't think it matters about the explicit inclusion of the timezone in the manifest. However, for clarity, let';s add (UTC) after the ISO8061 string in the date-time value.

[zanete]

Waiting to confirm if the documentation is also addressed

[jmcook1186]

@jmcook1186 to identify where docs are required

[jmcook1186]

The relevant documentation should be added in a new section between context and tree on this page https://if.greensoftware.foundation/major-concepts/manifest-file
@narekhovhannisyan

[narekhovhannisyan]

@jmcook1186
Green-Software-Foundation/if-docs#72