{"id":18640534,"url":"https://github.com/rexagod/cpv","last_synced_at":"2025-11-04T20:30:28.241Z","repository":{"id":182113107,"uuid":"667953238","full_name":"rexagod/cpv","owner":"rexagod","description":"A utility to help teams make the most out of CMO's Collection Profiles featureset.","archived":false,"fork":false,"pushed_at":"2023-11-20T09:47:57.000Z","size":4204,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-12-27T10:09:24.991Z","etag":null,"topics":["metrics","openshift"],"latest_commit_sha":null,"homepage":"https://github.com/openshift/enhancements/pull/1298","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rexagod.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2023-07-18T17:12:37.000Z","updated_at":"2024-01-17T10:41:15.000Z","dependencies_parsed_at":"2023-10-03T00:12:50.099Z","dependency_job_id":"4e2367bd-5fdc-40c1-8722-9abd9da82f5c","html_url":"https://github.com/rexagod/cpv","commit_stats":null,"previous_names":["rexagod/cpv"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rexagod%2Fcpv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rexagod%2Fcpv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rexagod%2Fcpv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rexagod%2Fcpv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rexagod","download_url":"https://codeload.github.com/rexagod/cpv/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239441663,"owners_count":19639122,"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":["metrics","openshift"],"created_at":"2024-11-07T05:54:50.798Z","updated_at":"2025-11-04T20:30:28.211Z","avatar_url":"https://github.com/rexagod.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `cpv`: Collection Profiles Validator \u003c!--vale off--\u003e\n\n[![Continuous Integration](https://github.com/rexagod/cpv/workflows/ci/badge.svg)](https://github.com/rexagod/cpv/actions) [![Code Quality](https://goreportcard.com/badge/github.com/rexagod/cpv)](https://goreportcard.com/report/github.com/rexagod/cpv) [![API Reference](https://pkg.go.dev/badge/github.com/rexagod/cpv.svg)](https://pkg.go.dev/github.com/rexagod/cpv)\n\n`cpv` is a command line tool for working with [collection profiles](https://github.com/openshift/enhancements/blob/719b231e3b06cf274e77f0d89e46a0d258002572/enhancements/monitoring/scrape-profiles.md?plain=1).\n\n## Usage\n\n`cpv` expects the following set of flags.\n\n\u003c!-- help.md --\u003e\n```\nUsage of ./cpv:\n  -address string\n    \tAddress of the Prometheus instance. (default \"http://localhost:9090\")\n  -allow-list-file string\n    \tPath to a file containing a list of allow-listed metrics that will always be included within the extracted metrics set. Requires -profile flag to be set.\n  -bearer-token string\n    \tBearer token for authentication.\n  -kubeconfig string\n    \tPath to kubeconfig file. Defaults to $KUBECONFIG.\n  -noisy\n    \tEnable noisy assumptions: interpret the absence of the collection profiles label as the default 'full' profile (when using the -status flag).\n  -output-cardinality\n    \tOutput cardinality of all extracted metrics to a file.\n  -profile string\n    \tCollection profile that the command is being run for.\n  -quiet\n    \tSuppress all output, and use $EDITOR for generated manifests.\n  -rule-file string\n    \tPath to a valid rule file to extract metrics from, for eg., https://github.com/prometheus/prometheus/blob/v0.45.0/model/rulefmt/testdata/test.yaml. Requires -profile flag to be set.\n  -status\n    \tReport collection profiles' implementation status. -profile may be empty to report status for all profiles.\n  -target-selectors string\n    \tTarget selectors used to extract metrics, for eg., https://github.com/prometheus/client_golang/blob/644c80d1360fb1409a3fe8dfc5bad4228f282f3b/api/prometheus/v1/api_test.go#L1007. Requires -profile flag to be set.\n  -validate\n    \tValidate the collection profile implementation. Requires -profile flag to be set.\n  -version\n    \tPrint version information.\n```\n\n\n### Scenarios\n\nWhile the utility can be used with the various aforementioned flag combinations to fulfill the desired use-case, the following ones may comparatively be more prominent within the general workflow and thus, have been documented in order to get the developers up-and-running with in no time.\n\n#### Extraction\n\nThe utility can be used to extract metrics based a set of given parameters that include:\n* `-allow-list-file`: Path to a file containing a list of metrics that will always be included within the extracted metrics set, even if they are not present in the Prometheus instance forwarded at `-address`.\n* `-rule-file`: Path to a file containing a set of [`RuleGroup`](https://github.com/prometheus/client_golang/blob/v1.17.0/api/prometheus/v1/api.go#L569)s. All metrics used to define `expr`essions within the `rules` will be extracted. For example, [`model/rulefmt/testdata/test.yaml`](https://github.com/prometheus/prometheus/blob/v0.45.0/model/rulefmt/testdata/test.yaml) will result in the extraction of two metrics: `errors_total` and `requests_total`.\n* `-target-selectors`: A set of constraints (resembling [`VectorSelector`](https://github.com/prometheus/prometheus/blob/32ee1b15de6220ab975f3dac7eb82131a0b1e95f/promql/parser/ast.go#L126)s) satisfying the `matchTarget` parameter in [`TargetsMetadata`](https://github.com/prometheus/client_golang/blob/0356577e9b46283f8efae268b73ffee773a6feb7/api/prometheus/v1/api.go#L501). For example. `\"{job=\\\"prometheus\\\", severity=\\\"critical\\\"}\"` will result in the extraction of all metrics present in the Prometheus instance forwarded at `-address`, that have the `job` label set to `prometheus` and the `severity` label set to `critical`.\n\nAll these flags are mutually exclusive and require the `-profile` flag to be set. Once extracted, the metrics are used to generate a [`RelabelConfig`](https://github.com/prometheus-operator/prometheus-operator/blob/pkg/apis/monitoring/v0.66.0/pkg/apis/monitoring/v1/prometheus_types.go#L1267) that [can be dropped into the `ServiceMonitor` or `PodMonitor` resource](https://github.com/openshift/cluster-monitoring-operator/pull/1785/files#diff-2ced247f66ba1c3c56d30d7ae8c78af6a5eb5e561060d5d64f5caa4cd42626b9R15).\n\n```bash\n$ ./cpv -profile=\"$PROFILE\" -rule-file=\"$RULE_FILE\" -target-selectors=\"$TARGET_SELECTORS\" -allow-list-file=\"$ALLOW_LIST_FILE\"\n```\n\n```yaml\nsourcelabels:\n    - __name__\nseparator: \"\"\ntargetlabel: \"\"\nregex: (foo|bar|...)\nmodulus: 0\nreplacement: \"\"\naction: keep\n```\n\nAdditionally, `-output-cardinality` may be specified to output the cardinality of all extracted metrics to a file, in order to better assess decisions around keeping or dropping certain metrics within the `ServiceMonitor` or `PodMonitor` resource(s) for a particular profile.\n\n```\nMETRIC  CARDINALITY\nfoo     40\nbar     10\n...\n```\n\n#### Status\n\nThe utility can be used to evaluate the extent to which a collection profile has been implemented for every default `ServiceMonitor` or `PodMonitor` resource that has [opted-in to Collection Profiles feature](https://github.com/rexagod/cpv/blob/74ff86c9a7f99635b40f991efc6eb14c859bb496/internal/profiles/utils.go#L48). For example, with respect to the [`default` Kube State Metrics `ServiceMonitor`](https://github.com/JoaoBraveCoding/cluster-monitoring-operator/blob/ad0a06d61793336a7d520cb37d48a053b1b233d1/assets/kube-state-metrics/service-monitor.yaml#L9) (notice the explicit opt-in label), the utility, seeing that this has opted-in to the Collection Profiles feature, will check for the presence of all corresponding [`SupportedNonDefaultCollectionProfiles`](https://github.com/rexagod/cpv/blob/373d577560bae10f10769aeeab33781df7d4dc8f/internal/profiles/types.go#L24) for that `ServiceMonitor` and report the status for each of them (whether they exist or not).\n\nFor **all** profiles to be \"fully implemented\" (i.e., when `-status` is used without specifying a particular `-profile=$PROFILE`) all of the default opted-in `ServiceMonitor` or `PodMonitor` resources (i.e., with `monitoring.openshift.io/collection-profile` label set to `full`) must have the same corresponding resources for every such profile. Here, \"corresponding resources\" mean the `ServiceMonitor` or `PodMonitor` resources that have their `metadata.name` same as their default opted-in `ServiceMonitor` or `PodMonitor` resource counterpart appended by the profile they fulfill, and with the `monitoring.openshift.io/collection-profile` label set to the profile being checked for.\n\nSo, for example, for an opted-in default `ServiceMonitor` resource with `metadata.name` as `kube-state-metrics` and `monitoring.openshift.io/collection-profile: full` present within its label set, the corresponding `ServiceMonitor` resources for the, say, `minimal` profile would be `kube-state-metrics-minimal`. The utility will check for the presence of all corresponding resources for every profile with the default resources' `metadata.name` as the base and report the status for each of them.\n\n```bash\n$ ./cpv -profile=\"$PROFILE\" -status\n```\n\n```\nPROFILE   SERVICE MONITOR  POD MONITOR  ERROR\n$PROFILE  foo-monitor                   not implemented\n$PROFILE                   bar-monitor  not implemented\n...\n```\n\nAdditionally, a `-noisy` flag may be specified to interpret the absence of `monitoring.openshift.io/collection-profile: full` within the default `ServiceMonitor` or `PodMonitor` resources as the default `full` profile. This is useful when the `ServiceMonitor` or `PodMonitor` resources have not been updated to opt-in to the Collection Profiles feature yet.\n\n#### Validation\n\nThe utility can be used to validate against any discrepancies that impact the specified `ServiceMonitor` or `Podmonitor` resources. For this purpose, the utility expects the `-profile` flag, i.e, the profile that the validation should run against, and the `-validate` flag to be set. The validation works by reporting the hierarchy of any missing metrics that the specified `-profile` depends on, the absence of which in turn may end up impacting the resources dependent on those metrics.\n\n```bash\n$ ./cpv -profile=\"$PROFILE\" -validate\n```\n\n```\n$PROFILE MONITOR  GROUP  LOCATION                                                    RULE                         QUERY                                                                                                         METRIC                                            ERROR\netcd-minimal      etcd   .../openshift-etcd-operator-etcd-prometheus-rules-....yaml  etcdMemberCommunicationSlow  histogram_quantile(0.99, rate(etcd_network_peer_round_trip_time_seconds_bucket{job=~\".*etcd.*\"}[5m])) \u003e 0.15  etcd_network_peer_round_trip_time_seconds_bucket  not loaded\n...\n```\n\n## License\n\n[GNU GPLv3](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frexagod%2Fcpv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frexagod%2Fcpv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frexagod%2Fcpv/lists"}