docs(nvd-cve-osv): document how to extract conversion metrics (google…

…#2937)

This adds some basic documentation on how to reproducibly extract CVE
conversion metrics

vulnfeeds/cmd/nvd-cve-osv/README.md

@@ -6,7 +6,7 @@ See [run_cve_to_osv_generation.sh](https://github.com/google/osv.dev/blob/master
 
 To see it in action on a single CVE:
 
-```
+```shell
 CVE=CVE-2024-3094
 
 git clone --recurse-submodules https://github.com/google/osv.dev
@@ -25,3 +25,36 @@ go run cmd/nvd-cve-osv/main.go \
     --out_dir "/tmp/nvd2osv"
 
 cat /tmp/nvd2osv/*/*/${CVE}.json
+```
+
+# Conversion metric retrieval
+
+This extracts the per-year metrics from the logs and presents them as a percentage over successful conversions from ones considered to be in scope (having a viable Git repository associated with them by CPE or by presence in a reference URL).
+
+This requires at least these IAM roles:
+
+- [Logs Viewer (`roles/logging-viewer`)](https://cloud.google.com/logging/docs/access-control#logging.viewer)
+- [Service Usage Consumer (`roles/serviceusage.serviceUsageConsumer`)](https://cloud.google.com/iam/docs/understanding-roles#serviceusage.serviceUsageConsumer) (or [any other role](https://cloud.google.com/iam/docs/permissions-reference) granting the `serviceusage.services.use` permission)
+
+For more information, see:
+
+- [Cloud Logging CLI documentation](https://cloud.google.com/logging/docs/reference/tools/gcloud-logging)
+- [Cloud Logging access control documentation](https://cloud.google.com/logging/docs/access-control)
+
+```shell
+$ gcloud --project oss-vdb logging read --freshness=12h --format=json 'logName="projects/oss-vdb/logs/nvd-cve-osv" "Metrics:"' | jq -r '. | map(.textPayload | gsub("[\\n]"; "")) | .[]' | awk '{
+  match($1, /nvdcve-2\.0-(....)\.json/, year);
+  match($5, /CVEsForKnownRepos:([0-9]+)/, cves_in_scope);
+  match($6, /OSVRecordsGenerated:([0-9]+)/, osvs);
+  print year[1], 100*osvs[1]/cves_in_scope[1]
+}' | tail -n $[$(date +%Y) - 2016 + 1]
+2016 81.6214
+2017 77.1155
+2018 64.1689
+2019 71.334
+2020 73.4837
+2021 74.2835
+2022 75.2699
+2023 73.034
+2024 52.2844
+```