Basic Terminology

Ready to get more insight into your applications? Here is a quick start guide to using Harbor to provide you the insight to make sure your applications are safe.

User

Its starts with you. You can use your Google ID, GitHub ID, or you e-mail to identify you as a user.

Organization

All Users must be part of an organization. That way multiple members can create inputs, get insight or take action on that shared data.

Application

Since Harbor is designed with the developer in mind, all of the functions are grouped by application. That way you can see information pertinent to an application regardless of how many systems its running on or our many other applications are running on that system.

Beacon

A beacon is anything that collects information from an application. Generally beacons can be implemented in one of three things.

  1. Code directly integrated in an application. You can write calls to harbor directly into your app to start tracking whats going on inside of your application.
  2. Install a pre-written beacon as a package in your app. Find a beacon in the catalog that servers your purpose and follow the instructions to install it as a package/library into your existing application.
    • Often these pre-written packages will allow you to more simply write calls to Harbor into your existing application.
  3. Stand-alone beacons. These beacons will sit outside your application and can be useful for gathering system information or on third party apps such as databases. A number fo these stand-alone beacons are also available in the Catalog.

Foghorn

Foghorns listen to streams of data from Harbor Services in order to send an alert to humans are systems. There are two basic implementations for a Foghorn.

  1. Inerternal foghorns. Use the Harbor UI to create a simple foghorn to start immediately being notified of changes in your applications performance.
  2. External foghorns. Harbor allows you to directly subscribe to streams of data from Harbor to use in any system set alerts or actions.

View

Charts and graphs to quickly visualize whats going on with the your data. Grouped by application a View is a collection of any number of different types of charts.

Tug

Similar to foghorns, tugs grab streams of data and perform actions against that data as opposed to simply alertiing on the data. Tugs are not implemented in the Alpha Version of Harbor.


Step-by-step guide

Sign Up

You can use your Google Account ID, Github Login or just use your e-mail

Create an Organization

If you arent already in an organization, you will need to create an organization. All applications have to belong to an organization.

Add an Application into your Organization


Select the add application button. Add an application I.D.
NOTE: We recommend using the same reverse dns notation that you use for your apps in general.

Create your first Beacon

Once youve added your application the first thing you have to do is add a beacon in for that application.

  • A beacon collects data relevant to your application and sends that data to harbor.

Pre-written beacon templates can be found in the Harbor Catalog. For this guide we will use a pre-written beacon to check the system stats of one of our database servers. You can directly go to this beacon at https://github.com/HrbrIO/LinuxSysInfoBeacon

Follow the Read Me instructions on installing the Harbor System Information Beacon For Linux.

Register that Beacon into your Application

You must register a beacon before Harbor will accept messages from it.

First of all I see the beaconVersionId is harbor-linux-sysinfo-beacon:0.1.1

Go to the application and select our application tv.ourglass.cloud:1.0.0

Click on the beacons section below the app.

Give the Beacon Version ID harbor-linux-sysinfo-beacon:0.1.0.

You must make sure the Beacon Version ID matches the beaconVersionID in your beacon. Otherwise Harbor will not accept the Beacon!

Finally we need to configure our beacon to send messages to to our API Key and to our Application tv.ourglass.cloud:1.0.0

To find your API Key click on your user avatar in the upper right hand corner and select API Keys.

For this beacon there is a options.json file we edit with our information. Edit with your favorite text editor to put in your API key and the tv.ourglass.cloud:1.0.0

  {
    "apikey": "YourAPIKey",
    "beaconInstanceId": "auto:mac:en0",
    "appVersionId": "tv.ourglass.cloud:1.0.0",
    "functions": []
  }

The Linux System Information Beacon runs a standalone app so we'll need to start it to collect information. Go ahead and run node src/index.js in the base directory for the beacon.

And now you are are sending your first messages to Harbor. You can double check what's coming into harbor by selecting your app.

The you can select go to developor options. After waiting a few seconds you can see the beacon messages.

Add a View

Before we can add a view or foghorn we need understand what your beacon is collecting and sending through Beacon messages should be sent in standard JSON format. By clicking on one of our beacons messages we can see what our SYSINFO Beacon is sending through. Here is soje sample message from our Linux System Information Beacon. As you can see there are quite a few fields to choose from. We are going to want to know CPU utilization so we will look at currentLoad and pick the field avgload.

  "currentLoad": {
    "avgload": 0.39,
    "currentload": 9.579341940857976,
    "currentload_user": 5.893377759266972,
    "currentload_system": 3.685964181591004,
    "currentload_nice": 0,
    "currentload_idle": 90.42065805914203,
    "currentload_irq": 0,
    "raw_currentload": 4600,
    "raw_currentload_user": 2830,
    "raw_currentload_system": 1770,
    "raw_currentload_nice": 0,
    "raw_currentload_idle": 43420,
    "raw_currentload_irq": 0,
}

To add a view we need to return to our application screen.

Click to add a new view. We'll name our Linux System Info View.

After selecting the check mark we can choose the add chart button. We are going to add a simple line chart.

Name the chart as you see fit. Then add SYSINFO into the Beacon Message Type. By having a Beacon Message Type that allows you to look at data from many different beacons. We know SYSINFO is the Beacon Message Type fort this beacon from the Read Me.

Select Check to save your chart and you should be good to go.

To View the chart select Views from the main menu and choose Display from the Linux System Info View.

Create a Foghorn

Now let's create a foghorn to alert us if there is an issue. Setting up a foghorn is very similar to setting up a view so let's set one up using the same currentLoad.avgload data we did for the view.

Return to the application management screen by clicking on our tv.ourglass.cloud:1.0.0 app.

Select to add a new foghorn.

There a number of fields to fill out here so let's break them down quickly.

Foghorn Name
Whatever you want it to be. Might as well make it pretty descriptive.
Foghorn Description
In case your name wasn't descriptive enough.
Beacon Message Type
For our Linux System Information Beacon it's SYSINFO
Trigger Field
Again the Dot Notation that allows the foghorn to read down your JSON. Here again it's currentLoad.avgload
Trigger Type
Plenty of pre-built triggers. We are going with the simple Instantaneous Reading Above so we can check this immediately.
Value
The value you are measure agains. We want to see if the CPU goes over 50%.
ADD RESPONSE+
You can choose between slack, sms and email. Since I don't have my slack API key handy, I'm going with e-mail.
Email Response
The email you want notified. You can also make changes to the default notification.

Once you have filled out the information and submit the form you will need to take one more step of actually starting your foghorn. By default a foghorn's initial state is stopped.

And if all is well you should start receiving e-mails every time your system goes over 50% CPU Utilization.

Conclusion

Now you should be familiar enough to start using pre-built beacons to start getting insight on standard system issues. Stay tuned for more in depth guides on creating your own beacons from scratch and subscribing to Harbor streams to get use all the great data for your own customer foghorns and tugs.