{"id":13585855,"url":"https://github.com/claws/dump1090-exporter","last_synced_at":"2025-08-20T22:32:04.115Z","repository":{"id":12356143,"uuid":"71686694","full_name":"claws/dump1090-exporter","owner":"claws","description":"A Prometheus metrics exporter for the dump1090 Mode S decoder for RTLSDR","archived":false,"fork":false,"pushed_at":"2023-07-01T07:05:14.000Z","size":2297,"stargazers_count":93,"open_issues_count":9,"forks_count":19,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-07-31T10:55:42.018Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/claws.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,"roadmap":null,"authors":null}},"created_at":"2016-10-23T06:48:22.000Z","updated_at":"2025-04-01T18:38:34.000Z","dependencies_parsed_at":"2024-01-15T06:03:10.918Z","dependency_job_id":null,"html_url":"https://github.com/claws/dump1090-exporter","commit_stats":{"total_commits":31,"total_committers":3,"mean_commits":"10.333333333333334","dds":"0.19354838709677424","last_synced_commit":"7857608bcadf7f9294872f61c33a54d6d45c6c3f"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/claws/dump1090-exporter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claws%2Fdump1090-exporter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claws%2Fdump1090-exporter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claws%2Fdump1090-exporter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claws%2Fdump1090-exporter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/claws","download_url":"https://codeload.github.com/claws/dump1090-exporter/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claws%2Fdump1090-exporter/sbom","scorecard":{"id":285566,"data":{"date":"2025-08-11","repo":{"name":"github.com/claws/dump1090-exporter","commit":"7857608bcadf7f9294872f61c33a54d6d45c6c3f"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":2.7,"checks":[{"name":"Code-Review","score":1,"reason":"Found 2/15 approved changesets -- score normalized to 1","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/ci.yml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'master'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"Pinned-Dependencies","score":1,"reason":"dependency not pinned by hash detected -- score normalized to 1","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:18: update your workflow using https://app.stepsecurity.io/secureworkflow/claws/dump1090-exporter/ci.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:20: update your workflow using https://app.stepsecurity.io/secureworkflow/claws/dump1090-exporter/ci.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:29: update your workflow using https://app.stepsecurity.io/secureworkflow/claws/dump1090-exporter/ci.yml/master?enable=pin","Warn: containerImage not pinned by hash: Dockerfile:1: pin your Docker image by updating python:3.10-alpine to python:3.10-alpine@sha256:24cab748bf7bd8e3d2f9bb4e5771f17b628417527a4e1f2c59c370c2a8a27f1c","Warn: pipCommand not pinned by hash: Dockerfile:14-20","Warn: pipCommand not pinned by hash: .github/workflows/ci.yml:25","Warn: pipCommand not pinned by hash: .github/workflows/ci.yml:26","Warn: pipCommand not pinned by hash: .github/workflows/ci.yml:27","Warn: pipCommand not pinned by hash: .github/workflows/ci.yml:42","Info:   0 out of   3 GitHub-owned GitHubAction dependencies pinned","Info:   1 out of   6 pipCommand dependencies pinned","Info:   0 out of   1 containerImage dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Vulnerabilities","score":0,"reason":"13 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: PYSEC-2024-48 / GHSA-fj7x-q9j7-g6q6","Warn: Project is vulnerable to: PYSEC-2022-43017 / GHSA-qwmp-2cf2-g9g6","Warn: Project is vulnerable to: PYSEC-2023-120 / GHSA-45c4-8wx5-qw6w","Warn: Project is vulnerable to: PYSEC-2024-24 / GHSA-5h86-8mv2-jq9f","Warn: Project is vulnerable to: GHSA-5m98-qgg9-wh84","Warn: Project is vulnerable to: GHSA-7gpw-8wmc-pm8g","Warn: Project is vulnerable to: GHSA-8495-4g3g-x7pr","Warn: Project is vulnerable to: PYSEC-2024-26 / GHSA-8qpw-xqxj-h4r2","Warn: Project is vulnerable to: GHSA-9548-qrrj-x5pj","Warn: Project is vulnerable to: PYSEC-2023-246 / GHSA-gfw2-4jvh-wgfg","Warn: Project is vulnerable to: GHSA-pjjw-qhg8-p2p9","Warn: Project is vulnerable to: PYSEC-2023-250 / GHSA-q3qx-c6g2-7pw2","Warn: Project is vulnerable to: PYSEC-2023-251 / GHSA-qvrw-v9rv-5rjx"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 27 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}}]},"last_synced_at":"2025-08-17T17:09:23.429Z","repository_id":12356143,"created_at":"2025-08-17T17:09:23.429Z","updated_at":"2025-08-17T17:09:23.429Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271397961,"owners_count":24752641,"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","status":"online","status_checked_at":"2025-08-20T02:00:09.606Z","response_time":69,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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-08-01T15:05:11.156Z","updated_at":"2025-08-20T22:32:03.775Z","avatar_url":"https://github.com/claws.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# dump1090 Exporter\n\n[Dump1090](https://github.com/mutability/dump1090) is a simple Mode S decoder\nfor RTLSDR devices that is commonly used for tracking aircraft. Dump1090 makes\na number of operating metrics available to track the performance of the tool\nand its environment.\n\nThe dump1090exporter collects statistics from dump1090 and exposes it to the\n[Prometheus](https://prometheus.io/) monitoring server for aggregation and\nlater visualisation (e.g. using [Grafana](https://grafana.net/dashboards/768\u003e)).\n\nThis exporter has been reported to work with:\n\n  - the dump1090 mutability fork\n  - the dump1090-fa fork\n  - [readsb](https://github.com/wiedehopf/readsb)\n\n## Install\n\nThe dump1090 exporter is implemented as a Python3.6+ package that can be\ninstalled using the Python package manager *pip*. It is recommended to install\nthis package into a virtual environment.\n\n```shell\n$ pip install dump1090exporter\n```\n\nThe package can optionally make use of the *uvloop* package which provides a\nmore efficient implementation of the asyncio event loop.\n\n```shell\n$ pip install dump1090exporter[uvloop]\n```\n\nThe dump1090exporter has also been packaged into a Docker container. See the\n[Docker](#docker) section below for more details about that.\n\n## Run\n\nThe dump1090 exporter can be run from the command line using the console entry\npoint script configured as part of the installation.\n\nThe dump1090 exporter accepts a number of command line arguments which can be\ndisplayed using the standard command line help request.\n\n```shell\n$ dump1090exporter -h\n```\n\nAn example usage is shown below.\n\n```shell\n$ dump1090exporter \\\n  --resource-path=http://192.168.1.201:8080/data \\\n  --port=9105 \\\n  --latitude=-34.9285 \\\n  --longitude=138.6007 \\\n  --log-level info\n```\n\nThe ``--resource-path`` argument defines the common base path to the various\ndump1090 resources used by the exporter. The resource path can be a URL or a\nfile system location.\n\nIn the example command the exporter is instructed to monitor a dump1090\ninstance running on a machine with the IP address 192.168.1.201 using the port\n8080.\n\nThe dump1090exporter can also monitor dump1090 state via the file system if\nyou run it on the same machine as the dump1090 process. In this scenario you\nwould pass a file system path to the ``--resource-path`` command line argument.\n\nFor example:\n\n```shell\n$ dump1090exporter \\\n  --resource-path=/path/to/dump1090-base-dir/data \\\n  ...\n```\n\nA more concrete example for dump1090-fa would be:\n\n```shell\n$ dump1090exporter \\\n  --resource-path=/run/dump1090-fa/ \\\n  ...\n```\n\nThe exporter uses the ``resources-path`` value to construct the following\nresources:\n\n  - {resource-path}/receiver.json\n  - {resource-path}/aircraft.json\n  - {resource-path}/stats.json\n\nReceiver data is read from ``{resource-path}/receiver.json`` every 10 seconds\nuntil a location can be obtained. Once a location has been read from the\nresource then it is only polled every 300 seconds. However, in most cases the\ndump1090 tool is not configured with the receivers position.\n\nAircraft data is read from ``{resource-path}/aircraft.json`` every 10 seconds.\nThis can be modified by specifying a new value with the ``--aircraft-interval``\nargument.\n\nStatistics data is read from ``{resource-path}/stats.json`` every 60 seconds,\nas the primary metrics being exported are extracted from the *last1min* time\nperiod. This too can be modified by specifying an alternative value with the\n``--stats-interval`` argument.\n\nThe example command uses the ``--port`` argument to instruct the exporter to\nexposes a metrics service on port 9105. This is where Prometheus would scrape\nthe metrics from. By default the port is configured to use 9105 so it only\nneeds to be specified if you want to change the port to a different value.\n\nThe example command uses the ``--latitude`` and ``--longitude`` arguments\nto instruct the exporter to use a specific receiver origin (lat, lon). By\nproviding the exporter with the receiver's location it can calculate ranges\nto aircraft. Note that if the receiver position is set within the dump1090\ntool (and accessible from the ``{resource-path}/receivers.json`` resource)\nthen the exporter will use that data as the origin.\n\nThe metrics that the dump1090 exporter provides to Prometheus can be\naccessed for debug and viewing using curl or a browser by fetching from\nthe metrics route url. For example:\n\n```shell\n$ curl -s http://0.0.0.0:9105/metrics | grep -v \"#\"\ndump1090_aircraft_recent_max_range{time_period=\"latest\"} 1959.0337385807418\ndump1090_messages_total{time_period=\"latest\"} 90741\ndump1090_recent_aircraft_observed{time_period=\"latest\"} 4\ndump1090_recent_aircraft_with_multilateration{time_period=\"latest\"} 0\ndump1090_recent_aircraft_with_position{time_period=\"latest\"} 1\ndump1090_stats_cpr_airborne{time_period=\"last1min\"} 176\ndump1090_stats_cpr_airborne{time_period=\"total\"} 18293\n...\n```\n\nThe metrics exposed by the dump1090-exporter are all prefixed with the\n*dump1090_* string so as to provide a helpful namespacing which makes them\neasier to find in visualisation tools such as Grafana.\n\nThe exporter exposes generalised metrics for statistics and uses the multi\ndimensional label capability of Prometheus metrics to include information\nabout which group the metric is part of.\n\nTo extract information for the peak signal metric that dump1090 aggregated\nover the last 1 minute you would specify the ``time_period`` for that group:\n\n```shell\ndump1090_stats_local_peak_signal{job=\"dump1090\", time_period=\"last1min\"}\n```\n\nIn the ``stats.json`` data there are 5 top level keys that contain statistics\nfor a different time period, defined by the \"start\" and \"end\" subkeys. The top\nlevel keys are:\n\n- *latest* which covers the time between the end of the \"last1min\" period and\n  the current time. In my dump1090 setup this is always empty.\n- *last1min* which covers a recent 1-minute period. This may be up to 1 minute\n  out of date (i.e. \"end\" may be up to 1 minute old)\n- *last5min* which covers a recent 5-minute period. As above, this may be up\n  to 1 minute out of date.\n- *last15min* which covers a recent 15-minute period. As above, this may be up\n  to 1 minute out of date.\n- *total* which covers the entire period from when dump1090 was started up to\n  the current time.\n\nBy default only the *last1min* time period is exported as Prometheus can be\nused for accessing historical data.\n\n\n## Prometheus Configuration\n\nPrometheus needs to be told where to fetch the dump1090 metrics from. The\nPrometheus configuration file should be updated with a new entry under the\n'scrape_configs' block, that looks something like this:\n\n```yaml\nscrape_configs:\n  - job_name: 'dump1090'\n    scrape_interval: 10s\n    scrape_timeout: 5s\n    static_configs:\n      - targets: ['192.168.1.201:9105']\n```\n\n## Visualisation\n\nThe Granfana visualisation tool can display nice looking charts and it\nsupports Prometheus. A [dump1090export](https://grafana.net/dashboards/768)\nGrafana dashboard has been created to demonstrate how the data provided by the\nexporter can be visualised.\n\n![](https://raw.githubusercontent.com/claws/dump1090-exporter/master/screenshot-grafana.png)\n\n## Docker\n\nThe dump1090 exporter has been packaged into a Docker container on DockerHub.\nThis can simplify running it in some environments. The container is configured\nwith an entry point that runs the dump1090 exporter application. The default\ncommand argument is ``--help`` which will display help information.\n\n```shell\n$ docker run -it --rm clawsicus/dump1090exporter\nusage: dump1090exporter [-h] [--resource-path \u003cdump1090 url\u003e]\n...\n```\n\nTo run the dump1090 exporter container in your environment simply pass your\nown custom command line arguments to it:\n\n```shell\n$ docker run -p 9105:9105 \\\n  --detach \\\n  clawsicus/dump1090exporter \\\n  --resource-path=http://192.168.1.201:8080/data \\\n  --latitude=-34.9285 \\\n  --longitude=138.6007\n```\n\nYou can then check the metrics being exposed to Prometheus by fetching them\nusing curl.\n\n```shell\n$ curl http://127.0.0.1:9105/metrics\n```\n\nNext you would configure a Prometheus server to scape the dump1090exporter\ncontainer on port 9105.\n\n\n## Demonstration\n\nA demonstration environment can be found in the ``demo`` directory. It uses\nDocker Compose to orchestrate containers running dump1090exporter, Prometheus\nand Grafana to facilitate experimentation with metric collection and graphing.\n\nThis provides a really quick and easy method for checking out the\ndump1090exporter.\n\n\n## Developer Notes\n\n### Python Release Process\n\nThe following steps are used to make a new software release:\n\n- Ensure current branch is set to master and is up to date.\n\n- Create a virtual environment, install dependencies and the dump1090exporter.\n\n  ```shell\n  $ make venv\n  $ source venv/bin/activate\n  (d1090exp) $\n  ```\n\n- Ensure all checks are passing.\n\n  ```shell\n  (d1090exp) $ make checks\n  ```\n\n- Ensure that the version label in ``__init__.py`` has been updated.\n\n- Create the distribution. This project produces an artefact called a pure\n  Python wheel. Only Python3 is supported by this package.\n\n  ```shell\n  (d1090exp) $ make dist\n  ```\n\n- Upload the new release to PyPI.\n\n  ```shell\n  (d1090exp) $ make dist-upload\n  ```\n\n- Create and push a repo tag to Github.\n\n  ```shell\n  $ git tag YY.MM.MICRO -m \"A meaningful release tag comment\"\n  $ git tag  # check release tag is in list\n  $ git push --tags origin master\n  ```\n\n  - Github will create a release tarball at:\n\n    https://github.com/{username}/{repo}/tarball/{tag}.tar.gz\n\n\n### Docker Release Process\n\nThe following steps are used to make a new software release:\n\n- Generate the dump1090exporter Python package distribution.\n\n  ```shell\n  (d1090exp) $ make dist\n  ```\n\n- Log in to the Docker user account which will hold the public image.\n\n  ```shell\n  (d1090exp) $ docker login\n  username\n  password\n  ```\n\n- Build the dump1090exporter Docker container.\n\n  ```shell\n  (d1090exp) $ docker build -t clawsicus/dump1090exporter .\n  ```\n\n- Perform a simple test of the container by specifying its full namespace to\n  run that container image.\n\n  ```shell\n  $ docker run -it --rm clawsicus/dump1090exporter\n  usage: dump1090exporter [-h] [--resource-path \u003cdump1090 url\u003e]\n  ...\n  ```\n\n- Test the container by configuring it to connect to a dump1090 service.\n\n  ```shell\n  $ docker run -p 9105:9105 \\\n    --detach \\\n    clawsicus/dump1090exporter \\\n    --resource-path=http://192.168.1.201:8080/data \\\n    --latitude=-34.9285 \\\n    --longitude=138.6007\n  ```\n\n  Confirm that metrics are being collected and exposed by checking metrics\n  are being exposed to Prometheus by fetching them using curl.\n\n  ```shell\n  $ curl http://127.0.0.1:9105/metrics\n  ```\n\n- Publish the new container to DockerHub using:\n\n  ```shell\n  (d1090exp) $ docker push clawsicus/dump1090exporter:\u003cversion\u003e\n  ```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclaws%2Fdump1090-exporter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclaws%2Fdump1090-exporter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclaws%2Fdump1090-exporter/lists"}