{"id":14971995,"url":"https://github.com/luizbizzio/currency-exporter","last_synced_at":"2026-02-21T19:17:52.220Z","repository":{"id":252477635,"uuid":"840562422","full_name":"luizbizzio/currency-exporter","owner":"luizbizzio","description":"💱 A Prometheus exporter written in Python to collect currency exchange rates and expose them as metrics. This tool provides real-time data on various exchange rates, enabling integration with monitoring systems for financial applications.","archived":false,"fork":false,"pushed_at":"2025-04-12T16:35:01.000Z","size":75,"stargazers_count":20,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-10-25T15:35:49.083Z","etag":null,"topics":["api","automation","currencies","currency","currency-converter","currency-exchange-rates","data-visualization","economy","exporter","grafana","grafana-dashboard","homeautomation","iot","metrics","monitoring","open-source","prometheus","prometheus-exporter","python","real-time"],"latest_commit_sha":null,"homepage":"https://economia.awesomeapi.com.br/json/last/GBP-EUR,EUR-BRL,USD-EUR,BTC-USD,CNY-USD,USD-JPY,EUR-USD,ETH-USD,GBP-USD","language":"Python","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/luizbizzio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":"luizbizzio"}},"created_at":"2024-08-10T02:53:36.000Z","updated_at":"2025-10-04T02:27:10.000Z","dependencies_parsed_at":"2024-11-20T03:32:52.376Z","dependency_job_id":null,"html_url":"https://github.com/luizbizzio/currency-exporter","commit_stats":{"total_commits":11,"total_committers":1,"mean_commits":11.0,"dds":0.0,"last_synced_commit":"ab38f8b9642e0ba69c9327bf7e0ba195ecc8d1b2"},"previous_names":["luizbizzio/currency_exporter"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/luizbizzio/currency-exporter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luizbizzio%2Fcurrency-exporter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luizbizzio%2Fcurrency-exporter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luizbizzio%2Fcurrency-exporter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luizbizzio%2Fcurrency-exporter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/luizbizzio","download_url":"https://codeload.github.com/luizbizzio/currency-exporter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luizbizzio%2Fcurrency-exporter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":281140974,"owners_count":26450551,"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-10-26T02:00:06.575Z","response_time":61,"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":["api","automation","currencies","currency","currency-converter","currency-exchange-rates","data-visualization","economy","exporter","grafana","grafana-dashboard","homeautomation","iot","metrics","monitoring","open-source","prometheus","prometheus-exporter","python","real-time"],"created_at":"2024-09-24T13:46:10.385Z","updated_at":"2026-02-21T19:17:52.213Z","avatar_url":"https://github.com/luizbizzio.png","language":"Python","funding_links":["https://github.com/sponsors/luizbizzio"],"categories":[],"sub_categories":[],"readme":"# Currency Exporter 💱📈\n\nPrometheus exporter for **currency exchange rates**.\n\nIt fetches rates from a public dataset on an interval and exposes metrics on `/metrics`.  \nThis exporter is for monitoring and dashboards. It is not for trading or real time pricing.\n\n## Examples (Grafana)\n\nThese screenshots are examples.\n\n### Time series panel\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"images/metrics.png\" alt=\"Grafana time series example\" width=\"700\"/\u003e\n\u003c/p\u003e\n\n### Stat panel\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"images/metrics2.png\" alt=\"Grafana stat example\" width=\"700\"/\u003e\n\u003c/p\u003e\n\n## How it works\n\n- You define the currency pairs in `config.yaml` (example: `EUR-USD`, `USD-BRL`).\n- The exporter chooses a pivot currency (it prefers `USD` if it appears in your pairs).\n- It downloads **one** JSON snapshot for the pivot currency and builds a lookup table of rates.\n- Each configured pair is calculated from the snapshot using cross rate math.\n- Prometheus scraping does not trigger extra API calls. The exporter serves cached values until the next update cycle.\n\nIf a currency code does not exist in the snapshot (example: `ABC-USD`), the exporter stays up, but marks the pair as unsupported.\n\n## Features 📊\n\n- Metrics on `/metrics`\n- Pair based config in `config.yaml`\n- One snapshot request per update cycle\n- Cached results (Prometheus scrapes are cheap)\n- Retries with exponential backoff for temporary network issues\n- Health and config metrics for alerting\n- Optional default Python and process metrics (`expose_default_metrics`)\n\n## Data source\n\n- Project: https://github.com/fawazahmed0/exchange-api  \n- Symbols list (all supported codes):  \n  https://cdn.jsdelivr.net/npm/@fawazahmed0/currency-api@latest/v1/currencies.json\n\nThe upstream dataset updates daily. Updating more frequently than 24h will usually return the same values.  \nYour exporter update frequency is controlled by `update_interval_seconds`.\n\n## Requirements\n\n- Python 3.10+ (3.11 recommended)  \n- Or Docker  \n- Network access to the data source\n\n## Install ⚙️\n\nBefore running, edit `config.yaml` and set the currency pairs you want in `pairs:`.  \nThis repository includes a `config.yaml` example. It is not meant to be used as-is.\n\n### Python 🐍\n\nInstall dependencies:\n\n```bash\npip install -r requirements.txt\n```\n\nRun:\n\n```bash\npython currency_exporter.py\n```\n\nTest:\n\n```bash\ncurl http://localhost:7575/metrics\n```\n\n### Docker 🐳 (GHCR)\n\nPull:\n\n```bash\ndocker pull ghcr.io/luizbizzio/currency-exporter:latest\n```\n\nRun (mount your `config.yaml`):\n\n```bash\ndocker run -d   --name currency-exporter   -p 7575:7575   -v \"$(pwd)/config.yaml:/config/config.yaml:ro\"   --restart unless-stopped   ghcr.io/luizbizzio/currency-exporter:latest   --config-file /config/config.yaml\n```\n\nTest:\n\n```bash\ncurl http://localhost:7575/metrics\n```\n\nNotes:\n- If you change `server.port` in `config.yaml`, update the `-p` mapping too.\n- The container is stateless. Any config change requires a container restart.\n\n## Configuration 🛠️\n\nEdit `config.yaml`:\n\n```yaml\nserver:\n  port: 7575\n  timeout_seconds: 10\n  update_interval_seconds: 28800\n  retries: 3\n  retry_backoff_seconds: 1\n  expose_default_metrics: false\n  log_level: INFO\n\npairs:\n  - BTC-USD\n  - EUR-BRL\n  - USD-BRL\n  - GBP-EUR\n  - EUR-USD\n  - CNY-USD\n```\n\nNotes:\n- Pair format is `BASE-QUOTE` like `USD-BRL`.\n- If a code does not exist, the exporter will set:\n  - `currency_pair_supported = 0`\n  - `currency_exporter_config_invalid_pairs \u003e 0`\n\n## Prometheus scrape config\n\n```yaml\nscrape_configs:\n  - job_name: \"currency-exporter\"\n    static_configs:\n      - targets: [\"YOUR_EXPORTER_IP:7575\"]\n```\n\nTip:\nIf you update once per day, increase `scrape_interval` for this job (example: 1h) to reduce storage and noise.\n\n## Grafana queries\n\nSingle pair:\n\n```promql\ncurrency_exchange_rate{base=\"EUR\",quote=\"USD\"}\n```\n\nMany pairs in one panel:\n\n```promql\ncurrency_exchange_rate{base=~\"EUR|USD|GBP|CNY|BTC\",quote=~\"USD|EUR|BRL\"}\n```\n\nLegend format:\n\n`{{base}}-{{quote}}`\n\n## Metrics\n\n| Name | Type | Description |\n|---|---|---|\n| `currency_exchange_rate{base,quote}` | Gauge | Exchange rate from base to quote |\n| `currency_pair_supported{base,quote}` | Gauge | 1 if pair is supported in current snapshot, else 0 |\n| `currency_exporter_up` | Gauge | 1 if last update succeeded, else 0 |\n| `currency_exporter_last_update_timestamp` | Gauge | Unix timestamp of last update attempt |\n| `currency_exporter_last_success_timestamp` | Gauge | Unix timestamp of last successful update |\n| `currency_exporter_update_duration_seconds` | Gauge | Duration of last update |\n| `currency_exporter_errors_total` | Counter | Total number of update errors |\n| `currency_exporter_config_invalid_pairs` | Gauge | Number of configured pairs missing in snapshot |\n| `currency_exporter_invalid_pairs_total` | Counter | Number of update cycles that had missing pairs |\n| `currency_exporter_snapshot_info{date,pivot}` | Gauge | Snapshot date and pivot info |\n\n## Troubleshooting 🔍\n\nIf you do not see `currency_exchange_rate`:\n- Open `/metrics` and search for `currency_`.\n- Confirm the exporter is running on the expected port.\n- Check logs. A bad URL or timeout will set `currency_exporter_up = 0`.\n\nIf `currency_exporter_config_invalid_pairs \u003e 0`:\n- One or more codes in `pairs` do not exist in the current snapshot.\n- Check the symbols list:\n  https://cdn.jsdelivr.net/npm/@fawazahmed0/currency-api@latest/v1/currencies.json\n\n## License\n\nThis project is licensed under the [PolyForm Noncommercial License 1.0.0](./LICENSE).\n\nCommercial use, resale, and paid services are not permitted.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluizbizzio%2Fcurrency-exporter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fluizbizzio%2Fcurrency-exporter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluizbizzio%2Fcurrency-exporter/lists"}