{"id":24490462,"url":"https://github.com/theprez/prometheus-exporter-jdbc","last_synced_at":"2025-06-19T13:41:44.554Z","repository":{"id":47375125,"uuid":"512075067","full_name":"ThePrez/prometheus-exporter-jdbc","owner":"ThePrez","description":"Prometheus Client for IBM i","archived":false,"fork":false,"pushed_at":"2024-02-17T15:16:31.000Z","size":112,"stargazers_count":21,"open_issues_count":10,"forks_count":5,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-05-01T16:58:52.465Z","etag":null,"topics":["grafana","ibmi","jdbc","monitoring","prometheus","prometheus-exporter","sql"],"latest_commit_sha":null,"homepage":"","language":"Java","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/ThePrez.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":"2022-07-09T02:32:23.000Z","updated_at":"2024-02-02T05:57:05.000Z","dependencies_parsed_at":"2023-01-25T21:46:23.247Z","dependency_job_id":null,"html_url":"https://github.com/ThePrez/prometheus-exporter-jdbc","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThePrez%2Fprometheus-exporter-jdbc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThePrez%2Fprometheus-exporter-jdbc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThePrez%2Fprometheus-exporter-jdbc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThePrez%2Fprometheus-exporter-jdbc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ThePrez","download_url":"https://codeload.github.com/ThePrez/prometheus-exporter-jdbc/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234988195,"owners_count":18918097,"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","ibmi","jdbc","monitoring","prometheus","prometheus-exporter","sql"],"created_at":"2025-01-21T17:18:11.443Z","updated_at":"2025-04-13T23:08:03.143Z","avatar_url":"https://github.com/ThePrez.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# JDBC Prometheus Exporter\n\nPrometheus exporter for IBM i and other databases. This provides an interface for passive metrics collection. That is, Prometheus can scrape this exporter for metrics.\n\nAny JDBC driver may be used as a data source for Prometheus. The metrics are customizable. \nAny numeric metric available through SQL can be monitored using this client!\n\nThis exporter was built for and tested on IBM i as a way to monitor IBM i system and application status through SQL.\nAs such, its out-of-box-experience is centered around the IBM i use case.\n\n- [Installation and Startup](#installation-and-startup)\n  - [Known Breatking Changes](#known-breaking-changes)\n  - [Using another JDBC driver](#using-another-jdbc-driver)\n  - [Using the `nohup` utility](#using-the-nohup-utility)\n- [Running on a different port](#running-on-a-different-port)\n- [Prometheus Configuration](#prometheus-configuration)\n- [JSON Configuration](#json-configuration)\n  - [Valid values for JSON configuration](#valid-values-for-json-configuration)\n    - [`queries` element](#queries-element)\n- [Collection data modes](#collection-data-modes)\n  - [Single-row mode](#single-row-mode)\n  - [Multi-row mode](#multi-row-mode)\n- [Collection timing modes](#collection-timing-modes)\n  - [Interval-based](#interval-based)\n  - [Point-in-time](#point-in-time)\n- [Managing with Service Commander (IBM i only)](#managing-with-service-commander-ibm-i-only)\n\n## Installation and Startup\n\n1. Download the latest `prom-client-ibmi.jar` file from\n[the releases page](https://github.com/ThePrez/Prom-client-IBMi/releases).\nPlace this file the filesystem somewhere. \n1. From a command line, `cd` to the directory where you placed\n`prom-client-ibmi.jar` and run:\n```bash\njava -jar prom-client-ibmi.jar\n```\nCreate a default configuration file by responding `y` to the\nfollowing prompt:\n```bash\nConfiguration file config.json not found. Would you like to initialize one with defaults? [y] \n```\nYou Should see a series of messages about collectors being registered. If you see the\nfollowing message, the client is running successfully:\n```\n==============================================================\nSuccessfully started Prometheus client on port 9853\n==============================================================\n```\n\nIf you're not running on IBM i, you'll want to kill the program and modify\n`config.json` to have reasonable values for your needs. \n\n### Known breaking changes\n\n**In version 1.0**\n- The default value for `include_hostname` is now `false`. By default, the host name will not be included in the metric names (as the host name is included in the label). This may break existing configurations.\n- The SQL query specified can now contain multiple SQL statements, separated by `; `. This is implemented by a dump \"split\" and not by any SQL parser logic. As such, this will break any existing SQL query that correctly contains this string. \n\n### Using another JDBC driver\n\nThe IBM i JDBC driver is bundled with this exporter. \nIf you'd like to use a different JDBC driver, you will need to specify the necessary options\nin the configuration (namely, `driver_class` and `driver_uri`). You will also need to\nexplicitly add that driver to the class path. For instance:\n\n```\njava -cp prom-client-ibmi.jar:myjdbcdriver.jar com.ibm.jesseg.prometheus.MainApp\n```\n\n### Using the `nohup` utility\nIf you would like to run the program in the background so that you can exit\nyour shell and keep the Prometheus client running, you can use the `nohup` utility:\n```bash\nnohup java -jar prom-client-ibmi.jar \u003e prom-client.log 2\u003e\u00261\n```\n\n## Running on a different port\n\nThe Prometheus client port can be customized in several ways. The port\nis determined by the following, in order of precedence:\n- The `PORT` environment variable\n- The `promclient.port` Java system property\n- The `port` value of the JSON configuration file\n- The default value of 9853\n\n## Prometheus Configuration\n\nTo configure Prometheus, just add a target to the `scrape_configs` as done\nin the following sample configuration:\n\n```yaml\nscrape_configs:\n  - job_name: 'prometheus-jdbc'\n    metrics_path: '/metrics'\n    static_configs:\n      - targets: ['1.2.3.4:9853']\n```\n\n## JSON Configuration\n\nSee [config.json](./config.json) for an example JSON file, which contains the\nfollowing:\n```json\n{\n  \"port\": 9853,\n\n  \"queries\": [{\n      \"name\": \"System Statistics\",\n      \"interval\": 60,\n      \"enabled\": true,\n      \"prefix\": \"STATS\",\n      \"sql\": \"SELECT * FROM TABLE(QSYS2.SYSTEM_STATUS(RESET_STATISTICS=\u003e'YES',DETAILED_INFO=\u003e'ALL')) X\"\n    },\n    {\n      \"name\": \"System Activity\",\n      \"interval\": 20,\n      \"prefix\": \"SYSACT\",\n      \"enabled\": true,\n      \"sql\": \"SELECT * FROM TABLE(QSYS2.SYSTEM_ACTIVITY_INFO())\"\n    },\n    {\n      \"name\": \"number of remote connections\",\n      \"interval\": 30,\n      \"enabled\": true,\n      \"sql\": \"select COUNT(REMOTE_ADDRESS) as REMOTE_CONNECTIONS from qsys2.netstat_info where TCP_STATE = 'ESTABLISHED' AND REMOTE_ADDRESS != '::1' AND REMOTE_ADDRESS != '127.0.0.1'\"\n    },\n    {\n      \"name\": \"Memory Pool Info\",\n      \"interval\": 100,\n      \"enabled\": true,\n      \"multi_row\": true,\n      \"prefix\": \"MEMPOOL\",\n      \"sql\": \"SELECT POOL_NAME,CURRENT_SIZE,DEFINED_SIZE,MAXIMUM_ACTIVE_THREADS,CURRENT_THREADS,RESERVED_SIZE FROM TABLE(QSYS2.MEMORY_POOL(RESET_STATISTICS=\u003e'YES')) X\"\n    },\n    {\n      \"name\": \"Plan Cache Analysis\",\n      \"interval\": 45,\n      \"multi_row\": true,\n      \"enabled\": true,\n      \"prefix\": \"PLAN_CACHE\",\n      \"sql\": \"call QSYS2.DUMP_PLAN_CACHE_PROPERTIES('QTEMP', 'PCPROP1');\nselect replace(upper(HEADING), ' ', '_') as HEADING, value,\n       case\n         when\n           (left(value, 8) = '*DEFAULT')\n           then\n             substr(\n               value, locate_in_string(value, '(', 1) + 1, locate_in_string(value, ')', 1) -\n                 locate_in_string(value, '(', 1) - 1)\n         when (substr(value, 9, 1) = '(') then substr(value, 1, 8)\n         else value\n       end as value\n  from qtemp.pcprop1\n  where value is not null and\n        value \u003c\u003e '*AUTO' and\n        length(trim(value)) \u003e 0 and\n        value \u003c\u003e '-' and\n        replace(upper(HEADING), ' ', '_') not in ('TIME_OF_SUMMARY',\n          'PLAN_CACHE_CREATION_TIME', 'LAST_PLAN_CACHE_AUTOSIZING_ADJUSTMENT',\n          'LAST_AUTOSIZING_LIMITED_DUE_TO_TEMPORARY_STORAGE', 'TIME_PLAN_CACHE_WAS_LAST_PRUNED',\n          'ACTIVITY_THRESHOLDS_START_TIME')\"\n    },\n    {\n      \"name\": \"Named Temp Storage buckets\",\n      \"interval\": 90,\n      \"multi_row\": true,\n      \"enabled\": true,\n      \"prefix\": \"TMP_STG_BUCKETS\",\n      \"sql\": \"select replace(upper(REPLACE(GLOBAL_BUCKET_NAME, '*','')), ' ', '_') as NAME, BUCKET_CURRENT_SIZE as CURRENT_SIZE, BUCKET_PEAK_SIZE as PEAK_SIZE from QSYS2.SystmpSTG where GLOBAL_BUCKET_NAME IS NOT NULL\"\n    },\n    {\n      \"name\": \"Unnamed Temp Storage buckets\",\n      \"interval\": 90,\n      \"multi_row\": false,\n      \"enabled\": true,\n      \"prefix\": \"UNNAMED_TMP_STG_BUCKETS\",\n      \"sql\": \"select SUM(BUCKET_CURRENT_SIZE) as CURRENT_SIZE, sum(BUCKET_PEAK_SIZE) as PEAK_SIZE from QSYS2.SystmpSTG where GLOBAL_BUCKET_NAME IS NULL\"\n    },\n    {\n      \"name\": \"HTTP Server metrics\",\n      \"interval\": 60,\n      \"multi_row\": true,\n      \"enabled\": true,\n      \"prefix\": \"HTTP\",\n      \"sql\": \"select SERVER_NAME concat '_' concat replace(HTTP_FUNCTION, ' ','_') as SERVER_FUNC, SERVER_NORMAL_CONNECTIONS, SERVER_SSL_CONNECTIONS, SERVER_ACTIVE_THREADS, SERVER_IDLE_THREADS, SERVER_TOTAL_REQUESTS, SERVER_TOTAL_REQUESTS_REJECTED, SERVER_TOTAL_RESPONSES, REQUESTS, RESPONSES, NONCACHE_RESPONSES, BYTES_RECEIVED, BYTES_SENT, NONCACHE_PROCESSING_TIME, CACHE_PROCESSING_TIME from qsys2.HTTP_SERVER_INFO      \"\n    },\n    {\n      \"name\": \"System Values\",\n      \"interval\": 333,\n      \"multi_row\": true,\n      \"prefix\": \"SYSVAL\",\n      \"sql\": \"select SYSTEM_VALUE_NAME,CURRENT_NUMERIC_VALUE from QSYS2.SYSTEM_VALUE_INFO where CURRENT_NUMERIC_VALUE IS NOT NULL\"\n    }\n  ]\n}\n```\n\nNotes about the JSON configuration file:\n- The program will create the default version for you if you don't create one yourself\n- The location of the configuration file can be customized by the `promclient.config` Java system property\n- The default configuration gathers metrics with just two queries. You can customize your metrics collection with any SQL query you'd like to monitor with prometheus.\n- For each query, the `interval` value represents the interval between data collection attempts\nfor that query, in seconds.\n\n### Valid values for JSON configuration\n\n| Key name           | Type     | required? | Description                                      |\n| ------------------ | -------- | ----------| -------------------------------------------------|\n| `queries`          | array    | yes       | Array of elements specifying which SQL queries to run |  \n| `driver_class`     | String   | no        | The JDBC driver class (default: \"com.ibm.as400.access.AS400JDBCDriver\") |\n| `driver_uri`       | String   | no        | The JDBC connection string (default: \"jdbc:as400://localhost\")    | \n| `hostname`         | String   | no        | The hostname of the system to connect to (default: localhost)      | \n| `username`         | String   | no        | Username to be used for the connection | \n| `password`         | String   | no        | Password for the connection. **NOT SECURE** |\n\n**NOTE: You may be prompted for any needed values (for instance, a password) at the command line if not specified in the JSON configuration**\n\n\n#### `queries` element\n\nThe `queries` element contains an array. Each element in the array can have the following values:\n| Key name           | Type     | required? | Description                                      |\n| ------------------ | -------- | ----------| -------------------------------------------------|\n| `sql`              | String   | yes       | The SQL query                                    |\n| `name`             | String   | no        | A human-readable name for the query              | \n| `interval`         | Integer  | no        | The interval to wait between queries (default: infinity)     | \n| `prefix`           | String   | no        | A prefix to be used in the Prometheus gauge name | \n| `include_hostname` | boolean  | no        | Whether to include the hostname in the Prometheus gauge name (default: true) |\n| `enabled`          | boolean  | no        | Whether this SQL query is enabled (default: true) |\n| `multi_row`        | boolean  | no        | Whether to enable multi-row mode (default: false) |\n\n\n\n**IMPORTANT NOTES ABOUT COLLECTED METRICS**\n- Only numeric values will be collected\n- The values will be reported to Prometheus in the format\n```\nhostname__prefix_identifier\n```\n(where `hostname` is the IBM i self-resolved hostname and `column` is the SQL column)\n- You can tailor the metric name in prometheus by changing the column name via the SQL query (using the SELECT `AS XXXX` syntax)\n- The `prefix` is only included if specified in the configuration\n- The `hostname` can be excluded via configuration\n- The `identifier` is the column name when running in single-row mode\n\n## Collection data modes\n\n### Single-row mode\n\nThe default behavior for processing query output is single-row mode. If feasible, this is the recommended\nway to collect metrics. \nIn single-row mode, only the first row of results are processed, but the gauge names can be computed up front,\nsince the identifier for the gauge is simply the column name. \n\n\n### Multi-row mode\n\nMulti-row mode allows you to collect metrics from multiple rows of a JDBC query. When using multi-row mode,\nthe value of the first column in each result is used to formulate a gauge name each time the query is run. \nThis has negative implications if the result set data does not have a consistent value in the first column.\n\n## Collection timing modes\n\n### Interval-based\n\nThe `interval` value for a query in the JSON configuration indicates how long to pause between queries.\nWhen using this technique, responses to Prometheus will be based on the most recent value collected.\nThis could mean the same collection value is repeated in Prometheus, or that values may be lost. For\ninstance, if using a 60-second query interval:\n- If Prometheus scrapes every two minutes, some values will not be propagated to Prometheus\n- If Prometheus scrapes every 30 seconds, the same collected value may be reported more than once\n\nFor efficiency's sake, this is the default behavior. This allows for aggressive Prometheus scrape intervals\nwithout putting excessive load on the monitored system.\n\n\n### Point-in-time\n\nIf omitted, the `interval` value for a query in the JSON configuration defaults to infinity. Metrics can be\ngathered upon-request by way of the `/metrics_now` endpoint. This approach provides the most up-to-date\ninformation to Prometheus, at intervals defined by Prometheus. However, use this approach with caution. \nIt exposes the monitored system to excessive load if metrics are scraped often. When using this approach,\nthe exporter still limits the query frequency to 5-second intervals.\n\n## Managing with Service Commander (IBM i only)\n\nFirst, install Service Commander (package name `service-commander`)\nversion 1.5.1 or later. \n\nThen, from a command line, `cd` to the directory where you placed\n`prom-client-ibmi.jar` and run:\n```bash\njava -jar prom-client-ibmi.jar sc\n```\nFollow the on-screen instructions. A `prometheus.yml` file will be created.\nDo not delete this file.\n\nThe default configuration adds a `prometheus` to the `autostart` group\nto be launched automatically at IPL.\n\n\n# Installation and Startup (off IBM i)\n\nThis Prometheus client can be run on a different platform and connect remotely to\nIBM i to gather statistics. Currently, however, only one remote system at a time\nis supported. \n\nTo enable this, populate `username`, `hostname`, and (optionally) `password` in\nthe `config.json` file that is generated upon initial startup.\n\nFor instance:\n\n```json\n  \"username\": \"myuser\",\n  \"hostname\": \"systemname\",\n  \"password\": \"mypassword\"\n```\n\nNote, however, that putting your password in a plaintext file is not recommended. \nInstead, configure the username and hostname. You will be prompted for the password\nat runtime. \n\nFor instance:\n\n```json\n  \"username\": \"myuser\",\n  \"hostname\": \"systemname\"\n```\n\n\n(documentation forthcoming)\n\n# Metrics gathered with default config (IBM i)\n\n- TOTAL_JOBS_IN_SYSTEM\n- MAXIMUM_JOBS_IN_SYSTEM\n- ACTIVE_JOBS_IN_SYSTEM\n- INTERACTIVE_JOBS_IN_SYSTEM\n- ELAPSED_TIME\n- ELAPSED_CPU_USED\n- ELAPSED_CPU_SHARED\n- ELAPSED_CPU_UNCAPPED_CAPACITY\n- CONFIGURED_CPUS\n- CURRENT_CPU_CAPACITY\n- AVERAGE_CPU_RATE\n- AVERAGE_CPU_UTILIZATION\n- AVERAGE_CPU_RATE_REAL\n- AVERAGE_CPU_UTILIZATION_REAL\n- MINIMUM_CPU_UTILIZATION\n- MAXIMUM_CPU_UTILIZATION\n- SQL_CPU_UTILIZATION\n- MAIN_STORAGE_SIZE\n- SYSTEM_ASP_STORAGE\n- TOTAL_AUXILIARY_STORAGE\n- SYSTEM_ASP_USED\n- CURRENT_TEMPORARY_STORAGE\n- MAXIMUM_TEMPORARY_STORAGE_USED\n- PERMANENT_ADDRESS_RATE\n- TEMPORARY_ADDRESS_RATE\n- TEMPORARY_256MB_SEGMENTS\n- TEMPORARY_4GB_SEGMENTS\n- PERMANENT_256MB_SEGMENTS\n- PERMANENT_4GB_SEGMENTS\n- TEMPORARY_JOB_STRUCTURES_AVAILABLE\n- PERMANENT_JOB_STRUCTURES_AVAILABLE\n- TOTAL_JOB_TABLE_ENTRIES\n- AVAILABLE_JOB_TABLE_ENTRIES\n- IN_USE_JOB_TABLE_ENTRIES\n- ACTIVE_JOB_TABLE_ENTRIES\n- JOBQ_JOB_TABLE_ENTRIES\n- OUTQ_JOB_TABLE_ENTRIES\n- JOBLOG_PENDING_JOB_TABLE_ENTRIES\n- PARTITION_ID\n- NUMBER_OF_PARTITIONS\n- ACTIVE_THREADS_IN_SYSTEM\n- PARTITION_GROUP_ID\n- SHARED_PROCESSOR_POOL_ID\n- DEFINED_MEMORY\n- MINIMUM_MEMORY\n- MAXIMUM_MEMORY\n- MEMORY_INCREMENT\n- PHYSICAL_PROCESSORS\n- PHYSICAL_PROCESSORS_SHARED_POOL\n- MAXIMUM_PHYSICAL_PROCESSORS\n- DEFINED_VIRTUAL_PROCESSORS\n- VIRTUAL_PROCESSORS\n- MINIMUM_VIRTUAL_PROCESSORS\n- MAXIMUM_VIRTUAL_PROCESSORS\n- DEFINED_PROCESSING_CAPACITY\n- PROCESSING_CAPACITY\n- UNALLOCATED_PROCESSING_CAPACITY\n- MINIMUM_REQUIRED_PROCESSING_CAPACITY\n- MAXIMUM_LICENSED_PROCESSING_CAPACITY\n- MINIMUM_PROCESSING_CAPACITY\n- MAXIMUM_PROCESSING_CAPACITY\n- PROCESSING_CAPACITY_INCREMENT\n- DEFINED_INTERACTIVE_CAPACITY\n- INTERACTIVE_CAPACITY\n- INTERACTIVE_THRESHOLD\n- UNALLOCATED_INTERACTIVE_CAPACITY\n- MINIMUM_INTERACTIVE_CAPACITY\n- MAXIMUM_INTERACTIVE_CAPACITY\n- DEFINED_VARIABLE_CAPACITY_WEIGHT\n- VARIABLE_CAPACITY_WEIGHT\n- UNALLOCATED_VARIABLE_CAPACITY_WEIGHT\n- THREADS_PER_PROCESSOR\n- DISPATCH_LATENCY\n- DISPATCH_WHEEL_ROTATION_TIME\n- TOTAL_CPU_TIME\n- INTERACTIVE_CPU_TIME\n- INTERACTIVE_CPU_TIME_ABOVE_THRESHOLD\n- UNUSED_CPU_TIME_SHARED_POOL\n- JOURNAL_RECOVERY_COUNT\n- JOURNAL_CACHE_WAIT_TIME\n- REMOTE_CONNECTIONS\n\n# Sample screenshot (visualization w/Grafana)\n\n![image](https://user-images.githubusercontent.com/17914061/180038306-30724eae-83b2-42c3-b6d5-da2e9b239a25.png)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheprez%2Fprometheus-exporter-jdbc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftheprez%2Fprometheus-exporter-jdbc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheprez%2Fprometheus-exporter-jdbc/lists"}