{"id":13560668,"url":"https://github.com/timescale/pg_prometheus","last_synced_at":"2025-04-03T16:30:57.012Z","repository":{"id":56543051,"uuid":"97644583","full_name":"timescale/pg_prometheus","owner":"timescale","description":"PostgreSQL extension for Prometheus data","archived":true,"fork":false,"pushed_at":"2020-11-01T17:33:20.000Z","size":72,"stargazers_count":214,"open_issues_count":21,"forks_count":44,"subscribers_count":17,"default_branch":"master","last_synced_at":"2024-11-04T12:39:56.555Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","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/timescale.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":"2017-07-18T21:14:46.000Z","updated_at":"2024-08-31T10:54:13.000Z","dependencies_parsed_at":"2022-08-15T20:40:24.553Z","dependency_job_id":null,"html_url":"https://github.com/timescale/pg_prometheus","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timescale%2Fpg_prometheus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timescale%2Fpg_prometheus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timescale%2Fpg_prometheus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timescale%2Fpg_prometheus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/timescale","download_url":"https://codeload.github.com/timescale/pg_prometheus/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247036916,"owners_count":20873047,"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":[],"created_at":"2024-08-01T13:00:48.486Z","updated_at":"2025-04-03T16:30:56.729Z","avatar_url":"https://github.com/timescale.png","language":"C","funding_links":[],"categories":["C"],"sub_categories":[],"readme":"# **SUNSET NOTICE**\n\nWe'll be sunsetting this project in the coming months as we focus on a new implementation with additional functionality\nand better support for new TimescaleDB features (such as compression). You can find the new project at\n[https://github.com/timescale/promscale](https://github.com/timescale/promscale).\n\nMore details can be found in our [design document](https://tsdb.co/prom-design-doc) for the new project.\n\nThis project will continue only in maintenance mode.\n\n# Prometheus metrics for PostgreSQL\n\n`pg_prometheus` is an extension for PostgreSQL that defines a\nPrometheus metric samples data type and provides several storage formats\nfor storing Prometheus data.\n\nRelated packages to install:\n- [Prometheus remote storage adaptor](https://github.com/timescale/prometheus-postgresql-adapter) (required)\n- [TimescaleDB](https://github.com/timescale/timescaledb) (optional\nfor better performance and scalability)\n\n## Running from Docker\n\nA PostgreSQL docker image with both pg_prometheus and TimescaleDB installed is\navailable in Docker Hub at [timescale/pg_prometheus](https://hub.docker.com/r/timescale/pg_prometheus/).\n\nExample usage:\n```\ndocker run --name pg_prometheus -d -p 5432:5432 timescale/pg_prometheus:latest-pg11 postgres \\\n      -csynchronous_commit=off\n```\n\nNote that this image inherits from the official [postgres image](https://hub.docker.com/_/postgres/) and\nso all options documented there are applicable to this image as well. Especially\nimportant for users that wish to persist data outside of docker volumes is the\n`PGDATA` environmental variable and accompanying volume mount.\n\n## Installation\n\n### Requirements\n\n* Install PostgreSQL libraries and headers for C language backend development (https://www.postgresql.org/download/)\n* Make sure you have PostgreSQL bin in your `PATH` and the **postgresql-devel** package for your version of PostgreSQL before compiling from source\n\nTo install from source, do:\n\n```bash\nmake\nmake install # Might require super user permissions\n```\n\nEdit `postgresql.conf` to include the `pg_prometheus` extension:\n\n```\nshared_preload_libraries = 'pg_prometheus'\n```\n\nStart PostgreSQL and install the extension as a superuser using the `psql` CLI:\n```SQL\nCREATE EXTENSION pg_prometheus;\n```\n\nOptionally grant permissions to the database user (`prometheus`) that will own the Prometheus data:\n\n```SQL\n-- Create the role\nCREATE ROLE prometheus WITH LOGIN PASSWORD 'secret';\n\n-- Grant access to the schema\nGRANT ALL ON SCHEMA prometheus TO prometheus;\n```\n\nThis also requires superuser privileges.\n\n##  Integrating with Prometheus\n\nFor quickly connecting Prometheus to pg_prometheus simply\nconnect the [Prometheus PostgreSQL adapter](https://github.com/timescale/prometheus-postgresql-adapter) to a\ndatabase that has pg_prometheus installed.\n\nFor more technical details, or to use pg_prometheus without Prometheus, read below.\n\n\n## Creating the Prometheus tables.\n\nTo create the appropriate Prometheus tables use:\n```SQL\nSELECT create_prometheus_table('metrics');\n```\n\nThis will create a `metrics` table for inserting data in the  [Prometheus exposition\nformat](https://prometheus.io/docs/instrumenting/exposition_formats/)\nusing the Prometheus data type. It will also create\na `metrics_view` to easily query data.\n\nOther supporting tables may also be created depending on the storage format (see\nbelow).\n\n## Inserting data\n\nWith either storage format, data can be inserted in Prometheus format into the\nmain table (e.g. `metrics` in our running example). Data should be formatted\naccording to the Prometheus exposition format.\n\n```SQL\nINSERT INTO metrics VALUES ('cpu_usage{service=\"nginx\",host=\"machine1\"} 34.6 1494595898000');\n```\n\nSince `metrics` is a view, and PostgreSQL does not allow `COPY` to views, we\ncreate a specialized table to be the target of copy commands for normalized\ntables (raw tables could write directly to the underlying `_sample` table).\nBy default, copy tables have a `_copy` suffix.\n\nOne interesting usage is to scrape a Prometheus endpoint (e.g. `http://localhost:8080/metrics`) directly (without using Prometheus):\n\n```bash\ncurl http://localhost:8080/metrics | grep -v \"^#\" | psql -h localhost -U postgres -p 5432 -c \"COPY metrics_copy FROM STDIN\"\n```\n\n## Querying data\n\nThe `metrics` view has the following schema:\n\n```SQL\n  Column |           Type           | Modifiers\n --------+--------------------------+-----------\n  time   | timestamp with time zone |\n  name   | text                     |\n  value  | double precision         |\n  labels | jsonb                    |\n```\n\nAn example query would be\n```SQL\nSELECT time, value\nFROM metrics\nWHERE time \u003e NOW() - interval '10 min' AND\n      name = 'cpu_usage' AND\n      labels @\u003e '{ \"service\": \"nginx\"}';\n```\n\n## Storage formats\n\nPg_prometheus allows two main ways of storing Prometheus metrics: raw and\nnormalized (the default). With raw, a table simply stores all the Prometheus samples in a single\ncolumn of type `prom_sample`.  The normalized storage format\nseparates out the labels into a separate table. The advantage of the normalized\nformat is disk space savings when labels are long and repetitive.\n\nNote that the `metrics` view can be used to query and insert data\nregardless of the storage format and serves to hide the underlying storage from the user.\n\n### Raw format\n\nIn raw format, data is stored in a table with one column of type `prom_sample`.\nTo define a raw table use pass `normalized_tables=\u003efalse` to `create_prometheus_table`.\nThis will also create appropriate indexes on the raw table. The schema is:\n\n```SQL\n  Column   |           Type           | Modifiers\n-----------+--------------------------+-----------\n sample    | prom_sampe               |\n```\n\n\n### Normalized format\n\nIn the normalized format, data is stored in two tables. The `values` table\nholds the data values with a foreign key to the labels. It has the following schema:\n\n```SQL\n  Column   |           Type           | Modifiers\n-----------+--------------------------+-----------\n time      | timestamp with time zone |\n value     | double precision         |\n labels_id | integer                  |\n```\n\nLabels are stored in a companion table called `labels`\n(note that `metric_name` is in its own column since it is always\npresent):\n\n```SQL\n   Column    |  Type   |                          Modifiers\n-------------+---------+-------------------------------------------------------------\n id          | integer | not null default nextval('metrics_labels_id_seq'::regclass)\n metric_name | text    | not null\n labels      | jsonb   |\n```\n\n## Use with TimescaleDB\n\n[TimescaleDB](http://www.timescale.com/) scales PostgreSQL for\ntime-series data workloads (of which metrics is one example). If\nTimescaleDB is installed, pg_prometheus will use it by default.\nTo install TimescaleDB, follow the instruction [here](http://docs.timescale.com/getting-started/installation).\nYou can explicitly control whether or not to use TimescaleDB with the\n`use_timescaledb` parameter to `create_prometheus_table`.\n\nFor example, the following will force pg_prometheus to use Timescale (and will\nerror out if it isn't installed):\n```SQL\nSELECT create_prometheus_table('metrics',use_timescaledb=\u003etrue);\n```\n\n## Contributing\n\nWe welcome contributions to this extension, which like TimescaleDB is\nreleased under the Apache2 Open Source License.\nThe same [Contributors\nAgreement](//github.com/timescale/timescaledb/blob/master/CONTRIBUTING.md)\napplies; please sign the [Contributor License\nAgreement](https://cla-assistant.io/timescale/pg_prometheus) (CLA) if\nyou're a new contributor.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimescale%2Fpg_prometheus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftimescale%2Fpg_prometheus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimescale%2Fpg_prometheus/lists"}