Version 1.1 (#34)

* Updated tedious to latest version
incorporate changes to index.js based on code in #28

* incorporate changes to metrics.js based on code in #28

* added mssql product version

* moved source files to src/

* Moved metric documentation into its own file (updated README)
Updated README with list of metrics

* updated test and removed duplicate code (by mistake)

* update documentation (FAQ)
added package-lock.json for deterministic builds
added .npmrc so that builds work regardless of environment
switch npm install to npm ci (faster and ensures that package-lock.json is present
updated version of express (3 high risks indicated by npm audit)

* Made e2e test less dependent on mssql version

* improved metrics logs

* Removed unecessary file

Co-authored-by: Pierre Awaragi <pierre.awaragi@cgi.com>

.gitignore

@@ -3,6 +3,5 @@ node_modules
 .idea
 .vscode
 .env
-package-lock.json
 yarn.lock
 yarn-error.log

.npmrc

@@ -0,0 +1 @@
+registry=https://registry.npmjs.org

Dockerfile

@@ -9,10 +9,10 @@ RUN mkdir -p /usr/src/app
 WORKDIR /usr/src/app
 
 # Copy application
-COPY package.json *.js ./
+COPY package.json package-lock.json src/*.js ./
 
-# Install dependecies
-RUN npm install --production
+# Install dependencies
+RUN npm ci --production
 
 # Expose the port the app runs in
 EXPOSE 4000

README.md

@@ -2,18 +2,25 @@
 
 Prometheus exporter for Microsoft SQL Server (MSSQL). Exposes the following metrics
 
+- mssql_product_version Instance version (Major.Minor)
 - mssql_instance_local_time Number of seconds since epoch on local instance
 - mssql_connections{database,state} Number of active connections
+- mssql_client_connections{client,database} Number of active client connections
 - mssql_deadlocks Number of lock requests per second that resulted in a deadlock since last restart
 - mssql_user_errors Number of user errors/sec since last restart
 - mssql_kill_connection_errors Number of kill connection errors/sec since last restart
-- mssql_database_state{database} State of each database (0=online 1=restoring 2=recovering 3=recovery pending 4=suspect 5=emergency 6=offline 7=copying 10=offline secondary)
+- mssql_database_state{database} Databases states: 0=ONLINE 1=RESTORING 2=RECOVERING 3=RECOVERY_PENDING 4=SUSPECT 5=EMERGENCY 6=OFFLINE 7=COPYING 10=OFFLINE_SECONDARY
 - mssql_log_growths{database} Total number of times the transaction log for the database has been expanded last restart
-- mssql_database_filesize{database,logicalname,type,filename} Physical sizes of files used by database in KB, their names and types (0=rows, 1=log, 2=filestream,3=n/a 4=fulltext(prior to version 2008 of MS SQL Server))
+- mssql_database_filesize{database,logicalname,type,filename} Physical sizes of files used by database in KB, their names and types (0=rows, 1=log, 2=filestream,3=n/a 4=fulltext(before v2008 of MSSQL))
+- mssql_page_read_total Page reads/sec
+- mssql_page_write_total Page writes/sec
 - mssql_page_life_expectancy Indicates the minimum number of seconds a page will stay in the buffer pool on this node without references. The traditional advice from Microsoft used to be that the PLE should remain above 300 seconds
+- mssql_lazy_write_total Lazy writes/sec
+- mssql_page_checkpoint_total Checkpoint pages/sec
 - mssql_io_stall{database,type} Wait time (ms) of stall since last restart
 - mssql_io_stall_total{database} Wait time (ms) of stall since last restart
 - mssql_batch_requests Number of Transact-SQL command batches received per second. This statistic is affected by all constraints (such as I/O, number of users, cachesize, complexity of requests, and so on). High batch requests mean good throughput
+- mssql_transactions{database} Number of transactions started for the database per second. Transactions/sec does not count XTP-only transactions (transactions started by a natively compiled stored procedure.)
 - mssql_page_fault_count Number of page faults since last restart
 - mssql_memory_utilization_percentage Percentage of memory utilization
 - mssql_total_physical_memory_kb Total physical memory in KB
@@ -42,9 +49,33 @@ It is **_required_** that the specified user has the following permissions
 - GRANT VIEW ANY DEFINITION TO <user>
 - GRANT VIEW SERVER STATE TO <user>
 
+## Frequently Asked Questions (FAQ)
+
+### Unable to connect to database
+
+Raised in [issue #19](https://github.com/awaragi/prometheus-mssql-exporter/issues/19)
+
+Probably your SQL Server is working as named instance. For named instances the TCP port is dynamically configured by default, so you may need do explicitly specify port in MSSQL settings as described [here](https://docs.microsoft.com/en-US/sql/database-engine/configure-windows/configure-a-server-to-listen-on-a-specific-tcp-port?view=sql-server-ver15).
+
+### Running multiple instances of exporter
+
+Raised in [issue #20](https://github.com/awaragi/prometheus-mssql-exporter/issues/20)
+
+Each container should use its own docker port forward (e.g. -p 4001:4000 and -p 4002:4000)
+
+### What Grafana dashboard can I use
+
+Here are some suggestions on available Grafana dashboards. If you are an author or such dashboard and want to have it referenced here, simply create a Pull Request.
+
+- https://grafana.com/grafana/dashboards/13919
+
+### Running in the background
+
+Use `docker run -d ...` to run the container in background
+
 ## Development
 
-## Launch a test mssql server
+## Launching a test mssql server
 
 To launch a local mssql instance to test against
 
@@ -54,12 +85,14 @@ npm run test:mssql:2019
 npm run test:mssql:2017
 ```
 
-To use a persistent storage add `-v /mypath:/var/opt/mssql/data` to your version of package.json
+To use a persistent storage add `-v /<mypath>:/var/opt/mssql/data` to the command line.
 
 ## List all available metrics
 
+To list all available metrics and the used queries to generate these metrics - say for for DBA validation, use the following command
+
 ```shell
-node metrics.js
+npm run metrics
 ```
 
 ## Environment variables
@@ -102,23 +135,26 @@ npm run docker:run
 
 ## Testing
 
+### Curl or Browser
+
 Use curl or wget to fetch the metrics from launched web application.
 
 ```shell
 curl http://localhost:4000/metrics
 ```
 
+### E2E Test with Expectations
+
 E2E test is available to execute against MSSQL 2017 or 2019 docker instances.
-Any added metrics must get added to the e2e tests.
 
-## Metric listing
+The test does not care about the values of the metrics but checks the presence of all expected keys.
 
-Call metrics.js file directly to generate documentation of available metrics and to update this README file.
+To add new metrics, the E2E must get updated with their keys to pass.
 
 ```shell
-node metrics.js
+npm test
 ```
 
 ## building and pushing image to dockerhub
 
-Use docker push or the bundled Github Workflows/Actions (see .github/workflows)
+Use `docker build` and `docker push` or the bundled Github Workflows/Actions (see .github/workflows)