{"id":15145754,"url":"https://github.com/soundcloud/collins_exporter","last_synced_at":"2025-10-19T16:32:15.982Z","repository":{"id":66309406,"uuid":"132118655","full_name":"soundcloud/collins_exporter","owner":"soundcloud","description":"Simple Collins exporter for Prometheus","archived":false,"fork":false,"pushed_at":"2024-02-02T03:16:36.000Z","size":6857,"stargazers_count":8,"open_issues_count":0,"forks_count":5,"subscribers_count":91,"default_branch":"master","last_synced_at":"2025-01-29T21:23:47.004Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","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/soundcloud.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-05-04T09:23:47.000Z","updated_at":"2022-05-20T03:57:02.000Z","dependencies_parsed_at":null,"dependency_job_id":"cf0e7dae-1677-4537-bea0-a1043b597e76","html_url":"https://github.com/soundcloud/collins_exporter","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soundcloud%2Fcollins_exporter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soundcloud%2Fcollins_exporter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soundcloud%2Fcollins_exporter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soundcloud%2Fcollins_exporter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/soundcloud","download_url":"https://codeload.github.com/soundcloud/collins_exporter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237172118,"owners_count":19266614,"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-09-26T11:42:32.356Z","updated_at":"2025-10-19T16:32:13.686Z","avatar_url":"https://github.com/soundcloud.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"Prometheus Collins Exporter\n===========================\n\nThis is a [Collins](https://github.com/tumblr/collins/) exporter for\n[Prometheus](https://prometheus.io).\n\nThis exporter usually retrieves the necessary data from Collins (called a\n“Collins scrape”) upon each scrape of the `/metrics` endpoint (the “Prometheus\nscrape”). However, Collins can become slow at times, especially if multiple\nrequests are overlapping. Therefore, whenever a Prometheus scrape hits the\nexporter while a Collins scrape is still ongoing, no new Collins scrape will be\nstarted, but all pending Prometheus scrapes will get metrics from the current\nCollins scrape once it has finished. (This adds jitter, but exporting from a\npotentially slow backend has jitter anyway. Arguably, not applying this\nprotection against overloading Collins will make things even worse.)\n\nDespite this precaution, a Collins scrape might still take longer than 10s for\nlarge inventories. Take that into account when configuring the scrape timeout\non your Prometheus server.\n\n## Installing\n\nYou need a Go development environment. Then, run the following to get the\nsource code and build and install the binary:\n\n    go get github.com/soundcloud/collins_exporter`\n\n## Running\n\nA minimal invocation is simply:\n\n    ./collins_exporter\n\nSupported parameters include:\n\n - `web.listen-address`: the address/port to listen on (default: `\":9136\"`)\n - `web.telemetry-path`: the path under which to expose metrics (default:\n   `\"/metrics\"`)\n - `collins.config`: the path to your Collins config, if not in a standard\n   location (see https://tumblr.github.io/collins/tools.html#configs)\n\n## Digging into the data\n\nThe exporter exposes three major groups of metrics, `collins_asset_status`,\n`collins_asset_state`, and `collins_asset_details`, with the Collins asset tag\nbeing used as a label for each one.\n\n### Asset info\n\nThe `collins_asset_details` metrics always have a value of one. But they\ncontain useful information about each asset in their labels. A typical metric\nlooks like this:\n\n```\ncollins_asset_details{instance=\"collins.example.com:9139\",ipmi_address=\"10.1.2.3\",job=\"collins\",nodeclass=\"web-server\",primary_address=\"10.10.20.30\",tag=\"ABCD1234\"}\n```\n\nThe information encoded in this series can be used to find assets by attributes\nother then the asset tag, as demonstrated in the example queries below.\n\n### Status\n\nThere is one `collins_asset_status` metric per asset tag and per possible\nCollins status. Since there are (currently) nine different Collins statuses,\nthe query `collins_asset_status{tag=\"ABCD1234\"}` will yield nine metrics, each\nwith a different `status` label like `\"New\"` or `\"Allocated\"`. The value of\neach but one of the metrics will be 0. The one metric with a value of 1\nrepresents the status the asset is currently in.\n\nA useful query to get started is to list the number of assets per status per\nnodeclass:\n\n```\ncount(((collins_asset_status == 1) * on(tag) group_right(status) collins_asset_details)) by (job, nodeclass, status)\n```\n\nIn fact, it's so useful you might want to use a recording rule for it:\n\n```\nstatus_nodeclass:collins_asset_status:count = count(((collins_asset_status == 1) * on(tag) group_right(status) collins_asset_details)) by (job, nodeclass, status)\n```\n\nBased on that, you could for example display the percentage of unallocated\n(available) assets per nodeclass on a dashboard:\n\n```\nsum(status_nodeclass:collins_asset_status:count{status=\"Unallocated\"}) without (status) / sum(status_nodeclass:collins_asset_status:count) without (status)\n```\n\nSometimes you need to get the status of a machine but don't know the asset tag\nyet. Here is a sample query for the asset status using only the primary IP\naddress. It returns the asset tag, the status name, and the nodeclass as\nlabels:\n\n```\ncollins_asset_details{primary_address=\"10.1.2.3\"} * on(tag) group_right(nodeclass) collins_asset_status == 1\n```\n\n\n### State\n\nUnlike the fixed number of statuses, there can be an arbitrary number of\nuser-defined Collins states. Thus, the `collins_asset_state` metrics follow a\ndifferent approach. There is exactly one metric per asset, and its value\nreflects the ID of the state. We are still looking for a good way of exposing\nthe state by name, too.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoundcloud%2Fcollins_exporter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsoundcloud%2Fcollins_exporter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoundcloud%2Fcollins_exporter/lists"}