minor edits to docs

Author: massimocandela

README.md

@@ -80,11 +80,10 @@ Read the documentation below for more options.
 - [Update to latest version](docs/update.md)
 - [More information for developers](docs/develop.md)
     - [All npm commands](docs/develop.md#all-npm-commands)
-    - [Git flow](docs/release-process.md#git-flow)
-    - [Report context](docs/context.md)
-    - [Release process](docs/release-process.md)
+    - [Reports/alerts templates](docs/context.md)
+    - [Release process and Git flow](docs/release-process.md)
 - [BGPalerter for researchers](docs/research.md)
-- [Release process and Git flow](docs/release-process.md)
+
 
 
 If you are using BGPalerter, feel free to sign here: [Who is using BGPalerter](docs/friends.md)

docs/research.md

@@ -2,8 +2,8 @@
 
 > This is a draft, this tutorial will improve soon
 
-BGPalerter has been designed in order to be suitable for research activities.
-While for production purposes it's usually enough to monitor some prefixes, for research purposes you might need to monitor the entire address space. 
+BGPalerter has been designed in order to be suitable also for research activities.
+While for production purposes it's usually enough to monitor specific prefixes, for research purposes you might need to monitor the entire address space. 
 In particular, BGPalerter is designed to be able to handle many more BGP messages than the current RIS live streaming produces in total, with a small CPU and memory footprint.
 
 This tutorial will briefly explain how to use BGPalerter for research.
@@ -26,12 +26,12 @@ If during your analysis you will find a warning of messages dropped in the logs,
 
 1) Check your code to verify if something is taking too much time for the processing of a single BGP message
 2) Set a higher value for `maxMessagesPerSecond` (depending on the CPU resources available). Something like 10000 is a good start.
-3) Set `multiProcess` to true, in order to use two processes.
+3) Set `multiProcess` to true, in order to use two processes (this is rarely required).
 
 If the memory consumption during your analysis increases drastically, you may want to:
 1) Check your code for memory leaks
-2) Check you are not doing many async calls accumulating in the stack (e.g., if you monitor the entire v6 address space, like on the example above, you cannot do a single network call for each BGP message received. You can instead bundle together multiple calls or pre-filter better).
-3) Check that the `squashAlerts` of your monitor component is working as expected. In particular, if the squashAlerts methods returns null it means the bucket of BGP messages is not yet ready for squashing, remaining in memory. See below for more information.
+2) Check you are not doing many async calls accumulating in the stack E.g., if you monitor the entire v6 address space, like on the example above, you cannot do a single network call for each BGP message received. You can instead bundle together multiple calls or implement a better `filter` function.
+3) Check that the `squashAlerts` of your monitor component is working as expected. In particular, if the squashAlerts methods returns null it means the bucket of BGP messages is not yet ready to be squashed, hence it will remain in memory. See below for more information.
 4) Reduce the `fadeOffSeconds`. This will drop all the BGP messages that took too long to be squashed by `squashAlerts`.
 
 
@@ -54,21 +54,21 @@ export default class myMonitor extends Monitor { // It MUST extend Monitor
     };
 
     updateMonitoredResources = () => {
-        /* You will probably not need the line below. Essentially you will be notified every
-         * time the set of monitored prefixes changes (note: this.input is inherited from the super class) */
-        const monitored = this.input.getMonitoredMoreSpecifics();
+        /* This function allows you to set what you are going to
+         * monitor and update the set every time the input changes */
+        this.monitored = this.input.getMonitoredMoreSpecifics();
     };
 
     filter = (message) => {
         /* Pre-filtering. This filtering is blocking since it happens synchronously.
          * Make this filtering as tight as possible without involving external resources
-         * (e.g., do NOT do database or API call here). For example base your filtering
+         * (e.g., do NOT do database or API calls here). For example base your filtering
          * on the properties of the BGP message received */
         return message.type === 'announcement';
     };
 
     squashAlerts = (alerts) => {
-        /* The input alerts is an array of alerts with the same signature generated by the monitor method.
+        /* The input 'alerts' is an array of alerts with the same signature generated by the monitor method.
          * Alerts with the same signature are usually referring to the same issue (maybe as seen by different peers).
          * The expected output is a string. Here you can define what is the summary for the entire "chunk" of alerts.
          * If you return null, the alerts will not be sent to the report but will remain in the queue. The next
@@ -86,23 +86,24 @@ export default class myMonitor extends Monitor { // It MUST extend Monitor
         new Promise((resolve, reject) => {
             /* This method is non blocking since it happens asynchronously.
              * Here you can do database or API calls (maybe bundle multiple requests together to reduce network overhead). 
-             * This is where the real analysis happens and when the alerts are generated. Place here your complex filtering/analysis. */
+             * This is where the real analysis happens and when the alerts are generated. Place here your complex filtering/analysis. 
+             * The 'filter' function described before is needed to avoid useless calls to the 'monitor' function, which is much more expensive in terms of memory. */
 
             const matchedRule = this.getMoreSpecificMatch(message.prefix); //The method getMoreSpecificMatch is inherited from the super class, it provides the rule in prefixes.yml that matches the current BGP message.
             
             if (matchedRule) { // We matched something in prefixes.yml
                 const signature = message.originAS.getId() + "-" + message.prefix; // All messages with the same origin AS and prefix will be bundled together. Read above the squash method to understand why.
                 
                 this.publishAlert(signature, // The method publishAlert is inherited from the super class.
-                    message.prefix, // The monitored resource subject of the alert (it can be an AS)
-                    matchedRule, // The monitored rule that was matched (prefixes.yml)
+                    message.prefix, // The monitored resource subject of the alert (it can be an AS or a prefix)
+                    matchedRule, // The monitored rule that was matched (from prefixes.yml)
                     message, // The entire BGP message (needed for possible further troubleshooting or for storing it)
                     {
                         love: "pizza" // Extra information I want to annotate this alert with (this information will be shared with the squash method and all the reports)
                     });
             }
 
-            resolve(true); // Remember to resolve the Promise when the calculation is completed. Don't forget!
+            resolve(true); // Remember to resolve the Promise when the calculation is completed!
         });
 }
 ```

package.json

@@ -4,7 +4,7 @@
   "description": "Software to monitor streams of BGP data. Pre-configured for real-time detection of visibility loss, RPKI invalid announcements, hijacks, and more.",
   "author": {
     "name": "Massimo Candela",
-    "url": "https://massimocandela.com"
+    "url": "http://massimocandela.com"
   },
   "license": "BSD-3-Clause",
   "main": "src/worker.js",