{"id":15481838,"url":"https://github.com/opsdis/icinga2-exporter","last_synced_at":"2025-04-22T15:25:25.091Z","repository":{"id":42029789,"uuid":"203152050","full_name":"opsdis/icinga2-exporter","owner":"opsdis","description":"The Icinga2-exporter utilize Icinga2 API to fetch service based performance data and publish it in a way that lets prometheus scrape the performance data as metrics.","archived":false,"fork":false,"pushed_at":"2024-11-14T10:55:23.000Z","size":94,"stargazers_count":17,"open_issues_count":3,"forks_count":17,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-17T04:19:12.112Z","etag":null,"topics":["grafana","icinga2","monitor-promdiscovery","prometheus"],"latest_commit_sha":null,"homepage":"https://www.opsdis.com","language":"Python","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/opsdis.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","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":"2019-08-19T10:35:56.000Z","updated_at":"2025-02-20T07:43:31.000Z","dependencies_parsed_at":"2024-11-14T11:19:36.289Z","dependency_job_id":"8d7b336d-b0dc-4fb0-ae83-848b565c299f","html_url":"https://github.com/opsdis/icinga2-exporter","commit_stats":{"total_commits":71,"total_committers":8,"mean_commits":8.875,"dds":0.2816901408450704,"last_synced_commit":"cc67040910392e64853eb45eeb9efcd074c067c0"},"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opsdis%2Ficinga2-exporter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opsdis%2Ficinga2-exporter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opsdis%2Ficinga2-exporter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opsdis%2Ficinga2-exporter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/opsdis","download_url":"https://codeload.github.com/opsdis/icinga2-exporter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249358920,"owners_count":21256929,"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":["grafana","icinga2","monitor-promdiscovery","prometheus"],"created_at":"2024-10-02T05:06:32.853Z","updated_at":"2025-04-22T15:25:25.069Z","avatar_url":"https://github.com/opsdis.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![PyPI version](https://badge.fury.io/py/icinga2-exporter.svg)](https://badge.fury.io/py/icinga2-exporter)\n\nicinga2-exporter\n-----------------------\n\n# Overview\n\nThe icinga2-exporter utilizes the [Icinga 2](https://icinga.com/) REST API to fetch service based performance\ndata and publish it in a way that lets [Prometheus](https://prometheus.io/) scrape the performance data as metrics.\n\nThe service is based on [Quart](https://pgjones.gitlab.io/quart/). Quart's is compatible with Flask but based \non Asyncio.  \n\nBenefits:\n\n- Enable advanced queries and aggregation on timeseries\n- Prometheus based alerting rules\n- Grafana graphing\n- Utilize investments with Icinga 2 of collecting metrics\n\n\n# Metrics naming\n\n## Metric names\nMetrics that is scraped with the icinga2-exporter will have the following name structure:\n\n    \u003cmetric_prefix\u003e_\u003ccheck_command\u003e_\u003cperfname\u003e_\u003cunit\u003e\n\n\u003e The metric_prefix can be changed by the configuration, defaults to icinga2\n\u003e \n\u003e Unit is only added if it exists on performance data\n\nExample from check command `check_ping` will result in two metrics:\n\n    icinga2_ping_rta_seconds\n    icinga2_ping_pl_ratio\n\n## Metric labels\n\nThe icinga2-exporter adds a number of labels to each metrics:\n\n- hostname - is the `host_name` in icinga2\n- service - is the `display_name` in icinga2\n\nOptional icinga2-exporter can be configured to add specific custom variables configured on the host.\n\n\u003e **Note**:\n\u003e\n\u003e Icinga 2 supports custom variables that can be complex data structures - but that is NOT currently supported.\n\nLabels created from custom variables are all transformed to lowercase.\n\n### Performance metrics name to labels\n\nAs described above the default naming of the Prometheus name is:\n\n    icinga2_\u003ccheck_command\u003e_\u003cperfname\u003e_\u003cunit\u003e\n\nFor some checks this does not work well like for the `disk` check command where the perfname are the unique mount paths.\nFor checks like that the where the perfname is defined depending on environment you can change so the perfname instead becomes a label.\nThis is defined in the configuration like:\n\n```yaml\n  perfnametolabel:\n      # The command name\n      disk:\n        # the label name to be used\n        label_name: mount\n```\nSo if the check command is `disk` the Prometheus metrics will have a format like, depending on other custom variables :\n\n    icinga2_disk_bytes{hostname=\"icinga2\", service=\"disk\", os=\"Docker\", mount=\"/var/lib/icinga2\"} 48356130816.0\n\nIf we did not make this translation we would got the following:\n\n    icinga2_disk_slashvarslashibslashicinga2_bytes{hostname=\"icinga2\", service=\"disk\", os=\"Docker\"} 48356130816.0\n\nThis would not be good from a cardinality point of view.\n\n# Scrape duration\n\nThe scrape duration is a metrics that is reported for all targets. \n\n    icinga2_scrape_duration_seconds{hostname=\"\u003ctarget\u003e\", server=\"\u003cicinga2_server_url\u003e\"} 0.160983\n\n# Scrape response\n\nWhen requests are made to the exporter the following responses are possible:\n\n- A target that exists - return all metrics and http status 200\n- A target does not exists - return no metrics, empty response, and http status 200\n- The export fail to scrape metrics from icinga2 - return empty response and http status 500\n\nIn the last scenario the exporter will log the reason for the failed scrape. A failed scrape can\nhave multiple reasons, for example:\n\n- The icinga2 server is not responding\n- Not having valid credentials\n- Request to icinga2 timeout\n\n\n# Configuration\n\n## icinga2-exporter\n\nThe `icinga2-exporter` is configured by a yaml based configuration file.\n\nExample:\n```yaml\n\n# Port can be overridden by using -p if running development quart\n#port: 9638\n\nicinga2:\n   # The url to the icinga2 server\n   url: https://127.0.0.1:5665\n   # The icinga2 username\n   user: root\n   # The icinga2 password\n   passwd: cf593406ffcfd2ef\n   # Verify the ssl certificate, default false\n   verify: false\n   # Timeout accessing icinga server, default 5 sec\n   timeout: 5\n   # All prometheus metrics will be prefixed with this string\n   metric_prefix: icinga2\n   # Enables a separate request to fetch host metadata like state and state_type. Default false\n   enable_scrape_metadata: true\n   # Enables export of warning and critical threshold values. Default false\n   enable_scrape_thresholds: false\n\n   # Set the service name for host check metric, default is alive - only change this if it is a name conflict with other\n   # services\n   # host_check_service_name: alive\n\n   # Example of host customer variables that should be added as labels and how to be translated\n   host_custom_vars:\n      # Specify which custom_vars to extract from hosts in icinga2\n      - env:\n           # Name of the label in Prometheus\n           label_name: environment\n      - site:\n           label_name: dc\n\n   # This section enable that for specific check commands the perfdata metrics name will not be part of the\n   # prometheus metrics name, instead moved to a label\n   # E.g for the disk command the perfdata name will be set to the label disk like:\n   # icinga2_disk_bytes{hostname=\"icinga2\", service=\"disk\", os=\"Docker\", disk=\"/var/log/icinga2\"}\n   perfnametolabel:\n      # The command name\n      disk:\n         # the label name to be used\n         label_name: mount\n\nlogger:\n   # Path and name for the log file. If not set send to stdout\n   logfile: /var/tmp/icinga2-exporter.log\n   # Log level\n   level: INFO\n```\n\n\u003e When running with gunicorn the port is selected by gunicorn\n\n## enable_scrape_thresholds\n\nSet this to `true` to scrape warning and critical threshold values.\n\nThresholds that are scraped with the icinga2-exporter will have the following name structure:\n\n    \u003cmetric_prefix\u003e_\u003ccheck_command\u003e_\u003cperfname\u003e_\u003cunit\u003e_threshold_critical\n    \u003cmetric_prefix\u003e_\u003ccheck_command\u003e_\u003cperfname\u003e_\u003cunit\u003e_threshold_warning\n\n\u003e The metric_prefix can be changed by the configuration, defaults to icinga2\n\u003e \n\u003e Unit is only added if it exists on performance data\n\nExample from check command `check_ping` will result in two metrics together with metrics for critical and warning thresholds:\n\n    icinga2_ping4_rta_seconds\n    icinga2_ping4_rta_seconds_threshold_critical\n    icinga2_ping4_rta_seconds_threshold_warning\n    icinga2_ping_pl_ratio\n    icinga2_ping4_pl_ratio_threshold_critical\n    icinga2_ping4_pl_ratio_threshold_warning\n\n## Logging\n\nThe log stream is configure in the above config. If `logfile` is not set the logs will go to stdout.\n\nLogs are formatted as json so its easy to store logs in log servers like Loki and Elasticsearch.\n\n## Prometheus configuration\nPrometheus can be used with static configuration or with dynamic file discovery using the project [monitor-promdiscovery](https://github.com/opsdis/monitor-promdiscovery).\n\nPlease add the job to the `scrape_configs` in prometheus.yml.\n\n\u003e The target is the `host_name` configured in icinga2.\n\n### Static config\n```yaml\n\nscrape_configs:\n  - job_name: 'icinga2'\n    metrics_path: /metrics\n    static_configs:\n      - targets:\n        - icinga2\n        - google.se\n    relabel_configs:\n      - source_labels: [__address__]\n        target_label: __param_target\n      - source_labels: [__param_target]\n        target_label: instance\n      - target_label: __address__\n        replacement: localhost:9638\n\n```\n\n### File discovery config for usage with `monitor-promdiscovery`\n\n```yaml\n\nscrape_configs:\n  - job_name: 'icinga2'\n    scrape_interval: 1m\n    metrics_path: /metrics\n    file_sd_configs:\n    - files:\n      - 'sd/icinga2_sd.yml'\n    relabel_configs:\n      - source_labels: [__address__]\n        target_label: __param_target\n      - source_labels: [__param_target]\n        target_label: instance\n      - target_label: __address__\n        replacement: localhost:9638\n\n```\n# Installing\n1. Check out the git repo.\n2. Install dependency\n\n    `pip install -r requirements.txt`\n\n3. Build a distribution\n\n    `python setup.py sdist`\n\n4. Install locally\n\n    `pip install dist/icinga2-exporter-X.Y.Z.tar.gz`\n\n\n# Running\n\n## Development\n\nRun the `icinga2-exporter` with the built-in Quart webserver:\n\n    python -m  icinga2_exporter -f config.yml\n\nTo see all options:\n\n    python -m  icinga2_exporter -h\n\n## Production with hypercorn as ASGI continer \n\nHypercorn is the recommended ASGI container for Quart. Install hypercorn with: \n\n    pip install hypercorn\n\nRunning with default config.yml. The default location is current directory\n\n    hypercorn \"icinga2_exporter.main:create_app()\n\nSet the path to the configuration file.\n\n    hypercorn \"icinga2_exporter.main:create_app('/etc/icinga2-exporter/config.yml')\"\n\n\u003e Port 8000 is the default port for hypercorn. For more configuration for hypercorn please visit \n\u003e https://pgjones.gitlab.io/hypercorn/index.html\n\n## Test the connection\n\nCheck if exporter is working.\n\n    curl -s http://localhost:9638/health\n\nGet metrics for a host where target is a host, `host_name` that exists in icinga2\n\n    curl -s http://localhost:9638/metrics?target=google.se\n\n# System requirements\n\nPython 3.\n\nFor required packages please review `requirements.txt`.\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopsdis%2Ficinga2-exporter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopsdis%2Ficinga2-exporter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopsdis%2Ficinga2-exporter/lists"}