This software is intended for use in the `FidoNet` computer network and other FTN-style networks (FTN &ndash; FidoNet Technology Network)

---

# T-Hist for Linux x86_64/i686 and Windows 64/32

The `T-Hist` utility creates text files with graphs and histograms of the FTN node load and with sessions and links statistics
based on information stored in the mailer's binary logs (history files).
The `T-Hist` supports binary log formats of the following mailers: T-Mail, Binkd, Argus, The Brake!, Bink/+, FhMail, DVMmail, KittenMail, BinkleyTerm-XE, FrontDoor, InternetRex, X-Mail32, BasicMail.

Development of the `T-Hist` began in 1996. The latest version of `T-Hist` 0.30.alpha7 for DOS, OS/2, NT (win32) was released in 2003 (it is located in the `_old` directory of this archive.)

After 23 years, the new `T-Hist` (and related utilities `LnkStat` and `DmpHist`) were released for Linux and Windows.

This archive contains executables in the following directories:
* `linux` &ndash; Linux executables (x86_64 and i686 architectures);
* `linux-static` &ndash; Linux executables with static libraries (x86_64 and i686 architectures);
* `windows` &ndash; Windows 64-bit and 32-bit executables.

The complete documentation for the new version has not yet made. As a basis, you can take a description of the utilities (in Russian only) and an example of a configuration file
from the archive with the last older version `0.30.alpha7` located in the `_old` directory of this archive.
Ignore the possible error messages when unpacking the archive with older version: `unzip` unpacks it without errors, and `7z` reports errors, but still extracts files correctly.

The text files of the documentation and an example of the configuration file of the older version are have CP866 encoding with DOS-like line break.
To use the old configuration file in Linux, convert it to Unix format:
```shell
dos2unix t-hist.ctl
```

## Terms used in this document

- The term `old versions` means `T-Hist` `0.30.alpha7` from 2003, and earlier versions.

- The term `parameter` means parameter in the configuration file.

- The terms `group`, `group of addresses` means an address defined in `Addr` parameter with at least one `#` character (macro).
Addresses that use the wildcards `*` but do not contain `#` are not groups.

- The terms `binary log` and `history file` are equivalent.

## Main features of the new `T-Hist` and related utilities

- All utilities print information and create output text files in UTF-8 encoding.
To post statistics in FTN echo conferences or netmail, text files must be converted to the appropriate encoding.
For example, for Russian-language echo conferences with CP866 encoding:

	```shell
	iconv -f UTF-8 -t CP866 in.txt -o out.txt
	```

- The `LnkStat` and `DmpHist` utilities (but not `T-Hist`) have the `-u` command line option to select the encoding of the printed information:

	`-u`, `-u+` &ndash; use UTF-8 encoding (default)

	`-u-` &ndash; use ASCII 7-bit encoding without pseudo-graphics

- For sessions recorded in a binary log with a duration of 0 seconds, a duration of 1 second is set. This allows more accurate build the load histograms.

	**Reason**: time intervals in binary logs are recorded with an accuracy of a second (binary log formats were developed during dial-up epoch,
when there were practically no sessions shorter than a second). But in Fido-over-IP epoch, sessions often have duration less than a second. For such sessions,
the duration of 0 seconds will be written to the binary log. The older versions of `T-Hist` did not take such short sessions into account when building load histograms.

	**Exception**: `DmpHist` utility continues to work as before. It prints raw data from binary logs without any adjustment.
For sessions shorter than a second, the utility will print a duration of 0 seconds, as recorded in the binary log.

	**Side effect**: default underestimation of the average CPS (Characters per Second &ndash; the number of characters/bytes transferred per second).
By default, when calculating the average CPS, the duration of all sessions is summed up: both non-empty and empty. In the older versions, most empty IP sessions
were 0 seconds long and did not increase the total time of all sessions. After this change, each empty session increases the estimated total time by at least 1 second,
although most likely the session was shorter. The more empty sessions are processed, the more the calculated sum of durations of all sessions will exceed the real total time.
And this leads to an underestimate of the CPS. For compatibility with the older versions, this behavior is retained by default.
For a more correct calculation of the average CPS when using IP mailers, specify in the configuration file:

	`AdvancedCPS Yes`

- On histograms, the load level that is greater than 0% but less than 3% is displayed using the `_` character.
In the older versions, this load level was either displayed excessively large - as a level of 3-10%, or not displayed at all due to the lack of a suitable pseudo-graphic symbol.

- The order of adresses and groups of addresses in `Addr` parameters is no longer important. Regardless of the order, when generating statistics,
they will be sorted from less general to more general. And the excluded addresses and groups of addresses will be placed at the beginning of the adresses list,
simultaneously deleting all present addresses that match the excluded ones. Re-specifying the same addresses will be ignored. For example, if in the configuration file specified:

	```yaml
	Addr 2:5020/#.#
	Addr 2:5020/378.0
	Addr #:#/#.#
	Addr 2:5020/378.0
	Addr 2:#/#.#
	Addr 2:5020/1132.0
	Addr 2:5020/408.0
	Addr !2:5020/1132.*
	Addr !*:*/*.666
	Addr 2:5020/715.#
	Addr 2:5020/1132.0
	Addr !2:5020/408.0
	```

	then the following address list will be used:

	```yaml
	Addr !2:5020/408.0
	Addr !2:5020/1132.*
	Addr !*:*/*.666
	Addr 2:5020/378.0
	Addr 2:5020/715.#
	Addr 2:5020/#.#
	Addr 2:#/#.#
	Addr #:#/#.#
	```

- New algorithm of browsing of the list of addresses specified by the `Addr` parameters. In the older versions, browsing the address list ended after the first match
with the session address. Now, if the session address is not defined as excluded, the browsing will continue to the end of the list. Such an algorithm takes into account
sessions with a separately specified addresses also in the statistics for the groups to which the addresses belongs. For example, for the address list:

	```yaml
	Addr !2:5020/1132.0
	Addr 2:5020/378.0
	Addr 2:5020/#.#
	Addr 2:#/#.#
	Addr #:#/#.#
	```

	the sessions with address `2:5020/378.0` will be taken into account not only in separate statistics for this address, but also in group statistics of sessions
	with addresses of the net `2:5020`, in group statistics of sessions with addresses of the zone `2` and in group statistics of sessions with any addresses.
	And sessions with address `2:5020/1132.0` will be ignored.

- Fixed processing of addresses excluded from statistics (for example, `Addr !2:5020/1132.0`).
In the older versions, sessions with such addresses were mistakenly printed in sessions table, and always as aborted. Now such addresses are excluded from all types of statistics.

- Format of the sessions table is changed. Now the session start time is printed with an accuracy of seconds (the older versions print it with an accuracy of minutes).
The session end time is excluded due to redundancy &ndash; the table contains the duration of sessions.

- Aborted Binkd sessions are marked in the sessions table with `A` character after address. The older versions were not place this mark for the aborted Binkd sessions.

- The `NoDrawZero` parameter also affects the load histograms (in the older versions this parameter only affected load graph).
Now the busy histogram always corresponds to the "summation" of all load graph lines.

- The `DmpHist` utility prints the start time of sessions exactly as it is written in the binary log, without any adjustments. The `TimeShift` parameter is ignored.
Also the `DmpHist` print a more detailed descryption of sessions status bits at the end of the table.

- Parameter names and their values in the configuration file are case-insensitive, with the exception of file names in Linux.

- Linux executables with static libraries are compressed by [UPX 4.2.4](https://upx.github.io) executable packer to reduce their size.

## Optimization

When using `T-Hist` only to process binary logs of Binkd IP-mailer, it is advisable to specify in the configuration file:

`SupportNewFormat No`

The binary log of Binkd is in the old format (like the binary log of T-Mail before version 2603).
Disabling support for the new format will also disable support for all mailers, except Binkd and T-Mail before version 2603, which will reduce the numbers of checks during program execution.

## How to add support of a new mailer

To use `T-Hist` with unsupported mailers, you need to convert the mailer logs to one of the binary log formats supported by `T-Hist`.
The easiest way is converting to binary log of Binkd and T-Mail before version 2603 (so-called old format). Read more in the file `ADD-NEW-MAILER.md`.

## Gratitudes

I would like to thank Alex Barinov `2:5020/715`, `2:50/0` for testing the new versions of `T-Hist` on its node.
I also thank everyone whose ideas, suggestions and help in testing allowed me to create and develop this project.
The names of some of these people are listed in the old documentation file.

---

Mikhail Markovskiy (klug), 2:5020/378

https://klug-photo.dreamwidth.org/709558.html

https://klug.livejournal.com/1102966.html
