github
/
statping
mirror of https://github.com/statping/statping
1
0
Fork 0
Code Issues Releases Wiki Activity
statping/source/tmpl/help.md

14 KiB
Raw Blame History

Statup Help

Statup is an easy to use Status Page monitor for your websites and applications. Statup is developed in Go Language and you are able to create custom plugins with it!

Services

For each website and application you want to add a new Service. Each Service will require a URL endpoint to test your applications status. You can also add expected HTTP responses (regex allow), expected HTTP response codes, and other fields to make sure your service is online or offline.

Statup Settings

You can change multiple settings in your Statup instance.

Users

Users can access the Statup Dashboard to add, remove, and view services.

Notifications

Plugins

Creating a plugin for Statup is not that difficult, if you know a little bit of Go Language you can create any type of application to be embedded into the Status framework. Checkout the example plugin that includes all the interfaces, information, and custom HTTP routing at https://github.com/hunterlong/statup_plugin. Anytime there is an action on your status page, all of your plugins will be notified of the change with the values that were changed or created.

Using the statup/plugin Golang package you can quickly implement the event listeners. Statup uses upper.io/db.v3 for the database connection. You can use the database inside of your plugin to create, update, and destroy tables/data. Please only use respectable plugins!

Custom Stlying

On Statup Status Page server can you create your own custom stylesheet to be rendered on the index view of your status page. Go to Settings and click on Custom Styling.

API Endpoints

Statup includes a RESTFUL API so you can view, update, and edit your services with easy to use routes. You can currently view, update and delete services, view, create, update users, and get detailed information about the Statup instance. To make life easy, try out a Postman or Swagger JSON file and use it on your Statup Server.

Postman JSON Export | Swagger Export

Authentication

Authentication uses the Statup API Secret to accept remote requests. You can find the API Secret in the Settings page of your Statup server. To send requests to your Statup API, include a Authorization Header when you send the request. The API will accept any one of the headers below.

  • HTTP Header: Authorization: API SECRET HERE
  • HTTP Header: Authorization: Bearer API SECRET HERE

Main Route /api

The main API route will show you all services and failures along with them.

Services

The services API endpoint will show you detailed information about services and will allow you to edit/delete services with POST/DELETE http methods.

Viewing All Services

  • Endpoint: /api/services
  • Method: GET
  • Response: Array of Services
  • Response Type: application/json
  • Request Type: application/json

Viewing Service

  • Endpoint: /api/services/{id}
  • Method: GET
  • Response: Service
  • Response Type: application/json
  • Request Type: application/json

Updating Service

  • Endpoint: /api/services/{id}
  • Method: POST
  • Response: Service
  • Response Type: application/json
  • Request Type: application/json

POST Data:

{
    "name": "Updated Service",
    "domain": "https://google.com",
    "expected": "",
    "expected_status": 200,
    "check_interval": 15,
    "type": "http",
    "method": "GET",
    "post_data": "",
    "port": 0,
    "timeout": 10,
    "order_id": 0
}

Deleting Service

  • Endpoint: /api/services/{id}
  • Method: DELETE
  • Response: Object Response
  • Response Type: application/json
  • Request Type: application/json

Response:

{
    "status": "success",
    "id": 4,
    "type": "service",
    "method": "delete"
}

Users

The users API endpoint will show you users that are registered inside your Statup instance.

View All Users

  • Endpoint: /api/users
  • Method: GET
  • Response: Array of Users
  • Response Type: application/json
  • Request Type: application/json

Viewing User

  • Endpoint: /api/users/{id}
  • Method: GET
  • Response: User
  • Response Type: application/json
  • Request Type: application/json

Creating New User

  • Endpoint: /api/users
  • Method: POST
  • Response: User
  • Response Type: application/json
  • Request Type: application/json

POST Data:

{
    "username": "newadmin",
    "email": "info@email.com",
    "password": "password123",
    "admin": true
}

Updating User

  • Endpoint: /api/users/{id}
  • Method: POST
  • Response: User
  • Response Type: application/json
  • Request Type: application/json

POST Data:

{
    "username": "updatedadmin",
    "email": "info@email.com",
    "password": "password123",
    "admin": true
}

Deleting User

  • Endpoint: /api/services/{id}
  • Method: DELETE
  • Response: Object Response
  • Response Type: application/json
  • Request Type: application/json

Response:

{
    "status": "success",
    "id": 3,
    "type": "user",
    "method": "delete"
}

Service Response

{
    "id": 8,
    "name": "Test Service 0",
    "domain": "https://status.coinapp.io",
    "expected": "",
    "expected_status": 200,
    "check_interval": 1,
    "type": "http",
    "method": "GET",
    "post_data": "",
    "port": 0,
    "timeout": 30,
    "order_id": 0,
    "created_at": "2018-09-12T09:07:03.045832088-07:00",
    "updated_at": "2018-09-12T09:07:03.046114305-07:00",
    "online": false,
    "latency": 0.031411064,
    "24_hours_online": 0,
    "avg_response": "",
    "status_code": 502,
    "last_online": "0001-01-01T00:00:00Z",
    "dns_lookup_time": 0.001727175,
    "failures": [
        {
            "id": 5187,
            "issue": "HTTP Status Code 502 did not match 200",
            "created_at": "2018-09-12T10:41:46.292277471-07:00"
        },
        {
            "id": 5188,
            "issue": "HTTP Status Code 502 did not match 200",
            "created_at": "2018-09-12T10:41:47.337659862-07:00"
        }
    ]
}

User Response

{
    "id": 1,
    "username": "admin",
    "api_key": "02f324450a631980121e8fd6ea7dfe4a7c685a2f",
    "admin": true,
    "created_at": "2018-09-12T09:06:53.906398511-07:00",
    "updated_at": "2018-09-12T09:06:54.972440207-07:00"
}

Object Response

{
    "type": "service",
    "id": 19,
    "method": "delete",
    "status": "success"
}

Main API Response

{
    "name": "Awesome Status",
    "description": "An awesome status page by Statup",
    "footer": "This is my custom footer",
    "domain": "https://demo.statup.io",
    "version": "v0.56",
    "migration_id": 1536768413,
    "created_at": "2018-09-12T09:06:53.905374829-07:00",
    "updated_at": "2018-09-12T09:07:01.654201225-07:00",
    "database": "sqlite",
    "started_on": "2018-09-12T10:43:07.760729349-07:00",
    "services": [
        {
            "id": 1,
            "name": "Google",
            "domain": "https://google.com",
            "expected": "",
            "expected_status": 200,
            "check_interval": 10,
            "type": "http",
            "method": "GET",
            "post_data": "",
            "port": 0,
            "timeout": 10,
            "order_id": 0,
            "created_at": "2018-09-12T09:06:54.97549122-07:00",
            "updated_at": "2018-09-12T09:06:54.975624103-07:00",
            "online": true,
            "latency": 0.09080986,
            "24_hours_online": 0,
            "avg_response": "",
            "status_code": 200,
            "last_online": "2018-09-12T10:44:07.931990439-07:00",
            "dns_lookup_time": 0.005543935
        }
    ]
}

Prometheus Exporter

Statup includes a prometheus exporter so you can have even more monitoring power with your services. The prometheus exporter can be seen on /metrics, simply create another exporter in your prometheus config. Use your Statup API Secret for the Authorization Bearer header, the /metrics URL is dedicated for Prometheus and requires the correct API Secret has Authorization header.

Grafana Dashboard

Statup has a Grafana Dashboard that you can quickly implement if you've added your Statup service to Prometheus. Import Dashboard ID: 6950 into your Grafana dashboard and watch the metrics come in!

Basic Prometheus Exporter

If you have Statup and the Prometheus server in the same Docker network, you can use the yaml config below.

scrape_configs:
  - job_name: 'statup'
    scrape_interval: 30s
    bearer_token: 'SECRET API KEY HERE'
    static_configs:
      - targets: ['statup:8080']

Remote URL Prometheus Exporter

This exporter yaml below has scheme: https, which you can remove if you arn't using HTTPS.

scrape_configs:
  - job_name: 'statup'
    scheme: https
    scrape_interval: 30s
    bearer_token: 'SECRET API KEY HERE'
    static_configs:
      - targets: ['status.mydomain.com']

/metrics Output

statup_total_failures 206
statup_total_services 4
statup_service_failures{id="1" name="Google"} 0
statup_service_latency{id="1" name="Google"} 12
statup_service_online{id="1" name="Google"} 1
statup_service_status_code{id="1" name="Google"} 200
statup_service_response_length{id="1" name="Google"} 10777
statup_service_failures{id="2" name="Statup.io"} 0
statup_service_latency{id="2" name="Statup.io"} 3
statup_service_online{id="2" name="Statup.io"} 1
statup_service_status_code{id="2" name="Statup.io"} 200
statup_service_response_length{id="2" name="Statup.io"} 2

Static HTML Exporter

You might have a server that won't allow you to run command that run longer for 60 seconds, or maybe you just want to export your status page to a static HTML file. Using the Statup exporter you can easily do this with 1 command.

statup export
'index.html' is created in current directory with static CDN url's.

Push to Github

Once you have the index.html file, you could technically send it to an FTP server, Email it, Pastebin it, or even push to your Github repo for Status updates directly from repo.

git add index.html
git commit -m "Updated Status Page"
git push -u origin/master

Config with .env File

It may be useful to load your environment using a .env file in the root directory of your Statup server. The .env file will be automatically loaded on startup and will overwrite all values you have in config.yml.

If you have the DB_CONN environment variable set Statup will bypass all values in config.yml and will require you to have the other DB_* variables in place. You can pass in these environment variables without requiring a .env file.

.env File

DB_CONN=postgres
DB_HOST=0.0.0.0
DB_PORT=5432
DB_USER=root
DB_PASS=password123
DB_DATABASE=root

NAME=Demo
DESCRIPTION=This is an awesome page
DOMAIN=https://domain.com
ADMIN_USER=admin
ADMIN_PASS=admin
ADMIN_EMAIL=info@admin.com
USE_CDN=true

IS_DOCKER=false
IS_AWS=false
SASS=/usr/local/bin/sass
CMD_FILE=/bin/bash

This .env file will include additional variables in the future, subscribe to this repo to keep up-to-date with changes and updates.

Makefile

Here's a simple list of Makefile commands you can run using make. The Makefile may change often, so i'll try to keep this Wiki up-to-date.

  • Ubuntu apt-get install build-essential
  • MacOSX sudo xcode-select -switch /Applications/Xcode.app/Contents/Developer
  • Windows Install Guide for GNU make utility
  • CentOS/RedHat yum groupinstall "Development Tools"

Commands

make build                         # build the binary
make install
make run
make test
make coverage
make docs
# Building Statup
make build-all
make build-alpine
make docker
make docker-run
make docker-dev
make docker-run-dev
make databases
make dep
make dev-deps
make clean
make compress
make cypress-install
make cypress-test

Testing

  • If you want to test your updates with the current golang testing units, you can follow the guide below to run a full test process. Each test for Statup will run in MySQL, Postgres, and SQlite to make sure all database types work correctly.

Create Docker Databases

The easiest way to run the tests on all 3 databases is by starting temporary databases servers with Docker. Docker is available for Linux, Mac and Windows. You can download/install it by going to the Docker Installation site.

docker run -it -d \
   -p 3306:3306 \
   -env MYSQL_ROOT_PASSWORD=password123 \
   -env MYSQL_DATABASE=root mysql

docker run -it -d \
   -p 5432:5432 \
   -env POSTGRES_PASSWORD=password123 \
   -env POSTGRES_USER=root \
   -env POSTGRES_DB=root postgres

Once you have MySQL and Postgres running, you can begin the testing. SQLite database will automatically create a statup.db file and will delete after testing.

Run Tests

Insert the database environment variables to auto connect the the databases and run the normal test command: go test -v. You'll see a verbose output of each test. If all tests pass, make a push request! 💃

DB_DATABASE=root \
   DB_USER=root \
   DB_PASS=password123 \
   DB_HOST=localhost \
   go test -v