Skip to content

MXTRAX wiki

Jump to bottom Edit New page
Mykhaylo Ignatenko edited this page Dec 23, 2013 · 42 revisions

Table of Contents

Getting started.

To build your mxtrax.db SQLite3 database and configure admin login, run in terminal: cd pr (to jump into your project directory) python manage.py sql mxtrax (you will see SQL code for 7 CREATE TABLEs: mxtrax_customer, mxtrax_maildomain, mxtrax_mailtest, mxtrax_config, mxtrax_stat) python manage.py syncdb (to sync mxtrax.db that you have just created). You will see the following:

  • You just installed Django's auth system, which means you don't have any superusers defined.
  • Would you like to create one now? (yes/no): yes
  • Username: i.e. root
  • Email address: [your email address]
  • Password: [create admin password]
  • Password (again): [retype the password]
  • Superuser created successfully.
To light up your production server: cd pr (if you’re not already in your project directory) python manage.py runserver xxx.xx.xx.xx:8000 (to run your production server)

Open your browser and go to http://xxx.xx.xx.xx:8000/admin/. You will be asked to log in using the admin login info that you created by running “syncdb” above.

Before sending any email tests, you need to add your Config info. To make sure that there is only one Config objects, the “+Add” button will disappear after you add your first Config object.

Click “+ Add” button and enter the following info:

  • Inbox email address (sendinguser) - test email accounts on your customers’ domains will bounce all email tests to this email.
  • Max round trip time (maxreturntime) - maximum allowed round trip time in seconds for each email test. The default is set to 300 seconds. If an email test takes longer to bounce back than this time, it will be either marked as “late” or “failing”.
  • Send alerts to (alertuser) - email address to which reports about failing domains will be sent.
  • Mailbox path (mboxpath) - absolute path to receiving mailbox that is associated with inbox email address above (i.e. /var/mail/mxtrax).
  • Max no bounce back number (maxfailnumber)- maximum allowed number of emails that did not bounce back, per each domain. The default is set to zero. The purpose of this field is to allow a few email tests to fail so that you don’t get numerous failure alerts while you are still configuring MXTRAX.
  • Max no bounce back % (maxfailpercentage) - maximum allowed ratio of no bounce back email tests over total number of email tests that were sent to that domain.
  • Max late number (maxlatenumber) - maximum allowed number of late email tests, per each domain. A late email is the one that took more than Max round trip time above but less than Max sec until fail below to bounce back to Inbox email address above.
  • Max late % (maxlatepercentage) - maximum allowed ratio of late email tests over total number of email tests that were sent to that domain.
  • Max sec until fail (max_sec_until_fail) - maximum time, in seconds, until a supposedly late email test is marked as failing. The default is set to 86400 seconds (1 day). If an email test took more than one day since its send time to bounce back, then we can mark that email tests as “failing” and not “late”.

Bulk customers/domains import.

/pr/mxtrax/management/commands/addmaildomains.py Addmaildomains.py allows to import customers/domains from a CSV file into Customer and MailDomain tables. You will get an error message (i.e. file does not exist, you forgot to include -f etc.) if you do not run. python manage.py addmaildomains -f [absolute path to your CSV file]. Addmaildomains also prints out statistics on how many MailDomains were imported, how many weren't imported because they are already in MailDomains database, and how many weren't imported because they did not pass email validation test (i.e. have typos in them). Additionally, Addmaildomains verifies that the total number of lines (excluding the first sample row "Customer.friendlyname,Customer.codename,MailDomain.testuser,MailDomain.domainname") in CSV file is equal to the sum of MailDomains that were imported, already existed in MailDomain database, and those that have typos.

You can also add customers/domains manually by going to http://xxx.xx.xx.xx:8000/admin/mxtrax/ and clicking “+Add” buttons next to “Customers” and “Mail domains”.

Manual Commands and Logistics.

cd pr (if not there already) python manage.py sendtests (The code is located in: /pr/mxtrax/management/commands/sendtests.py). This command sends an email test to all objects in MailDomain database that are not marked as “Maintenance Mode”. If you are still configuring test email address of a certain domain and don’t want any email tests to be sent to it, go to http://xxx.xx.xx.xx:8000/admin/mxtrax/maildomain/ and mark that domain as “Maintenance Mode”. The subject line of each email test contains a UUID (i.e. 94005aa5-0c39-40b6-a3c2-e88214eb38fd). For each sent email, sendtests.py automatically creates a MailTest object with the following info:

  • testid - UUID specific to only that email test.
  • sendtime - current server time rounded to seconds
  • receivetime - left blank to be filled in later when receivetests command is run
  • domain - foreign key to reference the corresponding MailDomain
  • incl_in_stat - marked False because the MailTest hasn’t yet been processed by receivetests command
cd pr (if not there already) python manage.py receivetests.py (The code is located in: /pr/mxtrax/management/commands/receivetests.py). Receivetests performs the following tasks:
1. It scans the receiving mailbox file (you specified the path to it in Config) and looks for any MailTests that don’t have receivetime. Receivetests compares UUIDs of MailTests with no receivetime to subject lines of messages in the inbox. If there is a match, receivetests command extracts receivetime from that message, updates the corresponding MailTest object’s receivetime, and deletes the processed message from the inbox. This way the inbox does not get cluttered with MailTests that successfully bounced back into the inbox, and receivetests command runtime is minimized in the future.
2. The next task for receivetests command is to calculate overall statistics, for all MailTests. Receivetests counts each MailTest object into one of the three categories: on-time, late, or no-bounce-back. These are the total numbers of MailTests in each of the three categories. To ensure that a MailTest that has just been sent out but hasn’t yet bounced back is not counted towards total no-bounce-back number, receivetests command checks that the time when you run the command is more than MailTest’s sendtime plus maxreturntime from Config.
3. After calculating overall statistics for all MailTests, receivetests calculates statistics for each MailDomain that is not marked as “in maintenance mode”: number of on-time MailTests, number of late MailTests, number of failed (no bounce back) MailTests, on-time percentage, late percentage, no-bounce-back (failing) percentage, average delivery time for all on-time and late MailTests. If a MailDomain fails to meet the restrictions that you specified in Config, it will be marked as “failing”.
4. The next step is to send an email alert to alertuser, which you specified in Config. If at least one MailDomain that is not in “maintenance mode” is marked as “failing” in step 3, then the email alert will be sent. The email alert will have detailed for all MailDomains, not just the one that is failing. If all MailDomains are functioning well (based on the restrictions that you specified in Config), you will not get an email alert.
This is an example of what an email alert text body will look like: 
 this domain is failing: user1@domain1.com
 overall on-time rate is: 40.00 percent.
 on time: 2.
 late: 0.
 did not return: 3.
 total: 5.
 average delivery time: 0:00:00.500000.
 MAX late number limit: 0
 MAX late percentage limit: 0.00
 MAX not bounced back number limit: 0
 MAX not bounced back percentage limit: 0.00
 Here are some stats for each domain:
 
 stats for: user1@domain1.com
 on time: 0
 late: 0
 did not bounce back: 3
 there are no successful or late tests - cannot calculate average delivery time.
 on-time rate is: 0.00 percent
 late rate: 0.00 percent
 not bounced back rate: 100.00 percent
 domain exceeded the max not bounced back number limit
 domain exceeded the max not bounced percentage limit
 Is this domain marked as failing? - YES
 ---------------------------------------------------------------
 
 stats for: user1@domain2.com
 on time: 2
 late: 0
 did not bounce back: 0
 average delivery time: 0:00:00.500000.
 on-time rate is: 100.00 percent
 late rate: 0.00 percent
 not bounced back rate: 0.00 percent
 Is this domain marked as failing? - NO
 ---------------------------------------------------------------
5. The last task that receivetests has to accomplish is to create/update Stat tables. Each Stat object is defined by date and MailDomain. This data will be used to graph daily combined statistics for the requested MailDomain. Receivetests looks at all MailTests and creates Stat objects by looking at all possible MailDomain/date combinations from MailTests. For example, if you have just added a new MailDomain today and sent a few MailTests to it, receivetests command will detect the new combination: the newly-added MailDomain and today’s date. In this case, receivetests will create a Stat object defined by the new MailDomain and today’s date. Each MailTest is scanned through to extract the following info before it is marked as “processed” (so that receivetests doesn’t have to run through it again in the future):
a) check if the new MailTest’s delivery time is smaller than min_delivery_time for that day or bigger than max_delivery_time for that day. If yes, receivetests command updates the corresponding field of the corresponding Stat object
b) increment Stat object’s ontime_num, late_num, fail_num, total_num based on whether a non-processed MailTest is on-time, late, or failing.
c) increment Stat object’s total_delivery_time by the delivery time of the given non-processed MailTest.
d) check Stat’s all_done box if Stat’s date is in the past and if the total_num of that Stat object is equal to the sum of ontime_num, late_num, and fail_num. This means that all MailTests for that MailDomain and date have been processed and accounted for in either ontime, late, or failing numbers.
To view statistics for each MailDomain, go to http://xxx.xx.xx.xx:8000/dash/[full_email_address]/. You can zoom into the desired time period by clicking and dragging the focus chart below the graph. You can also click “Refresh” below to update the graph. By default, the graph’s horizontal axis will start from the earliest date of all MailTests for the MailDomain that you specified in the URL bar and end with the latest Mailtest for the MailDomain.

Command Automatization.

add info about scheduling jobs using CRONTAB.

Reviewing Results.

If you want to see MailDomain info in JSON format, open your browser and go to: http://xxx.xx.xx.xx:8000/api/v2/maildomain/?format=json - shows all domains from MailDomain database. OR http://xxx.xx.xx.xx:8000/api/v2/maildomain/[x]/?format=json - shows info for the specified domain, where [x] is the domain ID number from MailDomain database.

If you want to see Stat info in JSON format, open your browser and go to: http://xxx.xx.xx.xx:8000/api/v1/stat/?format=json - shows all Stat objects.

Please refer to the instructions above if you want to view MailTest results graphed out.

Database/table structure.

1. Config: see above in Getting Started section.
2. Customer:
A. Customer Code (codename) - short code for your customer’s name
B. Name (friendlyname) - customer’s full name
3. MailDomain:
A. Mail domain name (domainname) - second part of customer’s email address (i.e. email.com)
B. Test user name (testuser) - first part of customer’s email address (i.e. mxtrax if the full email address is mxtrax@email.com). No need to add “@” to either mail domain name or test user name fields.
C. Failing (failing) - this checkbox will be checked if this MailDomain failed to meet the restrictions that you set up in Config.
D. Maintenance Mode (maintmode) - as mentioned above, if this checkbox is checked, sendtests and receivetests commands will ignore sending emails to and calculating Stats for that MailDomain
E. Customer (customer) - foreign key to the corresponding Customer object from Customer table
4. MailTest:
A. Test ID (testid) - Unique Universal Identifier (UUID) for that MailTest
B. Send time (sendtime) - date and time when the MailTest was sent
C. Receive time (receivetime) - date and time when the MailTest bounced back into receiving mailbox that you specified in Config. This field will be empty if either receivetests command wasn’t executed or the email never bounced back.
D. Mail Domain Name (maildomain) - this is a foreign key that references MailDomain table.
E. Was this MailTest already processed and included in Stats? (incl_in_stat) - this checkbox makes receivetests command run faster. If a MailTest was processed and included in Stat table for the corresponding MailDomain and that specific date, there is no need to run through it once again when executing receivetests command again.
5. Stat:
A. MailDomain (domain) - this is a foreign key to the corresponding MailDomain
B. Date (d) - MailDomain and Date are the two components that define each Stat object. That way you can view email test statistics for the specific day and specific MailDomain
C. Min delivery time (min_delivery_time) - minimum email test delivery time, in seconds, for all MailTests that were sent to the given MailDomain on the given date
D. Max delivery time (max_delivery_time) - maximum email test delivery time, in seconds, for all MailTests that were sent to the given MailDomain on the given date
E. On-time num (ontime_num) - number of on-time MailTests for the given MailDomain on the given date
F. Late num (late_num) - number of MailTests for the given MailDomain on the given date that bounced back too late based on the restrictions that you set up in Config.
G. Failing num (fail_num) - number of failing MailTests for the given MailDomain and date
H. Total num (total_num) - the total number of MailTests that were sent out on that day to that MailDomain
I. Total delivery time (total_delivery_time) - the total combined delivery time, in seconds, for all MailTests on the given date that bounced back and were processed by executing receivetests command. This number is used to calculate average bounce back time for MailDomains on each date.
J. Stats all done for this MailDomain on the given date? (all_done) - this checkbox will be checked if all MailTests that were sent out on that date to that MailDomain have been processed and included in either on-time, late, or failing category. You will see this checkmark if the date of the Stat object is in the past and if the sum of On-time num, Late num, and Failing num matches Total num.
Add a custom footer
Add a custom sidebar

Clone this wiki locally