Merge pull request #33 from awaragi/version-1.0

Updated documentation including how to test and develop locally
Updated version of package to 1.0.0
Added docker run script to build and launch server in container
updated to latest LTS nodejs base image
Renamed up metric to mssql_up based on Consider renaming theup metric #27
Fixed issue The mssql_database_filesize metrics fails on big databases #25
Ran prettier (finally)
Added github workflow (on release publish -> push to dockerhub)

.github/workflows/publish.yml

@@ -0,0 +1,36 @@
+name: Build and Publish
+on:
+ release:
+ types: [published]
+jobs:
+ docker:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v2
+ - name: Print tag number
+ run: echo Publishing to tag ${{ github.event.release.tag_name }}
+ - name: Set up QEMU
+ uses: docker/setup-qemu-action@v1
+ - name: Set up Docker Buildx
+ uses: docker/setup-buildx-action@v1
+ - name: Login to DockerHub
+ uses: docker/login-action@v1
+ with:
+ username: ${{ secrets.DOCKERHUB_USERNAME }}
+ password: ${{ secrets.DOCKERHUB_TOKEN }}
+ - name: Build and push (release tag)
+ uses: docker/build-push-action@v2
+ with:
+ push: true
+ tags: awaragi/prometheus-mssql-exporter:${{ github.event.release.tag_name }}
+ - name: Build and push (latest)
+ uses: docker/build-push-action@v2
+ with:
+ push: true
+ tags: awaragi/poc-hub-docker:latest
+ - name: Update repo description
+ uses: peter-evans/dockerhub-description@v2
+ with:
+ username: ${{ secrets.DOCKERHUB_USERNAME }}
+ password: ${{ secrets.DOCKERHUB_PASSWORD }}
+ repository: awaragi/prometheus-mssql-exporter

.gitignore

@@ -1,3 +1,8 @@
+node_modules
 *.iml
-/node_modules/
-/.idea/
+.idea
+.vscode
+.env
+package-lock.json
+yarn.lock
+yarn-error.log

.prettierignore

@@ -0,0 +1,4 @@
+node_modules/*
+package-lock.json
+yarn.lock
+

.prettierrc

@@ -0,0 +1,3 @@
+{
+ "printWidth": 160
+}

Dockerfile

@@ -1,5 +1,6 @@
-FROM node:8.4.0-alpine
-MAINTAINER Pierre Awaragi ([email protected])
+FROM node:16.14.2-alpine
+LABEL MAINTAINER="Pierre Awaragi ([email protected]), cobolbaby"
+LABEL org.opencontainers.image.authors="Pierre Awaragi ([email protected]), cobolbaby"
 
 # Create a directory where our app will be placed
 RUN mkdir -p /usr/src/app
@@ -8,7 +9,7 @@ RUN mkdir -p /usr/src/app
 WORKDIR /usr/src/app
 
 # Copy dependency definitions
-COPY package.json *.js /usr/src/app/
+COPY package.json *.js ./
 
 # Install dependecies
 RUN npm install --production

README.md

@@ -1,72 +1,124 @@
-Prometheus MSSQL Exporter Docker Container
-=============
+# Prometheus MSSQL Exporter Docker Container
 
 Prometheus exporter for Microsoft SQL Server (MSSQL). Exposes the following metrics
 
-*  mssql_instance_local_time Number of seconds since epoch on local instance
-*  mssql_connections{database,state} Number of active 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_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_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_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_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
-*  mssql_available_physical_memory_kb Available physical memory in KB
-*  mssql_total_page_file_kb Total page file in KB
-*  mssql_available_page_file_kb Available page file in KB
+- mssql_instance_local_time Number of seconds since epoch on local instance
+- mssql_connections{database,state} Number of active 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_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_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_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_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
+- mssql_available_physical_memory_kb Available physical memory in KB
+- mssql_total_page_file_kb Total page file in KB
+- mssql_available_page_file_kb Available page file in KB
 
 Please feel free to submit other interesting metrics to include.
 
-Usage
------
+> This exporter has been tested against MSSQL 2017 and 2019 docker images (only ones offered by Microsoft). Other versions might be work but have not been tested.
+
+## Usage
 
 `docker run -e SERVER=192.168.56.101 -e USERNAME=SA -e PASSWORD=qkD4x3yy -e DEBUG=app -p 4000:4000 --name prometheus-mssql-exporter awaragi/prometheus-mssql-exporter`
 
 The image supports the following environments and exposes port 4000
 
-* **SERVER** server ip or dns name (required)
-* **PORT** server port (optional defaults to 1433)
-* **USERNAME** access user (required)
-* **PASSWORD** access password (required)
-* **DEBUG** comma delimited list of enabled logs (optional currently supports app and metrics)
+- **SERVER** server ip or dns name (required)
+- **PORT** server port (optional defaults to 1433)
+- **USERNAME** access user (required)
+- **PASSWORD** access password (required)
+- **DEBUG** comma delimited list of enabled logs (optional currently supports app and metrics)
 
 It is **_required_** that the specified user has the following permissions
 
-* GRANT VIEW ANY DEFINITION TO <user>
-* GRANT VIEW SERVER STATE TO <user>
+- GRANT VIEW ANY DEFINITION TO <user>
+- GRANT VIEW SERVER STATE TO <user>
+
+## Development
+
+## Launch a test mssql server
+
+To launch a local mssql instance to test against
+
+```shell
+npm run test:mssql:2019
+# or
+npm run test:mssql:2017
+```
+
+To use a persistent storage add `-v /mypath:/var/opt/mssql/data` to your version of package.json
+
+## List all available metrics
+
+```shell
+node metrics.js
+```
+
+## Environment variables
+
+- SERVER: sqlserver
+- PORT: sql server port (defaults to 1433)
+- USERNAME: sql server user (should have admin or user with required permissions)
+- PASSWORD: sql user password
+- EXPOSE: webserver port (defaults to 4000)
+- DEBUG: verbose logging
+ - app for application logging
+ - metrics for metrics executions logging
+ - db for database connection logging
+ - queries for database queries and results logging
+
+## Launch via command line
+
+### Using NodeJS
+
+To execute and the application using locally running mssql (see above for how to launch a docker instance of mssql),
+use the following command which will generate all a detailed logs
+
+```shell
+npm start
+```
+
+A more verbose execution with all queries and their results printed out
+
+```shell
+npm run start:verbose
+```
+
+### Using Docker
+
+To build and launch your docker image use the following command
 
-Development
------------
+```shell
+npm run docker:run
+```
 
-### Launch via command line
+## Testing
 
-`
-SERVER=sqlserver
-PORT=sqlport<1433>
-USERNAME=sqluser
-PASSWORD=sqluserpassword
-EXPOSE=webport<4000>
-node ./index.js
-`
+Use curl or wget to fetch the metrics from launched web application.
 
-To enable debugging set the environment variable DEBUG to app and/or metrics (DEBUG=app) 
+```shell
+curl http://localhost:4000/metrics
+```
 
-for example:
-`DEBUG=app,metrics SERVER=192.168.56.101 USERNAME=SA PASSWORD=qkD4x3yy node ./index.js`
+E2E test is available to execute against MSSQL 2017 or 2019 docker instances.
+Any added metrics must get added to the e2e tests.
 
-### building and pushing image to dockerhub
+## Metric listing
 
-`npm run push`
+Call metrics.js file directly to generate documentation of available metrics and to update this README file.
 
-### Launch a mock mssql server
+```shell
+node metrics.js
+```
 
-`docker run -e ACCEPT_EULA=Y -e SA_PASSWORD=qkD4x3yy -p 1433:1433 --name mssql -d microsoft/mssql-server-linux`
+## building and pushing image to dockerhub
 
-To use a persistent storage include `-v /mypath:/var/opt/mssql/data`
+Use docker push or the bundled Github Workflows/Actions (see .github/workflows)

TODO.md

@@ -0,0 +1,5 @@
+# TODO metrics
+
+- sql version (see https://www.mssqltips.com/sqlservertip/1140/how-to-tell-what-sql-server-version-you-are-running/ and summary metric)
+- https://github.com/rongfengliang/prometheus-mssql-exporter/commit/0fc70b747cf2bd8f2e96c58a2cb6f1fc4aae39dd
+- custom metrics? https://github.com/awaragi/prometheus-mssql-exporter/pull/17