NAME

ltpstats - Licklider Transmission Protocol (LTP) processing statistics query utility

SYNOPSIS

ltpstats [-a | -k | -g] [-r]

DESCRIPTION

ltpstats logs messages containing the current values of LTP processing statistics accumulators for all configured LTP spans, then terminates. The utility provides flexible reporting options to display statistics in different formats and with varying levels of detail.

ltpstats reports statistics on a per-span basis, identified by the remote engine ID. Each statistic includes both a count (number of occurrences) and bytes (total bytes processed).

Statistics are accumulated from the time of span creation or from the last reset operation. The -r option can be used to reset the current statistics after reporting.

OPTIONS

-a

Report all 27 LTP statistics. This mode provides comprehensive visibility into all aspects of LTP operation including segments queued, transmitted, received, acknowledgments, errors, and discards.
-k

Report key statistics only (default). This mode reports the most important statistics for monitoring LTP performance:
- Outbound segments queued and transmitted
- Checkpoint transmissions and retransmissions
- Segment retransmissions
- Export (transmission) completions
- Inbound red and green segments received
- Checkpoints received
- Import (reception) completions
-g

Report grouped statistics. This mode organizes statistics into logical categories for easier analysis:
- Export (Outbound): Segments queued/transmitted, checkpoints, retransmissions, export completions
- Import (Inbound): Segments received (red/green), checkpoints received, import completions
- Acknowledgments: Positive/negative reports sent and received, report retransmissions
- Errors/Discards: Redundant, malformed, unknown sender/client, screened, miscolored segments, and cancellations
-r

Reset current statistics after reporting. This option resets the currentCount and currentBytes fields to zero and updates the resetTime to the current time. The reset operation is performed after the statistics are logged.

Note: This option modifies the SDR database and requires write access.

OUTPUT

ltpstats writes statistics to the ion.log file. All output is logged between start and end markers:

[i] Start of LTP statistics snapshot...
[x] span <engineId> <statistic> from <resetTime> to <currentTime>: <count> <bytes>
[i] ...end of LTP statistics snapshot.

Each statistics line contains:

span <engineId>

The remote engine ID identifying the LTP span. Statistics are reported separately for each configured span.
statistic

The name of the statistic being reported (e.g., out_seg_queued, ckpt_xmit, in_seg_recv_red).
from <resetTime to <currentTime>>

The time range over which statistics were accumulated. The resetTime is either the span creation time (shown as 1969/12/31-16:00:00 for epoch) or the last time statistics were reset with the -r option.
count

The first number: total count of events or operations for this statistic. For example, for out_seg_queued, this is the number of segments that were queued for transmission.
bytes

The second number: total bytes processed for this statistic. For example, for out_seg_queued, this is the total size in bytes of all segments that were queued. Note that some statistics (like checkpoints) may report 0 bytes as they track control events rather than data transfer.

Example Output

[2025/11/22-22:48:11] [i] Start of LTP statistics snapshot...
[2025/11/22-22:48:11] [x] span 3 out_seg_queued from 1969/12/31-16:00:00 to 2025/11/22-22:48:11: 235 11747594
[2025/11/22-22:48:11] [x] span 3 out_seg_popped from 1969/12/31-16:00:00 to 2025/11/22-22:48:11: 231 11600397
[2025/11/22-22:48:11] [x] span 3 ckpt_xmit from 1969/12/31-16:00:00 to 2025/11/22-22:48:11: 115 0
[2025/11/22-22:48:11] [i] ...end of LTP statistics snapshot.

In this example, for span 3:

235 segments totaling 11,747,594 bytes were queued for transmission
231 segments totaling 11,600,397 bytes were transmitted (popped from queue)
115 checkpoints were transmitted (0 bytes as checkpoints are control segments)

EXIT STATUS

"0"

ltpstats has terminated successfully.
"1"

ltpstats was unable to attach to LTP, probably because ltpadmin has not yet initialized LTP operations, or the ION_NODE_LIST_DIR environment variable is not set correctly for multi-node configurations.

FILES

No configuration files are needed.

ENVIRONMENT

ION_NODE_LIST_DIR

For multi-node test configurations, this variable must be set to the directory containing the ion_nodes file that identifies which node's database to access.

DIAGNOSTICS

The following diagnostics may be issued to the ion.log log file:

ltpstats can't attach to LTP.

ltpadmin has not yet initialized LTP protocol operations, or the environment is not configured correctly.
LTP is not initialized.

The LTP constants database has not been created yet. Run ltpadmin to initialize LTP.
Failed to commit statistics reset.

An SDR error occurred while attempting to reset statistics (only when -r is used). Check SDR status and available memory.

EXAMPLES

ltpstats

Display key statistics for all LTP spans (default behavior).
ltpstats -g

Display statistics organized by category (Export, Import, Acknowledgments, Errors).
ltpstats -a

Display all 27 LTP statistics for comprehensive monitoring.
ltpstats -k -r

Display key statistics and then reset the current counters.

BUGS

Report bugs to <https://github.com/nasa-jpl/ION-DTN/issues>