Dump journal File
The AMPS journal dump utility is used in examining the contents of an AMPS journal file for debugging and program tuning. The amps_journal_dump utility is most commonly used as a tool to debug the forensic lifespan of messages that have previously been published to AMPS. The amps_journal_dump tool is used to show that messages exist in a journaled topic, and to show the order the message was received in, and the timestamp associated with the message.
Command Line Options
The amps_journal_dump program has the following options available. These can also be printed to the screen by typing amps_journal_dump -help.
Option
Description
filename
(required)
Filename of the AMPS journal file.
-h, --help
Show the program help message and quit.
-l LIMIT
Limit range of output to entries N:M where N is the first entry and M is the last entry.
Passing in a single value, M, will return the first M results.
--localtime
Display ISO 8601 timestamp in local time.
--extents
Add local and replication extents information at the end of the journal dump.
--no-data
Do not display data values in the journal dump output.
--include-noops
Include noops in the journal dump.
Looking at the Output
In this section will examine some sample output from running amps_journal_dump. We will then go over what each of the entries emitted by the program means.
As is apparent in the listing, the output from amps_journal_dump is split into three sections, a header, a listing of the contents of the journal file and a footer.
The header contains general information about the journal file as it is represented in the filesystem, and state data about the journal file.
Field
Description
File Name
The name of the file as it appears on the local filesystem.
File Size
Number of total bytes allocated by the journal file.
Version
This is the version of the formatting used to write the data in the journal file.
Extents
A pair of numbers where the first is the number of extents used by the journal file, and the second is the number of blocks allocated for the journal file.
The second section of the amps_journal_dump lists each of the entries contained in the journal file, along with all of the meta-data used to track and describe the entry. For the sake of simplicity, the example only shows a single journal entry. In an actual installation, amps_journal_dump will produce a record for every message in the journal.
The exact options present depend on the version of the journal file.
Field
Description
entry
A monotonically increasing value representing the order in which the record was inserted into the transaction log file.
crc32
The cyclic redundancy check used for error checking the transaction log entry.
type
The AMPS command used in the original message or the type of entry in the journal file.
file offset
Offset for this entry within the journal file.
tx byte count
Size of this entry within the journal file.
msg byte count
Number of bytes in the message payload.
msg type
Message type of the message.
local txid
The monotonically increasing identifier used across all records local transaction log journal files.
previous local txid
The monotonically increasing identifier used across all records local transaction log journal files.
source txid
The monotonically increasing identifier used across all records local transaction log journal files. If a publish from a client does not include a sequence number, and the publish was made directly to this instance, this field can be used to hold the original client name hash for a publish or delete. In that case, the client name hash used for message identification purposes is generated by AMPS (to avoid message identity conflicts).
source name hash
For replicated messages, the hash of the instance from which the message was received.
client name hash
The hash of the publisher client name. The combination of the client name hash and the client seq are used as the identity of the message. If a publish or delete does not include a sequence number, and the publish was made directly to this instance, this field may be a hash generated by AMPS while the original client name hash is stored in the source txid field.
client seq
The sequence number of the message from this publisher.
topic hash
The identifier for the topic name.
sow expiration time
The expiration set on this individual message when it is used in a SOW topic or queue.
iso8601 timestamp
The time the message was processed, represented as an ISO-8601 timestamp.
timestamp
The raw timestamp stored in the AMPS transaction log. This is a microsecond-precision timestamp.
previous byte count
The size, in bytes, of the previous record in the transaction log.
topic byte count
The length, in bytes, of the topic name.
topic
The name of the topic this command applies to.
data
The data for this entry in the transaction log.
For published messages, this will be the message as published. For other commands, this could be data used internally by AMPS.
correlation id byte count
The number of bytes in the correlation ID for the command.
correlation id
The correlation ID for the command, if one was set on the command.
auth id byte count
The length of the authenticated ID that submitted the command.
auth id
The authenticated ID that submitted the command.
rep path byte count
The length of the replication path. This path records the route that this message took to reach this instance of AMPS.
rep path
The replication path. This path records the route that the message took to reach this instance of AMPS.
As seen in the listing, the final section contains general usage information about the data contained in the journal file.
Field
Description
Total Entries
Total number of journal entries entered into the journal file.
Total Bytes
The number of reserved bytes consumed by the journal file.
Remaining Bytes
The number of unused bytes available out of the total reserved file size.
Timestamp Formatting
The timestamp format used in amps_journal_dump is formatted by default using the system timezone for its location. To display the time in another timezone, the TZ environment variable can be configured to modify the output.
Last updated