diff --git a/src/__tests__/unit/lib/boavizta/index.test.ts b/src/__tests__/unit/lib/boavizta/index.test.ts index b3500bb..8599bbb 100644 --- a/src/__tests__/unit/lib/boavizta/index.test.ts +++ b/src/__tests__/unit/lib/boavizta/index.test.ts @@ -153,6 +153,12 @@ describe('lib/boavizta: ', () => { ]) ).toStrictEqual([ { + timestamp: '2021-01-01T00:00:00Z', + duration: 15, + 'cpu/utilization': 34, + 'instance-type': 't2.micro', + country: 'USA', + provider: 'aws', 'carbon-embodied': 1.6, energy: 1.6408333333333334, }, diff --git a/src/lib/boavizta/README.md b/src/lib/boavizta/README.md index b3decca..0527d9d 100644 --- a/src/lib/boavizta/README.md +++ b/src/lib/boavizta/README.md @@ -17,29 +17,30 @@ Boavizta exposes a [REST API](https://doc.api.boavizta.org/). If the `boavizta` ### Inputs -- `cpu/name`: the name of the physical processor being used -- `cpu/number-cores`: number of physical cores on a CPU -- `cpu/expected-lifespan`: the lifespan of the component, in seconds +- `cpu/name`: the name of the physical processor being used (required for `BoaviztaCpuOutput`) +- `cpu/number-cores`: number of physical cores on a CPU (required for `BoaviztaCpuOutput`) +- `cpu/expected-lifespan`: the lifespan of the component, in seconds (optional) - `country`: the country used to lookup grid carbon intensity, e.g. "USA" (optional - falls back to Boavizta default) -- `cpu/utilization`: percentage CPU utilization for a given observation -- `instance-type`: the name of the specific instance +- `cpu/utilization`: percentage CPU utilization for a given observation (required) +- `instance-type`: the name of the specific instance (required for `BoaviztaCloudOutput`, optional for `BoaviztaCpuOutput`) +- `provider`: the name of cloud provider (required for `BoaviztaCloudOutput`) ## Returns - `carbon-embodied`: carbon emitted in manufacturing the device, in gCO2eq - `cpu/energy`: energy used by CPU in kWh -## Usage +## Usage for `BoaviztaCpuOutput` -To run the `boavista-cpu` plugin an instance of `BoaviztaCpuImpact` must be created using `BoaviztaCpuImpact()` and, if applicable, passing global configurations. Subsequently, the `execute()` function can be invoked to retrieve data on `carbon-embodied` and `cpu/energy`. +To run the `boavista-cpu` plugin an instance of `BoaviztaCpuOutput` must be created using `BoaviztaCpuOutput()` and, if applicable, passing global configurations. Subsequently, the `execute()` function can be invoked to retrieve data on `carbon-embodied` and `cpu/energy`. This is how you could run the plugin in Typescript: ```typescript -import {BoaviztaCpuImpact} from '@grnsft/if-unofficial-plugins'; +import {BoaviztaCpuOutput} from '@grnsft/if-unofficial-plugins'; -const output = BoaviztaCpuImpact({}); -const usage = await output.calculate([ +const output = BoaviztaCpuOutput({}); +const usage = await output.execute([ { timestamp: '2021-01-01T00:00:00Z', duration: 1, @@ -115,3 +116,60 @@ npm i -g @grnsft/if npm i -g @grnsft/if-unofficial-plugins ie --manifest ./examples/manifests/test/boavizta.yml --output ./examples/outputs/boavizta.yml ``` + +## Usage for `BoaviztaCloudOutput` + +To run the `boavista-cloud` plugin an instance of `BoaviztaCloudOutput` must be created using `BoaviztaCloudOutput()` and, if applicable, passing global configurations. Subsequently, the `execute()` function can be invoked to retrieve data on `carbon-embodied` and `cpu/energy`. + +This is how you could run the plugin in Typescript: + +```typescript +import {BoaviztaCloudOutput} from '@grnsft/if-unofficial-plugins'; + +const output = BoaviztaCloudOutput({}); +const usage = await output.execute([ + { + timestamp: '2021-01-01T00:00:00Z', + duration: 15, + 'cpu/utilization': 34, + 'instance-type': 't2.micro', + country: 'USA', + provider: 'aws', + }, +]); +``` + +## Example `manifest` + +In IF plugins are expected to be invoked from an `manifest` file. This is a yaml containing the plugin configuration and inputs. The following `manifest` initializes and runs the `boavizta-cloud` plugin: + +```yaml +name: boavizta cloud demo +description: calls boavizta api +tags: +initialize: + plugins: + 'boavizta-cloud': + method: BoaviztaCloudOutput + path: '@grnsft/if-unofficial-plugins' +tree: + children: + child: + pipeline: + - boavizta-cloud + defaults: + instance-type: r6g.medium + provider: aws + inputs: + - timestamp: '2021-01-01T00:00:00Z' + duration: 15 # Secs + cpu/utilization: 34 +``` + +You can run this by passing it to `ie`. Run impact using the following command run from the project root: + +```sh +npm i -g @grnsft/if +npm i -g @grnsft/if-unofficial-plugins +ie --manifest ./examples/manifests/test/boavizta-cloud.yml --output ./examples/outputs/boavizta-cloud.yml +``` diff --git a/src/lib/boavizta/boavizta-api.ts b/src/lib/boavizta/boavizta-api.ts index ed6c87a..0cf4499 100644 --- a/src/lib/boavizta/boavizta-api.ts +++ b/src/lib/boavizta/boavizta-api.ts @@ -22,9 +22,14 @@ export const BoaviztaAPI = () => { componentType: string, verbose: boolean ): Promise => { + const dataCast = { + core_units: data['cpu/number-cores'], + name: data['cpu/name'], + tdp: data['cpu/thermal-design-power'], + }; const response = await axios.post( `${BASE_URL}/component/${componentType}?verbose=${verbose}&duration=${data['usage']['hours_use_time']}`, - data + dataCast ); return response.data; diff --git a/src/lib/boavizta/index.ts b/src/lib/boavizta/index.ts index c835e57..e9301c1 100644 --- a/src/lib/boavizta/index.ts +++ b/src/lib/boavizta/index.ts @@ -148,7 +148,10 @@ export const BoaviztaCloudOutput = ( fetchData ); - result.push(usageResult); + result.push({ + ...input, + ...usageResult, + }); } return result;