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, WebSocket, or Tcp 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.
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.
Next, input a name for your Client Application and choose an Alert Type of either: Card or Table.
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.com's dashboard will load and show your new Project and Client Application.
There are 3 types of objects that are used within The Monitaur:
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.
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.
To retrieve your Client Application's token, log into The Monitaur and click on the Projects button the top navbar.
Click on your parent Project, and then click on your desired Client Application.
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.
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.
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 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 AlertType as a traditional Log Level.
enum AlertType {
Debug, // value: 0
Info, // value: 1
Warning, // value: 2
Alert, // value: 3
Error // value: 4
}
Status is an enum and has numeric values representing either Online or Offline.
enum StatusType {
Online, // value: 0
Offline // value: 1
}
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 be retrieved using The Monitaur's WebAPI and performing an Alerts Get, and specifying IncludeDismissedAlerts=true in the query parameters.
The Monitaur currently supports 3 types of connections for logging Alerts:
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 main page and paste in the token you previously retrieved for your Client Application.
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.
6 secured WebAPI endpoints are included with The Monitaur:
- GET https://api.themonitaur.com/clientApplication
- Retrieve the Client Application registered to the
tokenincluded in the request header. - Returns: IClientApplication
curl -H "Authorization: bearer 3284283479255623" https://api.themonitaur.com/clientApplication
- GET https://api.themonitaur.com/alerts
- Retrieve the undismissed Alerts registered to the Client Application
- Request: Query string parameters
- Max Records to Retrieve - number - optional - The maximum number of Alerts to retrieve. Defaults to 150 and maximum is 50,000
- AlertTypes - array[AlertType] - optional - The AlertType(s) to include with the response
- StatusTypes - array[StatusType] - optional - The StatusType(s) to include with the response
- StartDate - string - optional - The inclusive initial limit for querying Alerts in a date range
- EndDate - string - optional - The exclusive ending limit for querying Alerts in a date range
- IncludeActiveAlerts - boolean - optional - A flag to indiciate a request of Alerts that include those that have not been dismissed
- IncludeDismissedAlerts - boolean - optional - A flag to indiciate a request of Alerts that include those that have been dismissed
- Returns: array[IAlert]
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 https://api.themonitaur.com/alert/{id}
- Retrieve the specified Alert registered to the authorized Client Application
- Request: Route parameter
- Id - number - required - The Id of the Alert to retrieve
- Returns: IAlert
curl -H "Authorization: bearer 3284283479255623" https://api.themonitaur.com/alert/5347
- POST https://api.themonitaur.com/alerts
- Create a new Alert registered to the authenticated Client Application
- Request: Body
-
interface IAlertCreateRequest { "statusType": number, "alertType": number, "message": string } - StatusType - StatusType (number) - required - The StatusType to log with the Alert
- AlertType - AlertType (number) - required - The AlertType to log with the Alert
- Message - string - optional - Any additional information (messages or serialized state data) to include with the Alert
-
- Returns: IAlert
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"
- POST https://api.themonitaur.com/alerts/dismiss
- Dismiss Alert(s) registered to the authenticated Client Application
- Request: Body
-
interface IAlertsDismissRequest { "ids": number[], } - Ids - array[number] - required - The Ids of the Alert(s) requested to dismiss
-
- Returns: Code 204
curl -X POST "https://api.themonitaur.com/Alerts/Dismiss" -H "Content-Type: application/json" -d "{"ids":[15,46,86]}" -H "Authorization: bearer 3284283479255623"
- DELETE https://api.themonitaur.com/alerts/{id}
- Delete an Alert registered to the authenticated Client Application
- Note: This endpoint should be used as infrequently as possible
- Request: Route parameter
- Id - number - required - The Id of the Alert requested to delete
- Returns: Code 204
curl -X DELETE "https://api.themonitaur.com/Alerts/568" -H "Authorization: bearer 3284283479255623"
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.
WebAPIClient(string token, string webAPIBaseUri = "https://api.themonitaur.com")- An example instantiation is below:
IWebAPIClient client = new WebAPIClient(8943258989435839054532);
- Token - string - Required - Parameter containing the
tokenof the registered Client Application retrieved from The Monitaur.com. - WebAPIBaseUri - string - Optional - The endpoint / host / url of The Monitaur's WebAPI server instance to connect (defaults to https://api.themonitaur.com).
The following methods are exposed on IWebAPIClient:
Task<ClientApplicationDTO> GetClientApplicationAsync()- Gets the Client Application that is registered to the
Client Application Token
- Gets the Client Application that is registered to the
Task<AlertDTO[]> GetAlertsAsync();- Get the most recent 150 undismissed Alerts for the Client Application
Task<AlertDTO[]> GetAlertsAsync(AlertsLookupRequest request);- Get Alerts for the Client Application conforming to the criteria in AlertsLookupRequest
-
interface AlertsLookupRequest { "maxRecordsToRetrieve": number, "alertTypes": number[], "statusTypes": number[], "startDate": datetime, "endDate": dateTime, "includeActiveAlerts": boolean, "includeDismissedAlerts": boolean }
Task<AlertDTO> GetAlertAsync(long id);- Get an Alert registered to the Client Application
Task<AlertDTO> CreateAlertAsync(AlertCreateRequest request);- Create a new Alert registered to the Client Application
-
interface AlertCreateRequest { "statusType": number, "alertType": number, "message": string }
Task<bool> DismissAlertsAsync(long[] ids);- Dismiss the Alerts registered to the Client Application with Ids contained in the ids input parameter
Task<bool> DeleteAlertAsync(long id);- Delete the specified Alert registered to the Client Application
- This endpoint should be used as infrequently as possible.
If you need to update the token that you set in the constructor of WebAPIClient, you can use the included function:
void SetToken(string token)
You can connect to The Monitaur's WebSocket servers either manually or you can use the provided WebSocket Nuget Packages.
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 - 1 is for an SSL secured WebSocket Server, the second 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}
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.
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.
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"}')
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.
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);
- Token - string - Required - Parameter containing the
tokenof the registered Client Application retrieved from The Monitaur.com. - Uri - string - Optional - The endpoint / host / url of The Monitaur's server instance to connect (defaults to connect.themonitaur.com.
- Port - int - Optional - The port of The Monitaur's server instance to connect (e.g. 6790, 6795).
- IsSSL - bool - Optional - Flag specifying if the connection should be made using SSL encryption for the connection to the server.
1 method is exposed in The Monitaur's WebSocket Module:
Task SendAlertAsync(AlertCreateRequest request);- Async method to send a new Alert to The Monitaur's servers.
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"
});
If using The Monitaur's WebSocket nuget packages, Ping and Pong messages should be digested and handled automatically.
At the end of usage, be sure to call Dispose() on the IMonitaurWebSocket object to free all allocated memory and resources.
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.
<!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>
<input type=number id="alertType" placeholder="Alert Type"/>
<input type=number id="statusType" placeholder="Status Type"/>
<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 alertType = document.getElementById("alertType");
const statusType = document.getElementById("statusType");
const message = document.getElementById("message");
sendMessage({ "alertType": alertType.value, "statusType": statusType.value, "message": message.value});
alertType.value = "";
statusType.value = "";
message.value = "";
});
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>
You can connect to The Monitaur's Tcp servers either manually or you can use the provided Tcp Nuget Packages.
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.
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.
Uri: connect.themonitaur.com
SSL Port: 6780
Non-SSL Port: 6785
End-of-Line Characters: \r\n
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.
To enable SSL for your connection to The Monitaur Tcp Server, 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.
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.
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.
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 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.
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);
- Token - string - Required - Parameter containing the
tokenof the registered Client Application retrieved from The Monitaur.com. - Uri - string - Optional - The endpoint / host / url of The Monitaur's Tcp Servers(defaults to connect.themonitaur.com).
- Port - number - Optional - The port of The Monitaur's server instance to connect (e.g. 6780, 6785).
- IsSSL - boolean - Optional - Flag specifying if the connection should be made using SSL encryption for the connection to the server.
1 method is exposed in The Monitaur's Tcp Module:
Task SendAlertAsync(AlertCreateRequest request);- Async method to send a new Alert to The Monitaur's Tcp Server.
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"
});
If using The Monitaur's Tcp nuget packages, Ping and Pong messages should be digested and handled automatically.
At the end of usage, be sure to call Dispose() on the IMonitaurTcp object to free all allocated memory and resources.
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.
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.
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.
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 the 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.
You can Filter undismissed Alerts dynamically on the Alerts Cards / 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 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.
There are 2 ways to query historic alerts: Alert Cards or Alert Table screens, and any Client Application dashboard.
To query historic records, first navigate to either the Alerts Cards / Table screens or any Client Application dashboard component. Now click on the checkbox that says Query History Alerts.
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.
Data that has been Queried can be exported as a Comma Separated Value (CSV) file. To export Queried data, when the desired Queried data is displayed on screen by querying for Alerts, click on the Export Queried Alerts button.
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.
Alerts can have their colors customized by Alert Type and Status Type by clicking on the Accounts menu item.
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.
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.
