{"id":19247936,"url":"https://github.com/litespeedtech/litespeed-prometheus-exporter","last_synced_at":"2025-04-21T11:33:55.149Z","repository":{"id":186819105,"uuid":"675729017","full_name":"litespeedtech/litespeed-prometheus-exporter","owner":"litespeedtech","description":null,"archived":false,"fork":false,"pushed_at":"2025-01-17T15:26:36.000Z","size":58965,"stargazers_count":10,"open_issues_count":1,"forks_count":5,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-01T12:54:38.586Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","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/litespeedtech.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,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-08-07T15:31:53.000Z","updated_at":"2025-01-17T15:26:40.000Z","dependencies_parsed_at":"2024-05-31T19:07:31.466Z","dependency_job_id":"72c347e9-7935-4450-bc1d-c8201f22a9f8","html_url":"https://github.com/litespeedtech/litespeed-prometheus-exporter","commit_stats":null,"previous_names":["litespeedtech/litespeed-prometheus-exporter"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/litespeedtech%2Flitespeed-prometheus-exporter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/litespeedtech%2Flitespeed-prometheus-exporter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/litespeedtech%2Flitespeed-prometheus-exporter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/litespeedtech%2Flitespeed-prometheus-exporter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/litespeedtech","download_url":"https://codeload.github.com/litespeedtech/litespeed-prometheus-exporter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250048107,"owners_count":21366176,"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-11-09T18:05:44.052Z","updated_at":"2025-04-21T11:33:55.127Z","avatar_url":"https://github.com/litespeedtech.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# LiteSpeed Prometheus Exporter\n\nThe LiteSpeed Prometheus Exporter is a specially designed Prometheus application and uses the LiteSpeed Enterprise or the OpenLiteSpeed Web Server controller to export Prometheus compatible data which can also be used by Grafana and other compatible applications.\n\nBesides giving useful information about LiteSpeed itself, it is an integral part of the LiteSpeed Containers product, in particular in exporting to Prometheus statistical information useful about individual user's resource consumption.  If LiteSpeed Containers are activated, cgroups information will be automatically exported.\n\n## Installation\n\nThese installation instructions assume you're downloading the compressed binary and installing from there, which will work for most x64 environments.  You can also build the package from the included Makefile if you need it on another architecture.\n\nYou must install the exporter on the LiteSpeed machine where the information is to be exported from.  Prometheus can run on another machine, but this software must be installed on the LiteSpeed machine to be monitored.\n\nFrom a command prompt, after downloading the software, use the tar command to extract the binary (substitute `VERSION` with the actual version of the software):\n\n```\ntar xf lsws-prometheus-exporter.VERSION.tgz\n```\n\nThat will create a `lsws-prometheus-exporter` directory.  Make that your default directory and run the install script as root:\n\n```\ncd lsws-prometheus-exporter\nsudo ./install.sh\n```\n\nYou are then prompted:\n\n```\nCert file name [ENTER for no HTTPS]: \n```\n\nPress [ENTER] by itself to use HTTP only for Prometheus connections to the exporter.  If you want to require HTTPS connections from Prometheus, enter a cert file name which is stored in a permanent location to be used by the service in PEM file format.  You will then be asked for a matching Key file name.\n\nThe service is then installed and started.\n\n## Configuring Prometheus\n\nPrometheus is generally configured using the `prometheus.yml` file in the `prometheus` directory.  You should see the [Prometheus Configuration documentation](https://prometheus.io/docs/prometheus/latest/configuration/configuration/) for details.  To add a LiteSpeed server running on the local machine, add to the `scrape-configs:` section:\n\n```\n  - job_name: \"litespeed_prometheus_exporter\"\n    static_configs:\n      - targets: [\"localhost:9936\"]\n    scrape_interval: 1m\n```\n\nA similar configuration but with the requirement of HTTPS (assuming you provided the cert and key files during exporter install):\n\n```\n  - job_name: \"litespeed_prometheus_exporter\"\n    scheme: https\n    static_configs:\n      - targets: [\"localhost:9936\"]\n    scrape_interval: 1m       \n```\n\n## Metrics Exported\n\n### Overall Metrics\n\nThe LiteSpeed metrics export includes the following overall metrics. In the `.rtreport` files, these metrics are at the top and don't repeat. For example:\n\n```\nVERSION: LiteSpeed Web Server/Enterprise/6.1.2\nUPTIME: 02:56:01\nBPS_IN: 0, BPS_OUT: 0, SSL_BPS_IN: 0, SSL_BPS_OUT: 0\nMAXCONN: 10000, MAXSSL_CONN: 10000, PLAINCONN: 0, AVAILCONN: 10000, IDLECONN: 0, SSLCONN: 0, AVAILSSL: 10000\n```\n\nThe titles to the table mean:\n\n- **Name** is the Prometheus name for the metric.  Each name will have a `litespeed_` prefix.\n- **Scraped Value** is the source from the `.rtreport` file the value originates from\n- **Description** is a simple description of the meaning of the parameter.\n- **Type** is either `Gauge` for values which can go up or down or `Counter` for values which can only go up.\n\n\n| Name | Scraped Value | Description | Type |\n| - | - | - | - |\n| `litespeed_available_connections` | `AVAILCONN` | Available number of connections | Gauge |\n| `litespeed_available_ssl_connections` | `AVAILSSL` | Available number of SSL (https) connections | Gauge |\n| `litespeed_current_http_connections` | `PLAINCONN` | Current number of http connections | Gauge |\n| `litespeed_current_idle_connections` | `IDLECONN` | Current number of idle connections | Gauge |\n| `litespeed_current_ssl_connections` | `SSLCONN` | Current number of SSL (https) connections | Gauge |\n| `litespeed_exporter_scrapes_failures_total` | - | The number of failed scrapes. | Counter |\n| `litespeed_exporter_scrapes_total` | - | The total number of scrapes. | Counter |\n| `litespeed_incoming_http_bytes_per_second` | `BPS_IN` | Incoming number of bytes per second over HTTP | Gauge |\n| `litespeed_incoming_ssl_bytes_per_second` | `SSL_BPS_IN` | Incoming number of bytes per second over HTTPS | Gauge |\n| `litespeed_maximum_http_connections` | `MAXCONN` | Maximum configured http connections | Counter |\n| `litespeed_maximum_ssl_connections` | `MAXSSL_CONN` | Maximum configurations SSL (https) connections | Counter |\n| `litespeed_outgoing_http_bytes_per_second` | `BPS_OUT` | Outgoing number of bytes per second over HTTP | Gauge |\n| `litespeed_outgoing_ssl_bytes_per_second` | `SSL_BPS_OUT` | Outgoing number of bytes per second over HTTPS | Gauge |\n| `litespeed_up` | - | Whether LiteSpeed is up or down (`1` or `0`) | Gauge |\n| `litespeed_version` | `VERSION` | Returns whether LiteSpeed is up or down and the `version` field returns the text `LiteSpeed Web Server/Enterprise/6.1.2` | Gauge |\n\n### VHost (REQRATE) Metrics \n\nThe LiteSpeed metrics exported include the following VHost (virtual host) metrics.  In the `.rtreport*` files, these metrics repeat and have a `REQ_RATE` prefix with the first line representing the total and subsequent lines for VHosts which are defined and accessed in the conventional way.  For example:\n\n```\nREQ_RATE []: REQ_PROCESSING: 0, REQ_PER_SEC: 0.2, TOT_REQS: 10, PUB_CACHE_HITS_PER_SEC: 0.0, TOTAL_PUB_CACHE_HITS: 0, PRIVATE_CACHE_HITS_PER_SEC: 0.0, TOTAL_PRIVATE_CACHE_HITS: 0, STATIC_HITS_PER_SEC: 0.0, TOTAL_STATIC_HITS: 0\nREQ_RATE [Example]: REQ_PROCESSING: 0, REQ_PER_SEC: 0.2, TOT_REQS: 10, PUB_CACHE_HITS_PER_SEC: 0.0, TOTAL_PUB_CACHE_HITS: 0, PRIVATE_CACHE_HITS_PER_SEC: 0.0, TOTAL_PRIVATE_CACHE_HITS: 0, STATIC_HITS_PER_SEC: 0.0, TOTAL_STATIC_HITS: 0\n```\n\nNote that in the Prometheus table each VHost, including the overall one will be assigned a separate line; in the graph, each VHost will be assigned a separate color.\n\nEach Prometheus Name will include, besides the `litespeed_` prefix, a `_per_vhost` suffix.\n\n| Name | Scraped Value | Description | Type |\n| - | - | - | - |\n| `litespeed_current_requests_per_vhost` | `REQ_PROCESSING` | Current number of requests in flight | Gauge |\n| `litespeed_outgoing_bytes_per_second_per_vhost` | `BPS_OUT` | Current number of bytes per second outgoing.  Only available for configured VHosts | Gauge |\n| `litespeed_private_cache_hits_per_second_per_vhost` | `PRIVATE_CACHE_HITS_PER_SEC` | Private cache hits per second | Gauge |\n| `litespeed_private_cache_hits_per_vhost` | `TOTAL_PRIVATE_CACHE_HITS` | Total private cache hits | Counter |\n| `litespeed_public_cache_hits_per_second_per_vhost` | `PUB_CACHE_HITS_PER_SEC` | Public cache hits per second | Gauge |\n| `litespeed_public_cache_hits_per_vhost` | `TOTAL_PUB_CACHE_HITS` | Total public cache hits | Counter |\n| `litespeed_requests_per_second_per_vhost` | `REQ_PER_SEC` | Requests per second | Gauge |\n| `litespeed_static_hits_per_second_per_vhost` | `STATIC_HITS_PER_SEC` | Static file requests per second | Gauge |\n| `litespeed_static_hits_per_vhost` | `TOTAL_STATIC_HITS` | Total number of static file hits | Counter |\n| `litespeed_total_requests_per_vhost` | `TOT_REQS` | Total number of requests | Counter |\n\n\n### Applications Metrics (EXTAPP)\n\nLiteSpeed exports what is prefixed as external application metrics (`EXTAPP`).  There are 3 names in brackets before the metrics:\n\n- The application type.  In the example below it's LSAPI\n- The VHost (if the application is defined per VHost).\n- The application name.  The application in the example below is a wsgiApp, which is a mechanism for Python applications.\n\n```\nEXTAPP [LSAPI] [] [wsgiApp]: CMAXCONN: 35, EMAXCONN: 35, POOL_SIZE: 1, INUSE_CONN: 0, IDLE_CONN: 1, WAITQUE_DEPTH: 0, REQ_PER_SEC: 0.1, TOT_REQS: 1\n```\n\nEach Prometheus Name will include, besides the `litespeed_` prefix, a `_per_app` suffix.\n\n| Name | Scraped Value | Description | Type |\n| - | - | - | - |\n| `litespeed_config_max_connections_per_app` | `CMAXCONN` | Configured maximum number of connections | Gauge |\n| `litespeed_connections_idle_per_app` | `IDLE_CONN` | Number of idle connections | Gauge |\n| `litespeed_connections_in_use_per_app` | `INUSE_CONN` | Number of connections in use | Gauge |\n| `litespeed_current_sessions_per_app` | `SESSIONS` | Current number of sessions | Gauge |\n| `litespeed_pool_count_per_app` | `POOL_SIZE` | Total number of pools | Gauge |\n| `litespeed_pool_max_connections_per_backend` | `EMAXCONN` | Maximum number of connections for the pool | Gauge |\n| `litespeed_requests_per_second_per_backend` | `REQ_PER_SEC` | Number of requests per second | Gauge |\n| `litespeed_total_requests_per_backend` | `TOT_REQS` | Total number of requests | Counter |\n| `litespeed_wait_queue_depth_per_backend` | `WAITQUE_DEPTH` | Depth of the waiting queue | Gauge |\n\n### CGroups metrics\n\nCGroups metrics will be exported by default if LiteSpeed Containers is enabled and the system is capable of cgroups v2.  Metrics are exported in the following form:\n\n```\n   cgroups_PREFIX_SUFFIX\n```\n\nWhere PREFIX is one of the following:\n- **cpu**: CPU utilization statistics.\n- **io**: Read and write utilization statistics.\n- **memory**: Amount of memory utilization.\n- **pids**: Number of tasks.\n  \nSUFFIX names are listed in each table below.\n\nStatistics are in two forms: raw and calculated.  The calculated ones tend to be the most useful, however they are calculated using the raw statistics.\n\nYou are given each statistic with a `uid` qualifier.  The `uid` of `.` is used to represent the system as a whole.  All other uids are numeric system UIDs.\n\nFor example, there is an exported value `cgroups_cpu_difference_microseconds`.  It has a PREFIX of `cpu` and a SUFFIX of `difference_microseconds` and is documented below.\n\n#### CPU prefix\n\n| Suffix | Calculated | Description | Type |\n| - | - | - | - |\n| difference_microseconds | X | CPU difference in the last interval in microseconds per user | Gauge\n| loadavg_percent |   | The contents of the /proc/loadavg file for the last minute for the system as a whole.  Not available for each uid. | Gauge\n| microseconds | | Total CPU usage in microseconds per user. | Counter\n| percent | X | CPU usage as a percent of microseconds used per user. | Gauge\n| system_microseconds | | Kernel-space CPU usage in microseconds per user | Counter\n| user_microseconds | | User-space CPU usage in microseconds per user | Counter\n\n#### IO prefix\n\n| Suffix | Calculated | Description | Type |\n| - | - | - | - |\n| op_per_second | X | Read and write operations per second per user | Gauge\n| per_second | X | Read and written bytes per second per user | Gauge\n| read_bytes | | Total bytes read per user | Counter\n| reads_total | | Total number of reads per user | Counter\n| write_bytes | | Total bytes written per user | Counter\n| writes_total | | Total number of writes per user | Counter\n\n#### Memory prefix\n\n| Suffix | Calculated | Description | Type |\n| - | - | - | - |\n| bytes | | Total amount of memory currently being used per user | Gauge\n| percent | X | Memory usage as a percent per user | Gauge\n| swap_bytes | | Amount of swap memory currently being used per user | Gauge\n\n#### Pids prefix\n\n| Suffix | Calculated | Description | Type |\n| - | - | - | - |\n| percent | X | Number of tasks active as a percent per user | Gauge\n| total | | Total number of tasks active per user | Gauge\n\n## Configuring the Prometheus Exporter\n\nThe `lsws-prometheus-exporter` program is started as a service and it can be modified by updating the configuration in the service definition.  In a SystemD system (most systems), this will be a file in the `/etc/systemd/system` folder with the name `lsws-prometheus-exporter.service`.  To add a command line parameter, add it to the `ExecStart` definition after the program starts.  For example, if you installed the exporter with a certificate and key file pointing to the default LiteSpeed admin files you'd see:\n\n```\nExecStart=/usr/local/lsws-prometheus-exporter/lsws-prometheus-exporter --tls-cert-file=/usr/local/lsws/admin/conf/webadmin.crt --tls-key-file=/usr/local/lsws/admin/conf/webadmin.key\n```\n\n### Command line parameters\n\n| Name | Description | Default |\n| - | - | - |\n| `--cgroups` | Whether cgroups v2 user information will be collected.  0 requests disabling, 1 requests enabling if cgroups v2 and LiteSpeed Containers are enabled. | 1 |\n| `--litespeed-home` | Home directory for LiteSpeed, if cgroups are enabled. | /usr/local/lsws |\n| `--metrics-excluded-list` | A comma separated list of metrics to exclude, using the Prometheus name without the prefix `litespeed_`. | None |\n| `--metrics-service-addr` | The address and port to use to listen for prometheus collection requests within the pod.  Form: addr:port; a blank addr listens on all addresses. | `:9936` |\n| `--metrics-service-path` | The HTTP path to service requests on. | `/metrics` |\n| `--tls-cert-file` | If you want to require https to access metrics you must specify a `tls-cert-file` and a `tls-key-file` which are PEM encoded files | None |\n| `--tls-key-file` | If you want to require https to access metrics you must specify a `tls-cert-file` and a `tls-key-file` which are PEM encoded files | None |\n| `--v` | Sets info loggings.  `--v=4` is the most verbose. | `2` |\n\n## Troubleshooting\n\nThe exporter writes its errors and important messages to standard output.  If you use the install script, this will have any messages written to the system log.  On SystemD systems, these are read using `journalctl`.\n\n## Building the Exporter\n\nThe exporter is built using the included Makefile.  If there's a change, update the script with the new version number.  If you wish to build the full package, make sure that `STAGING` is set to `0`; with staging set to `1` only the binary will be built.\n\n## Notable changes\n\n### 0.1.2\n- [Bug Fix] Include missing scraped fields from the CMAXCONN line.\n- The litespeed-containers branch was merged to master.\n\n### 0.1.1\n- [Bug Fix] Tolerate missing cgroups io.stat file.\n- [Bug Fix] Work correctly if .tz file is exploded in place from clone.\n\n### 0.1.0\n- [Feature] Add cgroups support for LiteSpeed Containers.\n\n### 0.0.2 \n- [Feature] The install.sh script supports a \"-n\" flag to disable SSL file prompts.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flitespeedtech%2Flitespeed-prometheus-exporter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flitespeedtech%2Flitespeed-prometheus-exporter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flitespeedtech%2Flitespeed-prometheus-exporter/lists"}