Reporting

From Halon, SMTP software for hosting providers
Jump to: navigation, search

Statistics are collected as counters (legends) and also automatically made into historical line graphs (round-robin databases).

Some counters are created automatically, such as configured domains. If you only have an any (catch all) domain, you will not get domain statistics. If you need statistics for a particular domain, add each domain as domain aliases to your any domain.

To create your own counters or line graphs, use the stat() core function. Pie charts can also display entries from the rate() function.

On the non-clustered activity page, you can view the available legends by pressing the "Legends" button. Legends can also be extracted using the statList SOAP call.

Line charts (graphs)

Line graphs are automatically created from the legends (counters). The raw round-robin database[1] data can be fetched using the graphFile call.

Pie chart

When pressing "Edit" on a pie chart, you can enter expressions line-by-line. Each line is interpreted standalone, but added together in the resulting pie. There are two syntaxes; one based on keys, and another on math.

Key based

Key-based expressions maps directly to values the legends database. They contain a key name, and a legend filter, separated by ":". Each legend has three "parts" (keys), and the filter specifies those parts separated by "," (comma). You can use "%" as a wild-card, in order to do partial matching. If multiple legends are matched by your legend filter, they are grouped and summarized. You can make up your own keys, which will be used as labels, such as

blocks:ippolicy:blocked,mailserver:1

or use any of the special (reserved) key names, which expands to multiple entires

Special key Example
key1 key1:ippolicy:%,mailserver:1
key2
key3 key3:hsl:stat,ip-family,%
clusternode clusternode:mail:total

The first example, key1, would probably match two legends (ippolicy:allow,mailserver:1 and ippolicy:block,mailserver:1) because if the "%" (wild-card). Since the key name is key1, it will use the first part (key) as label (allow and block). Because no third legend key was given, the last one (key3) automatically becomes a wild-card match, and would have been summarized if multiple legends were matched.

Math based

The math based syntax is name=expression. They are identified by their "=" separator.

foo=rand(1,10)
bar=(5+10)/3
pass=v("hsl:stat,dkim,pass")
total=r("perday,total")

Operators

Operator Example
+ sum=1+3
- difference=4-1
/ quotient=10/2
* product=5*5
^ power=2^10

Functions

Function Example
v result=v("hsl:stat,mystats,legend1")
r result=r("namespace,entry")
q result=q("quarantine=mailquarantine:1")
sin result=sin(5)
cos result=cos(5)
tan result=tan(5)
abs result=abs(-5)
rand result=rand(1,10)

Please note that the v() function may match one legend. The q() function returns number of hits based on a queue search.

Examples

Weekly statistics

To view a certain metric for an arbitrary period of time, rate controls can be used (because counts expire). This method only works up to a certain amount of traffic; otherwise it will consume too much CPU (keep in mind that each "count" in an actual item in memory). For example, to view the amount of messages per week (works up to 100000 messages), you could use a script such as

rate("week-stat""total"1000003600*24*7); 

in the very beginning of the content flow, and

rate("week-stat""delivered"1000003600*24*7); 

at the very end, just before the message is delivered. To visualise it, you could create a pie chart like

blocked=r("week-stat,total")-r("week-stat,delivered")
delivered=r("week-stat,delivered")