Documentation

The Monitaur provides easy logging and health monitoring services for any server-side application. The Monitaur supports logging Alerts through WebAPI, Tcp, and WebSocket connections and provides support for any secured application including perennial, distributed, NTier layered applications. It is easy to begin implementing The Monitaur in your own .NET applications using the provided .NET nuget packages, and it is nearly as easy to write your own logic for interacting with the WebAPI, Tcp, and WebSocket servers for your server-side applications. The Monitaur's Tcp, and WebSocket servers can support non-SSL or SSL connections, and acquiring your authorization / authentication `token` is as simple as registering a Client Application on The Monitaur's Web Application, copying the provided token, and attaching it to your payload. All The Monitaur packages referenced in this documentation are available on the NuGet package manager in 1 aggregate package - The Monitaur.

Getting Started

To get started, first register for a free account at The Monitaur.com. You can login using an existing account provided by: Google, Facebook, Twitch, Twitter, or Microsoft.

After your initial log in, you will be greeted with a banner guiding you through creating your first Project and Client Application. Input a name for your new Project.

Image welcome banner new Project

Next, input a name for your Client Application and choose an Alert Type of either: Card or Table.

Image welcome banner new Client Application

The next screen shows your new Client Application's token and offers you a chance to copy it to your clipboard. This token is private and should not be publically exposed. When you click close on the final screen, The Monitaur's dashboard will load and show your new Project and Client Application.

image dashboard

Table of Contents


Components

There are 3 types of objects that are used within The Monitaur:


Projects

A Project represents the top-most object you can create on The Monitaur. A Project represents a collection of Client Applications that will be sending Alerts to The Monitaur's servers. A newly created account allows for 3 Projects total, but additional projects can be purchased from the Purchasable Items screen.


Client Applications

A Client Application represents the entity that will be submitting Alerts to The Monitaur's servers. Each Client Application will receive its own token which will be used for logging Alerts.

This token should not be publically exposed.

The Client Application object is as follows:

        interface IClientApplication
        {
            "clientName": string,             // The Client Application Name
            "clientDescription": string       // The Client Application Description
        }

In order to submit Alerts on behalf of a Client Application, the Client Application's token must be submit on or following connection to The Monitaur's servers.

Client Authorization Token

To retrieve your Client Application's token, log into The Monitaur and click on the Projects button the top navbar.

Image Projects menu item

Click on your parent Project, and then click on your desired Client Application.

Image Client Applications registered to a project

A password field is on the page that contains your token, and you can reveal or copy it to clipboard for use when submitting Alerts.

Image token for Client Application

This Client Application token is private and should not be publically available. This token is used to submit data to The Monitaur's servers, and if exposed, may result in unauthorized access and revocation of account services.

A newly created account allows for 3 Client Applications per Project, but additional Client Applications per Project can be purchasaed from the Purchasable Items screen.


Alerts

An Alert is an object sent by your registered Client Application(s) and logged at The Monitaur. Alerts can contain template information and are useful when evaluating and monitoring perennial distributed production applications. For example, an Alert could be issued on a polling interval that discloses the current health of the application, or an Alert could be sent to a WebAPI endpoint to ensure it remains online. Alerts can also contain custom messages that can contain any data you like, and this could include custom status objects deserialized into a string and sent along with the Alert.

The Alert object is as follows:

    interface IAlert
    {
        "id": number,                     // The Alert Id
        "statusType": number,             // The Status Type of the Alert
        "statusTypeValue": string,        // The Status Type of the Alert as a value
        "alertType": number,              // The Alert Type of the Alert
        "alertTypeValue": string,         // The Alert Type of the Alert as a value,
        "message": string,                // Custom string data you can include with the alert
        "timestamp": datetime             // The timestamp of the Alert adjusted to local time
    }

AlertType

Alert Type is an enum and has numeric values representing multiple states. You can use these values to represent any state, but it is recommended to think of Alert Type as a traditional Log Level.

    enum AlertType {
        Debug,      // value: 0
        Info,       // value: 1
        Warning,    // value: 2
        Alert,      // value: 3
        Error       // value: 4
    }

Status Type

Status Type is an enum and has numeric values representing either Online or Offline.

    enum StatusType {
        Online,     // value: 0
        Offline     // value: 1
    }

Active and Dismissed

Alerts have 2 states: Active and Dismissed. An Active Alert has not yet been viewed and will be shown on The Monitaur's Web Application by default. After reviewing the Alert(s), they can be Dismissed and archived. In this state, Alerts are assumed to have been reviewed and are no longer displayed on the Web Application. They can still retrieved using The Monitaur's WebAPI and performing an Alerts Get, and specifying IncludeDismissedAlerts=true in the query parameters.


Protocols

The Monitaur currently supports 3 types of connections for logging Alerts:

WebAPI

You can connect to The Monitaur's WebAPI either manually or you can use the provided WebAPI Nuget Packages.

The Monitaur includes a Swagger documented WebAPI detailing the available WebAPI endpoints, requests, responses, and the capability to use test the WebAPI from the browser. Click on the Authorize in the upper-right hand corner of the Swagger documentation and paste in the token you previously retrieved for your Client Application.


Manual Connections

Authorization

In order to use the WebAPI, you must include an authorization header to your request with the value as 'Bearer {token}', where {token} is the token generated for the desired Client Application. Please see above if you need help locating your token.

Endpoints

6 secured WebAPI endpoints are included with The Monitaur:

Get Client Application
curl -H "Authorization: bearer 3284283479255623" https://api.themonitaur.com/clientApplication
Get Alerts
curl -H "Authorization: bearer 3284283479255623" https://api.themonitaur.com/alerts?maxRecordsToRetrieve=30000&alertTypes=0&alertTypes=1&alertTypes=2&statusTypes=0&startDate=2020-04-15T07:00:00.000Z&endDate=2020-05-15T07:00:00.000Z&includeActiveAlerts=true&includeDismissedAlerts=false
Get Alert
curl -H "Authorization: bearer 3284283479255623" https://api.themonitaur.com/alert/5347
Create Alert
curl -X POST "https://api.themonitaur.com/Alerts" -H "Content-Type: application/json" -d "{\"statusType\":1,\"alertType\":4,\"message\":\"Hello world\"}" -H "Authorization: bearer 3284283479255623"
Dismiss Alerts
curl -X POST "https://api.themonitaur.com/Alerts/Dismiss" -H "Content-Type: application/json" -d "{\"ids\":[15,46,86]}" -H "Authorization: bearer 3284283479255623"
Delete Alert
curl -X DELETE "https://api.themonitaur.com/Alerts/568" -H "Authorization: bearer 3284283479255623"

Nuget Packages

A WebAPI Client module is included and can be used to access The Monitaur's WebAPI. First, install the NuGet package using the NuGet package manager:

install-package TheMonitaur.WebAPI

This will add the most-recent version of the The Monitaur WebAPI Module to your specified Project.

Once installed, we can instantiate an instance of IWebAPIClient with the included implementation WebAPIClient.

Parameters

Methods

The following methods are exposed on IWebAPIClient:

Update Your Token

If you need to update the token that you set in the constructor of WebAPIClient, you can use the included function:


WebSocket

You can connect to The Monitaur's WebSocket servers either manually or you can use the provided WebSocket Nuget Packages.


Manual Connections

Connect to the Server

To connect to The Monitaur's WebSocket servers, you will need a token for a registered Client Application. To retrieve the token, please see Retrieving Your Client Application Token.

Connect your WebSocket Client to the following endpoint and port. There are 2 ports to choose from - one is for an SSL secured WebSocket Server and the other is for an unsecured WebSocket Server. More information on the use of both servers is detailed in SSL or Non-SSL.

For the secured server: Uri: wss://connect.themonitaur.com:6790/{token}

For the non-secured server: Uri: ws://connect.themonitaur.com:6795/{token}

Token

You must send your token for your Client Application as a route parameter on the initial connection Uri in order to be authenticated on The Monitaur's Servers. You do not need to add a prefix. An example of an initial connection Uri for the secured server is as follows:

wss://connect.themonitaur.com:6790/659459068904568908434588847

If you connect successfully, you will receive a raw message back telling you that your connection to The Monitaur was successful.

SSL or Non-SSL

To enable SSL for your connection to The Monitaur WebSocket servers, you need to connect to port 6790. It is recommended to use the SSL server for increased security. You can however use the non-SSL server by connecting to port 6795. Both servers function identically, and because there is no encryption on the non-SSL server, the non-SSL server may have a slightly improved response rate.

Send an Alert

The AlertCreateRequest has the following signature:

    interface AlertCreateRequest {
        "statusType": number,         // The Status Type of the Alert to create
        "alertType": number,          // The Alert Type of the Alert to create
        "message": string             // Custom message or serialized to include with the Alert
    }

To send an Alert to The Monitaur's WebSocket servers, create in JSON a new AlertCreateRequest and serialize it to a string. On your WebSocket Client that is connected to The Monitaur's WebSocket servers, send the serialized data. An example of the serialized payload is below:

socket.Send('{"statusType":0, "alertType": 1, "message": "Hello world"}')

Ping

The Monitaur WebSocket servers will send a raw message containing ping to every client every 120 seconds to verify which connections are still alive. If a client fails to respond with a raw message containing pong, during the the next ping cycle, the connection will be severed and disposed. You should encorporate logic to listen for raw messages containing ping, and if received, immediately respond with a raw message containing the message pong.

Note: Failure to implement this logic will result in a connection being severed in up to approximately 240 seconds.


Nuget Packages

A WebSocket Client module is included which can be used for non-SSL or SSL connections. To get started, first install the NuGet package using the NuGet package manager:

install-package TheMonitaur.WebSocket

This will add the most-recent version of the The Monitaur's WebSocket module to your specified Project.

Once installed, we can instantiate an instance of IMonitaurWebSocket with the included implementation MonitaurWebSocket.

MonitaurWebSocket(string token, string uri = "connect.themonitaur.com", int port = 6790, bool isSSL = true)

An example instantiation is below:

IMonitaurWebSocket client = new MonitaurWebSocket(8943258989435839054532)

Parameters

Methods

1 method is exposed in The Monitaur's WebSocket Module:

The AlertCreateRequest has the following signature:

    interface AlertCreateRequest {
        "statusType": number,         // The Status Type of the Alert to create
        "alertType": number,          // The Alert Type of the Alert to create
        "message": string             // Custom message or serialized to include with the Alert
    }

An example call to send a message to the server could be:

    await client.SendAlertAsync(new AlertCreateRequest
    {
        "StatusType" = 2,
        "AlertType" = 1,
        "Message" = "Hello world"
    })

Ping

If using The Monitaur's WebSocket nuget packages, Ping and Pong messages should be digested and handled automatically.

Dispose

At the end of usage, be sure to call Dispose() on the IMonitaurWebSocket object to free all allocated memory and resources.


Example WebSocket HTML + JS Browser Client

Below is a simple Html Client that you can use to test The Monitaur's WebSocket servers. When implementing this test client, make sure to change `{token}` in the const uri to your desired Client Application token.

DO NOT USE THIS CLIENT IN PRODUCTION OR YOUR TOKEN WILL BE PUBLICALLY EXPOSED.

Send An Alert To The Monitaur From WebSocket!

    Below is the HTML and Javascript Code for the above form (without styling).

    
        <!DOCTYPE html>
    
    
    
    
    
    
    
        <html>
    
        <head>
        <meta charset="utf-8" />
    
    
    
        <title>Send An Alert To The Monitaur From WebSocket!</title>
            </head>
    
        <body>
        <h1>Send An Alert To The Monitaur From WebSocket!</h1>
        <label for="alertType-select">Alert Type</label>
        <select id="alertType-select">
        <option value="0">Debug</option>
        <option value="1">Info</option>
        <option value="2">Warning</option>
        <option value="3">Alert</option>
        <option value="4">Error</option>
                </select>
        <label for="alertType-select">Status Type</label>
        <select id="statusType-select">
        <option value="0">Online</option>
        <option value="1">Offline</option>
                </select>
        <input type=text id="message" placeholder="Message" />
    
    
    
    
    
    
    
        <button id="sendButton">Send</button>
    
        <ul id="messages"></ul>
    
        <script language="javascript" type="text/javascript">
            const uri = "wss://connect.themonitaur.com:6790/{token}";
            function connect() {
                socket = new WebSocket(uri);
                socket.onopen = function (event) {
                    console.log("opened connection to " + uri);
                };
                socket.onclose = function (event) {
                    console.log("closed connection from " + uri);
                };
                socket.onmessage = function (event) {
                    appendItem(list, event.data);
                    console.log(event.data);
    
                    if (event.data === 'Ping') {
                        sendMessage('Pong');
                    }
                };
                socket.onerror = function (event) {
                    console.log("error: " + event.data);
                };
            }
            connect();
            const list = document.getElementById("messages");
            const button = document.getElementById("sendButton");
            button.addEventListener("click", function () {
                const alertTypeSelect = document.getElementById("alertType-select");
                const alertType = alertTypeSelect.options[alertTypeSelect.selectedIndex].value;
    
                const statusTypeSelect = document.getElementById("statusType-select");
                const statusType = statusTypeSelect.options[statusTypeSelect.selectedIndex].value;
    
                const message = document.getElementById("message");
                const payload = { "alertType": alertType, "statusType": statusType, "message": message.value };
                sendMessage(JSON.stringify(payload));
            });
            function sendMessage(message) {
                socket.send(message);
                console.log(message);
            }
            function appendItem(list, message) {
                var item = document.createElement("li");
                item.appendChild(document.createTextNode(message));
                list.appendChild(item);
            }
    </script>
    
            </body>
    
        </html>

    Tcp

    You can connect to The Monitaur's Tcp servers either manually or you can use the provided Tcp Nuget Packages.

    Manual Connections


    Connect to the Server

    To connect to The Monitaur's Tcp servers, you will need a token for a registered Client Application. To retrieve the token, please see Retrieving Your Client Application Token.

    First, connect your Tcp Client to the following endpoint and port. There are 2 ports to choose from - 1 is for an SSL secured Tcp Server, the second is for an unsecured Tcp Server. More information on the use of both servers is detailed in Tcp SSL or Non-SSL.

    Submit your Token

    You must send as the first message to the server a raw message containing your token. You must add oauth: as the prefix for your token. This first message should look similar to the following:

    oauth:yourOAuthTokenGoesHere

    If you connect successfully, you will receive a raw message back telling you that your connection to The Monitaur was successful.

    SSL or Non-SSL

    To enable SSL for your connection to The Monitaur Tcp Servers, you need to connect to port 6780. It is recommended to use the SSL server for increased security. You can however use the non-SSL server by connecting to port 6785. Both servers function identically, and because there is no encryption on the non-SSL server, the non-SSL server may have a slightly improved response rate.

    Send an Alert

    The AlertCreateRequest has the following signature:

        interface AlertCreateRequest {
            "statusType": number,         // The Status Type of the Alert to create
            "alertType": number,          // The Alert Type of the Alert to create
            "message": string             // Custom message or serialized to include with the Alert
        }

    To send an Alert to The Monitaur's Tcp servers, create in JSON a new AlertCreateRequest and serialize it to a string. On your Tcp Client that is connected to The Monitaur's Tcp servers, send a UTF-8 byte array containing the serialized JSON data and the end-of-line-characters, \r\n. An example of the serialized payload is below:

    socket.Send(Encoding.UTF8.GetBytes('{"statusType":0, "alertType": 1, "message": "Hello world"}\r\n'))

    Make sure to send the End-Of-Line characters or your Alert will not be written to the server.

    End-of-Line Characters

    Tcp connections are persistent connections of streamed data. The server is unable to determine where breaks in the data exist without End-Of-Line characters to identify where to split apart the data. For The Monitaur's End-Of-Line characters are defined to be:

    \r\n

    On many devices, this represents a carriage return and new line.

    Ping

    The Monitaur Tcp servers will send a raw message containing 'ping' to every client every 120 seconds to verify which connections are still alive. If a client fails to respond with a raw message containing 'pong', during the the next ping cycle, the connection will be severed and disposed. You will need to encorporate logic to listen for raw messages containing 'ping', and sif received, immediately respond with a raw message containing the message 'pong'.

    Note: Failure to implement this logic will result in a connection being severed in up to approximately 240 seconds.


    Nuget Packages

    A Tcp Client module is included which can be used for non-SSL or SSL connections. To get started, first install the NuGet package using the NuGet package manager.

    install-package TheMonitaur.Tcp

    This will add the most-recent version of the The Monitaur's Tcp Module to your specified Project.

    Once installed, we can instantiate an instance of IMonitaurTcp with the included implementation MonitaurTcp.

    MonitaurTcp(string token, string uri = "connect.themonitaur.com", int port = 6780, bool isSSL = true)

    An example instantiation is below:

    IMonitaurTcp client = new MonitaurTcp(8943258989435839054532)

    Parameters

    Methods

    1 method is exposed in The Monitaur's Tcp module:

    The AlertCreateRequest has the following signature:

        interface AlertCreateRequest {
            "statusType": number,         // The Status Type of the Alert to create
            "alertType": number,          // The Alert Type of the Alert to create
            "message": string             // Custom message or serialized to include with the Alert
        }

    An example call to send a message to the server could be:

        await client.SendAlertAsync(new AlertCreateRequest
        {
            StatusType = 2,
            AlertType = 1,
            Message = "Hello world"
        });

    Ping

    If using The Monitaur's Tcp nuget packages , Ping and Pong messages should be digested and handled automatically.

    Dispose

    At the end of usage, be sure to call Dispose() on the IMonitaurTcp object to free all allocated memory and resources.


    Dashboard

    The Monitaur Web Application's dashboard has been designed to provide tooling to maximize available screen-space for reviewing your Alerts. It features real-time updates, and as your Client Applications post Alerts to either WebAPI, WebSocket, or Tcp, the Web Application will be automatically updated to reflect the new or updated Alerts. Additionally, all filter settings including but not limited to Alert Types, Status Types, Client Applications, and Projects are saved between sessions, so you can quickly log into The Monitaur to review Alert notifications conforming to your set Filters and quickly dismiss your reviewed Alerts.

    The dashboard includes 2 different ways to visualize your Alerts:

    Note: At a later date, The Monitaur will support email notifications for selected Alerts. However, this feature is not yet ready for production.

    Alert Cards

    Cards are designed to be used when reviewing Alerts or are browsing The Monitaur on a mobile device. There are 3 potential locations to interact with cards: on the Alert Cards page, on the Client Application dashboard, or after selecting Alerts and clicking on Review Selected Alerts. Screenshots of these screens are included below.

    Image Review Alerts and Alert Cards screens Image Client Application dashboard with cards

    Alert Tables

    Tables are designed to manage large number of Alerts. Tables can be accessed through the Alerts Table menu or by setting a Client Application to display on the dashboard as tables . Tables allow for a quick overview of undismissed Alerts, a way to aggregately dismiss Alerts, or can be used to select Alerts to further review. When you click on Review Selected Alerts, the next screen will populate with the selected Alerts displayed as Cards, and when you click on a Card, it will be dismissed.

    Image Alert Tables screen Image Client Application dashboard tables

    Dismiss Alerts

    You can dismiss displayed Alerts from the Web Application. If the Alerts are currently displayed as Cards (and is not a queried dataset), you can dismiss any Alert by clicking or tapping on it. If when looking at the Client Application dashboard component, you will see a modal showing you the Alert in more detail with Dismiss Alert as an action. Dismissed Alerts are not visible by default on the Web Application, but can be viewed and / or exported using Queries and Outputting Data.

    Filters

    You can Filter undismissed Alerts dynamically on the Alert Cards / Alert Tables screens or on any Client Application dashboard component. To filter Alerts, first select Set Filters from the filter panel. The screen will refresh with Alert Type and Status Type expandable filter selections, and if in the Alert Cards / Table screen, a Projects filter selection. Set the desired filter criteria including the shown Alert Types, Status Types, and / or Projects / Client Applications, and the Alert Card or Alert Table component will update immediately.

    If the data expected onscreen is not being shown, it more than likely is caused by Filters. Filters retain their state (displayed or not displayed) between your login sessions. You can reset the Filters by selecting Reset Filters on the respective Filter panel.

    Queries

    There are 2 ways to query historic alerts: Alert Cards or Alert Tables screens, and any Client Application dashboard.

    To query historic records, first navigate to either the Alert Card / Alert Table screens or any Client Application dashboard component. Now click on the checkbox that says Query History Alerts.

    Image Customize account Alert notifcation colors for text and background

    The Filters panel will change into a Query panel. From this panel, you can select a desired start and end date, a desired number of records, to include active records, to include dismissed records, select included Alert Types, and select included Status Types. Modify the query parameters to match the desired query, and then click Submit Filter and Query. The Query panel will become locked and the queried results will be displayed. Queried records (if active) cannot be dismissed from when the Query panel is active.

    Outputting Data

    Data that has been Queried can be exported as a Comma Separated Value (CSV) file. To export Queried, when the desired Queried is displayed on screen by querying for Alerts, click on the Export Queried Alerts button.

    Image export queried Alerts

    The maximum number of rows you can query using The Monitaur's Web Application is 50,000 records per request. If you require more than 50,000 records, you can modify the query parameters to return sub-queries and union them on your local machine.

    Customize

    Alerts can have their colors customized by Alert Type and Status Type by clicking on the Accounts menu item.

    Image Customize account Alert notifcation colors for text and background

    To setup customized colors, select the Alert Type you would like to customize, and choose a Text and / or Background Color from the Color Picker. The displayed records in the dashboard will automatically update to reflect the color changes.


    Additional Information

    The Monitaur was created by LiveOrDevTrying and is maintained by Pixel Horror Studios. The Monitaur is currently implemented in (but not limited to) the following projects: Allie.Chat, There Is No Turning Back!, and OpenDJRadio.

    Pixel Horror Studios Logo