{"id":32191921,"url":"https://github.com/eigenbahn/prometheus-api-client","last_synced_at":"2025-10-22T01:54:03.481Z","repository":{"id":62432538,"uuid":"295828246","full_name":"Eigenbahn/prometheus-api-client","owner":"Eigenbahn","description":"Prometheus HTTP API client for Clojure","archived":false,"fork":false,"pushed_at":"2020-12-29T16:08:31.000Z","size":14,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-10-05T09:42:16.848Z","etag":null,"topics":["clojure","clojure-library","prometheus"],"latest_commit_sha":null,"homepage":"","language":"Clojure","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/Eigenbahn.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}},"created_at":"2020-09-15T19:23:43.000Z","updated_at":"2020-12-29T16:08:33.000Z","dependencies_parsed_at":"2022-11-01T20:45:43.787Z","dependency_job_id":null,"html_url":"https://github.com/Eigenbahn/prometheus-api-client","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Eigenbahn/prometheus-api-client","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Eigenbahn%2Fprometheus-api-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Eigenbahn%2Fprometheus-api-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Eigenbahn%2Fprometheus-api-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Eigenbahn%2Fprometheus-api-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Eigenbahn","download_url":"https://codeload.github.com/Eigenbahn/prometheus-api-client/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Eigenbahn%2Fprometheus-api-client/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280365582,"owners_count":26318385,"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-21T02:00:06.614Z","response_time":58,"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":["clojure","clojure-library","prometheus"],"created_at":"2025-10-22T01:53:58.708Z","updated_at":"2025-10-22T01:54:03.473Z","avatar_url":"https://github.com/Eigenbahn.png","language":"Clojure","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Prometheus HTTP API client for Clojure\n\nClient library wrapper around [Prometheus HTTP API](https://prometheus.io/docs/prometheus/latest/querying/api/).\n\nIt provides the extraction of only relevant data from the responses and, for endpoints returning time series, automated response conversion to a more Clojure-friendly format.\n\nAs of writing, 100% of the endpoints are implemented, each corresponding to a function with extensive documentation.\n\n\n## Installation\n\nAdd the following dependency to your `project.clj` file:\n\n    [eigenbahn/prometheus-api-client \"1.0.0\"]\n\n\n## General Usage\n\n#### Connection\n\nAll methods take a connection `conn` as a first argument. It's just a simple map in the form:\n\n```clojure\n{:url \"\u003cprometheus_base_url\u003e\"}\n```\n\nThe :url field value must contain the base URL of the Prometheus instance. It is not expected to contain the \"/api/v1\" part.\n\nSo to connect to a localhost instance:\n\n```clojure\n(def prom-conn {:url \"http://localhost:9090\"})\n```\n\n#### Time instants\n\nArguments corresponding to a time instant (and by extension the boundaries of a time range) can be in the following format:\n\n- any valid Clojure `inst` object\n- UNIX timestamp with second precision, with optional milliseconds after the comma, in string or number. E.g.: ``\"1600093006\"``, `1600093006`, `\"1600093006.148\"`, `1600093006.148`.\n- an [RFC3339](https://www.ietf.org/rfc/rfc3339.txt) string. E.g. `\"1996-12-19T16:39:57-08:00\"`.\n\n\n#### Optional arguments\n\nAll optional arguments are keyword arguments.\n\n\n#### Error / Exception handling\n\nErrors translate to HTTP error codes, throwing exceptions.\n\nAs we are relying on [clj-http.client](https://github.com/dakrone/clj-http), those exceptions are [Slingshot](https://github.com/scgilardi/slingshot) Stones. Refer to [this section](https://github.com/dakrone/clj-http#exceptions) to see how to handle them.\n\n\n#### Result extraction \u0026 conversion\n\nBy default, only the most sensible data in the API response is returned by each function.\n\nThis can be tweaked by adjusting the value of dynamic var `content-level`:\n\n- `::http-client`: raw value from `clj-http.client`, good for debugging\n- `::body`: HTTP body parsing into a clojure data structure\n- `::data`: `\"data\"` part of the prometheus response\n- `::best`: only the most sensible data for each endpoint (default)\n\nLikewise, we by default convert time series into more clojure-friendly data structures (maps) with timestamps converted to `inst` and used as keys and values parsed when scalar instead of just strings. This can be disabled by setting `convert-result` to false.\n\n\n## Example usage\n\nAll the endpoints are implemented.\nOnly the TSDB querying-related ones are presented here.\n\n#### Querying time series\n\n```clojure\n;; a single point at a given time (/query endpoint)\n(prometheus-api.client/query prom-conn \"scrape_duration_seconds\" :at 1600093006.148)\n;; -\u003e [{\"value\" {#inst \"2020-09-14T14:16:46.148000000-00:00\" 0.004643278},\n;;      \"metric\"\n;;      {\"job\" \"prometheus\",\n;;       \"instance\" \"localhost:9090\",\n;;       \"__name__\" \"scrape_duration_seconds\"}}]\n\n;; the last point\n(prometheus-api.client/query prom-conn \"scrape_duration_seconds\")\n;; -\u003e [{\"value\" {#inst \"2020-09-15T16:31:02.564000000-00:00\" 0.005696021},\n;;      \"metric\"\n;;      {\"job\" \"prometheus\",\n;;       \"instance\" \"localhost:9090\",\n;;       \"__name__\" \"scrape_duration_seconds\"}}]\n\n;; over a time range (/query-range endpoint)\n(prometheus-api.client/query-range prom-conn \"scrape_duration_seconds\"\n                                   #inst \"2020-09-14T12:16:04.148000000-00:00\" ; from\n                                   #inst \"2020-09-14T14:15:50.148000000-00:00\" ; to\n                                   14)                                         ; step (in seconds unless unit specified)\n;; -\u003e [{\"values\"\n;;      {#inst \"2020-09-14T12:47:02.000000000-00:00\" 0.00457012,\n;;       #inst \"2020-09-14T12:17:10.000000000-00:00\" 0.00456644,\n;;       ...\n;;       #inst \"2020-09-14T14:13:36.000000000-00:00\" 0.004636848},\n;;      \"metric\"\n;;      {\"job\" \"prometheus\",\n;;       \"instance\" \"localhost:9090\",\n;;       \"__name__\" \"scrape_duration_seconds\"}}]\n\n;; note that the the /query endpoint also allows querying over a relative range with a step\n;; e.g. the last 30 minutes grouped by 5 minutes\n(prometheus-api.client/query prom-conn \"scrape_duration_seconds[30m:5m]\")\n```\n\n\n#### List labels \u0026 series\n\n```clojure\n;; list of label names (/labels endpoint)\n(prometheus-api.client/labels prom-conn)\n;; -\u003e [\"__name__\" \"branch\" \"call\" ...]\n\n;; list of values for a given label (/label/\u003clabel_name\u003e/values endpoint)\n(prometheus-api.client/values-for-label prom-conn \"role\")\n;; -\u003e [\"endpoints\" \"ingress\" \"node\" \"pod\" \"service\"]\n\n;; list series by series matchers (/series endpoint)\n(prometheus-api.client/series prom-conn [\"up\" \"process_start_time_seconds{job=\\\"prometheus\\\"}\"])\n;; -\u003e [{\"job\" \"prometheus\",\n;;      \"instance\" \"localhost:9090\",\n;;      \"__name__\" \"process_start_time_seconds\"}\n;;     {\"job\" \"prometheus\", \"instance\" \"localhost:9090\", \"__name__\" \"up\"}]\n```\n\n\n## Similar projects \u0026 acknowledgement\n\nProject inspired by the excellent [full-spectrum/influxdb-client](https://github.com/full-spectrum/influxdb-client) library for InfluxDB.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feigenbahn%2Fprometheus-api-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feigenbahn%2Fprometheus-api-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feigenbahn%2Fprometheus-api-client/lists"}