{"id":18834473,"url":"https://github.com/fgouteroux/foreman_exporter","last_synced_at":"2026-01-26T11:30:17.608Z","repository":{"id":212308517,"uuid":"731148912","full_name":"fgouteroux/foreman_exporter","owner":"fgouteroux","description":"Exposes Foreman Prometheus Metrics with caching and HA (memberlist). ","archived":false,"fork":false,"pushed_at":"2024-04-18T07:19:14.000Z","size":635,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-12-30T07:42:18.742Z","etag":null,"topics":["foreman","prometheus-exporter"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fgouteroux.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-12-13T13:12:57.000Z","updated_at":"2024-06-12T14:29:39.000Z","dependencies_parsed_at":"2024-01-15T14:42:26.330Z","dependency_job_id":"2abf4f8b-f7ff-4d78-812c-d632101e3f82","html_url":"https://github.com/fgouteroux/foreman_exporter","commit_stats":null,"previous_names":["fgouteroux/foreman_exporter"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fgouteroux%2Fforeman_exporter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fgouteroux%2Fforeman_exporter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fgouteroux%2Fforeman_exporter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fgouteroux%2Fforeman_exporter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fgouteroux","download_url":"https://codeload.github.com/fgouteroux/foreman_exporter/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239768923,"owners_count":19693764,"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":["foreman","prometheus-exporter"],"created_at":"2024-11-08T02:12:35.502Z","updated_at":"2026-01-26T11:30:17.553Z","avatar_url":"https://github.com/fgouteroux.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# foreman_exporter\n\n## Foreman Prometheus Exporter\n\nThis [Prometheus](https://prometheus.io/)\n[exporter](https://prometheus.io/docs/instrumenting/exporters/)\nexposes [foreman](https://www.theforeman.org/) metrics.\n\n![Foreman Exporter](img/home.png)\n\n### Usage\n\n```\nusage: foreman_exporter --url=URL --username=USERNAME --password=PASSWORD [\u003cflags\u003e]\n\n\nFlags:\n  -h, --[no-]help                Show context-sensitive help (also try --help-long and --help-man).\n      --[no-]web.disable-exporter-metrics  \n                                 Exclude metrics about the exporter itself (process_*, go_*).\n      --web.telemetry-path=\"/metrics\"  \n                                 Path under which to expose metrics.\n      --web.prefix-path=\"\"       Prefix path for all http requests.\n      --[no-]web.systemd-socket  Use systemd socket activation listeners instead of port listeners (Linux only).\n      --web.listen-address=:11111 ...  \n                                 Addresses on which to expose metrics and web interface. Repeatable for multiple addresses.\n      --web.config.file=\"\"       [EXPERIMENTAL] Path to configuration file that can enable TLS or authentication. See: https://github.com/prometheus/exporter-toolkit/blob/master/docs/web-configuration.md\n      --url=URL                  Foreman url. ($FOREMAN_URL)\n      --username=USERNAME        Foreman username. ($FOREMAN_USERNAME)\n      --password=PASSWORD        Foreman password ($FOREMAN_PASSWORD)\n      --[no-]skip-tls-verify     Foreman skip TLS verify. ($FOREMAN_SKIP_TLS_VERIFY)\n      --concurrency=4            Max concurrent foreman client http request.\n      --limit=0                  Foreman client host limit search.\n      --search=\"\"                Foreman client host search filter.\n      --timeout-offset=0.5s      Offset to subtract from Prometheus-supplied timeout.\n      --[no-]collector.lock-concurrent-requests  \n                                 Lock concurrent requests on collectors.\n      --collector=host ...       Collector to enabled (repeatable), choices: [host, hostfact].\n      --collector.host.labels-include=COLLECTOR.HOST.LABELS-INCLUDE  \n                                 Host labels to include (regex).\n      --collector.host.labels-exclude=COLLECTOR.HOST.LABELS-EXCLUDE  \n                                 Host labels to exclude (regex).\n      --collector.host.timeout=30s  \n                                 Host default timeout if no request header 'X-Prometheus-Scrape-Timeout-Seconds'\n      --[no-]collector.host.cache.enabled  \n                                 Enable host cache, if global 'cache.enabled' is false.\n      --[no-]collector.host.cache.compression  \n                                 Enable host zstd cache compression for kvstore values, if global 'cache.compression' is false.\n      --collector.host.cache.ttl-expires=COLLECTOR.HOST.CACHE.TTL-EXPIRES  \n                                 Host cache expiration time, if omitted, inherit from 'cache.ttl-expires'.\n      --collector.hostfact.search=COLLECTOR.HOSTFACT.SEARCH  \n                                 Search host fact query filter.\n      --collector.hostfact.include=COLLECTOR.HOSTFACT.INCLUDE  \n                                 Host fact to include (regex).\n      --collector.hostfact.exclude=COLLECTOR.HOSTFACT.EXCLUDE  \n                                 Host fact to exclude (regex).\n      --collector.hostfact.timeout=30s  \n                                 Host fact default timeout if no request header 'X-Prometheus-Scrape-Timeout-Seconds'.\n      --[no-]collector.hostfact.cache.enabled  \n                                 Enable host fact cache, if global 'cache.enabled' is false.\n      --[no-]collector.hostfact.cache.compression  \n                                 Enable host fact zstd cache compression for kvstore values, if global 'cache.compression' is false.\n      --collector.hostfact.cache.ttl-expires=COLLECTOR.HOSTFACT.CACHE.TTL-EXPIRES  \n                                 Host fact cache expiration time, if omitted, inherit from global 'cache.ttl-expires'.\n      --[no-]cache.enabled       Enable cache for all collectors.\n      --cache.ttl-expires=1h     Cache Expiration time for all collectors.\n      --[no-]cache.compression   Enable zstd cache compression for all collectors in kvstore.\n      --[no-]ring.enabled        Enable the ring to deduplicate exported foreman metrics.\n      --ring.instance-id=RING.INSTANCE-ID  \n                                 Instance ID to register in the ring.\n      --ring.instance-addr=RING.INSTANCE-ADDR  \n                                 IP address to advertise in the ring. Default is auto-detected.\n      --ring.instance-port=7946  Port to advertise in the ring.\n      --ring.instance-interface-names=RING.INSTANCE-INTERFACE-NAMES  \n                                 List of network interface names to look up when finding the instance IP address.\n      --ring.join-members=RING.JOIN-MEMBERS  \n                                 Other cluster members to join.\n      --log.level=info           Only log messages with the given severity or above. One of: [debug, info, warn, error]\n      --log.format=logfmt        Output format of log messages. One of: [logfmt, json]\n      --[no-]version             Show application version.\n```\n\n### Metrics Exposed\n\n**Exporter metrics**\n\nThis endpoint return metrics about exporter itself and foreman client requests.\n\n```\n# HELP foreman_exporter_build_info A metric with a constant '1' value labeled by version, revision, branch, goversion from which foreman_exporter was built, and the goos and goarch for the build.\n# TYPE foreman_exporter_build_info gauge\nforeman_exporter_build_info{branch=\"feat/handle_scrape_timeout\",goarch=\"amd64\",goos=\"linux\",goversion=\"go1.21.1\",revision=\"7059cdd4062a29a53cc43225c23061c3b9750aac\",tags=\"unknown\",version=\"0.0.5-2-g7059cdd-dirty\"} 1\n# HELP foreman_exporter_client_in_flight_requests A gauge of all in-flight requests for the foreman client.\n# TYPE foreman_exporter_client_in_flight_requests gauge\nforeman_exporter_client_in_flight_requests 0\n# HELP foreman_exporter_client_request_duration_seconds A histogram of all request latencies from the foreman client.\n# TYPE foreman_exporter_client_request_duration_seconds histogram\nforeman_exporter_client_request_duration_seconds_bucket{le=\"0.005\"} 0\nforeman_exporter_client_request_duration_seconds_bucket{le=\"0.01\"} 0\nforeman_exporter_client_request_duration_seconds_bucket{le=\"0.025\"} 0\nforeman_exporter_client_request_duration_seconds_bucket{le=\"0.05\"} 0\nforeman_exporter_client_request_duration_seconds_bucket{le=\"0.1\"} 0\nforeman_exporter_client_request_duration_seconds_bucket{le=\"0.25\"} 14\nforeman_exporter_client_request_duration_seconds_bucket{le=\"0.5\"} 72\nforeman_exporter_client_request_duration_seconds_bucket{le=\"1\"} 73\nforeman_exporter_client_request_duration_seconds_bucket{le=\"2.5\"} 74\nforeman_exporter_client_request_duration_seconds_bucket{le=\"5\"} 74\nforeman_exporter_client_request_duration_seconds_bucket{le=\"10\"} 74\nforeman_exporter_client_request_duration_seconds_bucket{le=\"+Inf\"} 74\nforeman_exporter_client_request_duration_seconds_sum 26.012748153\nforeman_exporter_client_request_duration_seconds_count 74\n# HELP foreman_exporter_client_requests_total A counter for all requests from the foreman client.\n# TYPE foreman_exporter_client_requests_total counter\nforeman_exporter_client_requests_total{code=\"200\",method=\"get\"} 74\n```\n\n**Foreman hosts status**\n\nEnabled by default.\n\nThis collector return metrics to a dedicated endpoint `/host-metrics`.\n\n```\n# HELP foreman_exporter_host_status_info Foreman host status\n# TYPE foreman_exporter_host_status_info gauge\nforeman_exporter_host_status_info{build_status=\"Installed\",configuration_status=\"Active\",global_status=\"OK\",name=\"server.example.com\",organization=\"example\"} 1\n```\n\nIf the memory cache is enabled and the cache has expired it is possible to use it even if foreman api is not available (network outage, service restart, slow response...). This could prevent hole in metrics scrapping and alerts flapping. To use it, just pass the uri param `expired-cache=true` in scrape config or curl cmd.\n\n```\ncurl http://localhost:11111/host-metrics?expired-cache=true\n```\n\nIf the memory cache is enabled, it is possible to force cache regeneration with the param `cache=false`.\n\n```\ncurl http://localhost:11111/host-metrics?cache=false\n```\n\nThe following metrics have been added:\n```\n# HELP foreman_exporter_host_scrape_timeout 1 if timeout occurs, 0 otherwise\n# TYPE foreman_exporter_host_scrape_timeout gauge\nforeman_exporter_host_scrape_timeout 1\n# HELP foreman_exporter_host_use_expired_cache 1 if using expired cache, 0 otherwise\n# TYPE foreman_exporter_host_use_expired_cache gauge\nforeman_exporter_host_use_expired_cache 1\n```\n\n**Foreman hosts facts**\n\nEnable this collector with the flag `--collector=hostfact`.\n\nThis collector return metrics to a dedicated endpoint `/host-facts-metrics`.\n\nForeman hosts facts could render big metrics labels and must be used with the following flags to reduce the number of labels (labels cardinality):\n- `--collector.hostfact.search=`: a foreman query to filter http facts response\n- `--collector.hostfact.include=`: a regex to filter facts to include as labels\n- `--collector.hostfact.exclude=`: a regex to filter facts to exclude as labels\n\nAs foreman host facts collector metrics could return many metrics (depending of foreman hosts number) and labels doesn't change a lot, a memory cache could be enabled.\n\n```\n# HELP foreman_exporter_host_facts_info Foreman host facts\n# TYPE foreman_exporter_host_facts_info gauge\nforeman_exporter_host_facts_info{name=\"server.example.com\", operatingsystem=\"RedHat\",operatingsystemmajrelease=\"9\",operatingsystemrelease=\"9.2\"} 1\n```\n\nIf the memory cache is enabled and the cache has expired it is possible to use it even if foreman api is not available (network outage, service restart, slow response...). This could prevent hole in metrics scrapping and alerts flapping. To use it, just pass the uri param `expired-cache=true` in scrape config or curl cmd.\n\n```\ncurl http://localhost:11111/host-facts-metrics?expired-cache=true\n```\n\nIf the memory cache is enabled, it is possible to force cache regeneration with the param `cache=false`.\n\n```\ncurl http://localhost:11111/host-facts-metrics?cache=false\n```\n\n\nThe following metrics have been added:\n```\n# HELP foreman_exporter_host_facts_scrape_timeout 1 if timeout occurs, 0 otherwise\n# TYPE foreman_exporter_host_facts_scrape_timeout gauge\nforeman_exporter_host_facts_scrape_timeout 1\n# HELP foreman_exporter_host_facts_use_expired_cache 1 if using expired cache, 0 otherwise\n# TYPE foreman_exporter_host_facts_use_expired_cache gauge\nforeman_exporter_host_facts_use_expired_cache 1\n```\n\n### HA with memberlist\n\nThis exporter could be run in cluster mode with memberlist.\n\n![Ring](img/ring.png)\n\nTo enable cluster mode, use the following flags:\n```\n      --ring.instance-id=RING.INSTANCE-ID  \n                                 Instance ID to register in the ring.\n      --ring.instance-addr=RING.INSTANCE-ADDR  \n                                 IP address to advertise in the ring. Default is auto-detected.\n      --ring.instance-port=7946  Port to advertise in the ring.\n      --ring.instance-interface-names=RING.INSTANCE-INTERFACE-NAMES  \n                                 List of network interface names to look up when finding the instance IP address.\n      --ring.join-members=RING.JOIN-MEMBERS  \n                                 Other cluster members to join.\n```\n\nOne instance of the ring is elected to be the leader and this is the only one which will make request to foreman and export metrics.\n\nIf the leader instance goes down, another one will be elected and will start to export metrics.\n\n![Memberlist](img/memberlist.png)\n\nWith this config, it is easy to configure a prometheus agent to scrape the exporter metrics and avoid duplication.\n\nIf the foreman host facts collector metrics is enabled with the cache option, the cache is stored in the memberlist kvstore and replicated to all ring instances.\n\n```\n      --[no-]cache.enabled       Enable cache\n      --cache.ttl-expires=1h     Cache Expiration time\n      --[no-]cache.compression   Enable zstd compression for kvstore values\n```\n\n### TLS and basic authentication\n\nForeman Exporter supports TLS and basic authentication. This enables better control of the various HTTP endpoints.\n\nTo use TLS and/or basic authentication, you need to pass a configuration file using the `--web.config.file` parameter. The format of the file is described\n[in the exporter-toolkit repository](https://github.com/prometheus/exporter-toolkit/blob/master/docs/web-configuration.md).\n\n### Sources\n\n- [Foreman api](https://apidocs.theforeman.org/foreman/2.4/apidoc/v2.html)\n- [Hashicorp Memberlist](https://github.com/hashicorp/memberlist)\n- [Grafana Distributed systems kit](https://github.com/grafana/dskit)\n- [Grafana Mimir Override exporter](https://github.com/grafana/mimir/tree/main/pkg/util/validation/exporter)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffgouteroux%2Fforeman_exporter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffgouteroux%2Fforeman_exporter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffgouteroux%2Fforeman_exporter/lists"}