{"id":16055532,"url":"https://github.com/uglow/smetrics","last_synced_at":"2026-01-16T00:56:37.430Z","repository":{"id":40753125,"uuid":"148235873","full_name":"uglow/smetrics","owner":"uglow","description":"Smetrics - use Google Sheets to store metrics data over time","archived":false,"fork":false,"pushed_at":"2023-01-06T01:35:21.000Z","size":1288,"stargazers_count":0,"open_issues_count":10,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-03-18T13:57:27.085Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/uglow.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-09-11T00:18:07.000Z","updated_at":"2021-07-23T00:48:24.000Z","dependencies_parsed_at":"2023-02-05T01:46:58.441Z","dependency_job_id":null,"html_url":"https://github.com/uglow/smetrics","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uglow%2Fsmetrics","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uglow%2Fsmetrics/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uglow%2Fsmetrics/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uglow%2Fsmetrics/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/uglow","download_url":"https://codeload.github.com/uglow/smetrics/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246786055,"owners_count":20833633,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-09T02:09:17.752Z","updated_at":"2026-01-16T00:56:37.393Z","avatar_url":"https://github.com/uglow.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# smetrics\n\n[![NPM Version](https://img.shields.io/npm/v/smetrics.svg?style=flat-square)](http://npm.im/smetrics)\n[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)\n[![Coverage Status](https://coveralls.io/repos/github/uglow/smetrics/badge.svg?branch=master)](https://coveralls.io/github/uglow/smetrics?branch=master)\n[![Dependencies status](https://david-dm.org/uglow/smetrics/status.svg?theme=shields.io)](https://david-dm.org/uglow/smetrics#info=dependencies)\n[![Dev-dependencies status](https://david-dm.org/uglow/smetrics/dev-status.svg?theme=shields.io)](https://david-dm.org/uglow/smetrics#info=devDependencies)\n[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)\n\n\u003e Records metrics to your Google Sheets spreadsheet \n\n`smetrics` is designed to persist metrics (test runs, test coverage, build times, load times, etc) using Google Sheets.\nGoogle Sheets provides cloud-storage for the data, allowing you to see the changes in the metrics over time (and graph them yourself).\n\n## Install\n\n`npm install smetrics --dev`\n\n\n## Usage\n\n``` js\n// File: processMetrics.js\n// Lets say you've just built your code, run your unit and performance tests.\n// Now you want to persist the results somewhere so you can see the changes over time.\n\nimport fs from 'fs';\nimport * as smetrics from '../src/index.js';\n\n// See Authentication section for how to generate this information\nconst creds = fs.readFileSync('./google-generated-creds.json').toString();\n// OR, if you cannot save the file locally (like on heroku)\nconst options = {\n  clientEmail: process.env.SMETRICS_GOOGLE_SERVICE_ACCOUNT_CLIENT_EMAIL,\n  privateKey: process.env.SMETRICS_GOOGLE_SERVICE_ACCOUNT_PRIVATE_KEY,\n  dateTimeFormat: 'googleDate', // defaults to 'milliseconds',\n  filePath: '/tmp/yourfile.json' // defaults to CWD + 'smetrics.json'\n}\n\n// Gather all the metrics then commit them to Google Sheets\naddUnitTestMetrics();\n\n// Commit the changes (async - returns a promise)\nsmetrics.commit('\u003cspreadsheet key\u003e', options)\n  .catch((err) =\u003e {\n    console.log(err);\n  });\n\n\nfunction addUnitTestMetrics() {\n  const stats = { numTotalTests: 100, numPassedTests: 99 };\n  const tabName = 'My Stats';\n  \n  smetrics.addMetric(tabName, 'Total tests', stats.numTotalTests);\n  smetrics.addMetric(tabName, 'Passed tests', stats.numPassedTests);\n}\n```\n\n### Important\n**The order that metrics are added is significant.** If you decide to change the order that you add metrics, you\nshould open the corresponding Google Sheet and change the column-order to match your new metric-capturing order.\n\n### Usage within AWS Lambda functions\n\nBecause this library persists state to a file, you need to specify the `filePath` when calling `addMetric` and `commit`\nwith a path underneath the `/tmp` directory:\n\n``` js\nimport fs from 'fs';\nimport * as smetrics from '../src/index.js';\n\n// NOTE: filePath is specified explicitly, under the '/tmp' folder\nsmetrics.addMetric(tabName, 'Total tests', stats.numTotalTests, { filePath: '/tmp/smetrics.json' });\n\n// See Authentication section for how to generate this information\nconst creds = fs.readFileSync('./google-generated-creds.json').toString();\n// OR, if you cannot save the file locally (like on heroku)\nconst options = {\n  clientEmail: process.env.SMETRICS_GOOGLE_SERVICE_ACCOUNT_CLIENT_EMAIL,\n  privateKey: process.env.SMETRICS_GOOGLE_SERVICE_ACCOUNT_PRIVATE_KEY,\n  dateTimeFormat: 'googleDate',\n\n  // NOTE: filePath is specified explicitly:\n  filePath: '/tmp/smetrics.json'\n}\nsmetrics.commit('\u003cspreadsheet key\u003e', options); // Async - returns a promise \n\n```\n\n## API\n\n### `addMetric(sheetName, column, value, options) : object`\n\nAdds a metric to the temporary metric-file \n\n- `sheetName` \u003cstring\u003e The name of the sheet within the spreadsheet\n- `column` \u003cstring\u003e The name of the column within the sheet\n- `value` \u003cany\u003e The value to store\n- `options` \u003cobject\u003e (optional):\n  - `timestamp` \u003ctimeMillis\u003e The timestamp to associate with the metric. Defaults to the current time.\n  - `filePath` \u003cstring\u003e The file path to write the metric data to. Defaults to current working directory 'smetrics.json'\n\n### `commit(spreadsheetKey, options) : void`\n\n- `spreadsheetId` \u003cstring\u003e The SpreadsheetId\n\nReads the metrics in the metric-data file ('smetrics.json') and persists it to the\ndesignated Google Sheet.\n\n- `sheetName` \u003cstring\u003e The name of the sheet within the spreadsheet\n- `options` \u003cobject\u003e:\n  - `clientEmail` \u003cstring\u003e This value is available in the JSON file that you can download when setting up Authentication with a service account.\n  - `privateKey` \u003cstring\u003e This value is available in the JSON file that you can download when setting up Authentication with a service account.\n  - `dateFormat` \u003cstring|function\u003e Default value 'milliseconds'.\n\nThe default format for DateTime columns is `milliseconds`, which is the number of milliseconds since the epoch (e.g. 1537165777561, \nwhich is equivalent to Mon Sep 17 2018 16:29:37 GMT+1000 (Australian Eastern Standard Time)).\n\nAlternately, you can specify the format as `googleDate`, which formats the date as `dd-mon-yyyy hh:mm:ss`. \nGoogle sheets interprets this string as a date, and can be used correctly when the data is charted. You\nmay need to manually format the DateTime column as a 'Date Time' in the Google Sheet (once-only).\n\nLastly, you can supply a function for `dateFormat`, which has the signature `(timeMillis: Number) =\u003e any`.\n\n## How it works\n\nEvery time a metric is added, a temporary file (`smetrics.json`, [example](fixtures/smetrics.json)) is created/updated in your \ncurrent working directory with the metric name and a value:\n\n```js\n// smetrics.json:\n[\n  [\n    { metric: 'Test Time (s)', value: 26 }, \n    { metric: 'Time to Interactive (ms)', value: 503 },\n    // ...\n  ]\n]\n```\n\nWhen `commit(spreadsheet, creds)` is called, the `smetrics.json` file is appended to the specified spreadsheet as\na new row, with the first column containing a date-time stamp (generated using `Date.now()`).\n\n\n## Hacking `smetrics`\n\nSince this package ultimately processes a file called `smetrics.json` when `smetrics.commit(...)` is called, \nyou are welcome to write to this file yourself, rather than call `smetrics.addMetric(...)`. If you stick to the same \nformat as [this example](fixtures/smetrics.json), and follow the authentication process, you\nmay even add multiple rows of metrics in one go (Why would you want to? I'm not sure).\n\n\n## Authentication\n\n### Service Account (recommended method)\n\nThis is a 2-legged OAuth method and designed to be \"an account that belongs to your application instead of to an individual end user\".\nUse this for an app that needs to access a set of documents that you have full access to.\n([read more](https://developers.google.com/identity/protocols/OAuth2ServiceAccount))\n\n__Setup Instructions__\n\n1. Go to the [Google Developers Console](https://console.developers.google.com/project)\n1. Select your project or create a new one (and then select it)\n1. Enable the Drive API for your project\n   1. In the sidebar on the left, expand APIs \u0026 auth \u003e APIs\n   1. Search for \"sheets\"\n   1. Click on \"Google Sheets API\"\n   1. Click the blue \"Enable API\" button\n1. Create a service account for your project:\n   1. In the sidebar on the left, expand IAM \u0026 Admin \u003e Service Accounts\n   1. Click \"Create Service Account\" button\n   1. Enter the service account name \u0026 a description for step 1 and press Create.\n   1. Skip steps 2 \u0026 3 by pressing Cancel\n   1. In the Service Accounts panel, select Actions \u003e Manages Key\n   1. Press Add Key \u003e Create New Key\n   1. Select the \"JSON\" key type option\n   1. Click blue \"Create\" button.\n   \nYour JSON key file is generated and downloaded to your machine (it is the only copy!)\nnote your service account's email address (also available in the JSON key file)\nShare the doc (or docs) with your service account using the email noted above.\n\nThe `private_key` field in the JSON file that is the private key.\n\n### Sharing the sheet with the service account\n\n1. Open the Google Sheet\n1. Press the Share button.\n1. In the Share dialog, type the service accounts email: your-service-account-name@google-app.iam.gserviceaccount.com\n1. Press Send.\n\n## Spreadsheet ID\n\nThe Spreadsheet ID can be found in the URL of the spreadsheet.\n\nE.g. docs.google.com/spreadsheets/d/:spreadsheetID:/edit#gid=0\n\n## Graphing the results\n\nOnce you have the data in your spreadsheet, you can provide read-access to allow other tools\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md).\n\n\n## License\n\nThis software is licensed under the MIT Licence. See [LICENSE](LICENSE).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuglow%2Fsmetrics","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuglow%2Fsmetrics","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuglow%2Fsmetrics/lists"}