How to use the command gnomon (with examples)
Gnomon is a utility tool that can be used to annotate console logging statements with timestamps and find slow processes. It provides additional functionalities such as showing the number of seconds since the start of the process and displaying timestamps in different formats. This article will illustrate different use cases of the gnomon command.
Use case 1: Piping stdout of any command through gnomon
Code:
npm test | gnomon
Motivation:
Piping the standard output (stdout) of any command through gnomon allows us to annotate the console logging statements with timestamps. This is helpful in understanding the timing and sequence of different processes in the command output.
Explanation:
The | symbol is used to redirect the output of the npm test command to the input of the gnomon command. This enables gnomon to annotate the console log statements with timestamps. The gnomon command itself does not require any additional arguments for this use case.
Example output:
[2021-01-01 00:00:01 +0000] INFO: Test started
[2021-01-01 00:00:02 +0000] DEBUG: Processing data
[2021-01-01 00:00:03 +0000] WARNING: Data validation failed
[2021-01-01 00:00:04 +0000] ERROR: Unable to connect to the database
Use case 2: Showing number of seconds since the start of the process
Code:
npm test | gnomon --type=elapsed-total
Motivation:
By using the --type=elapsed-total argument, gnomon displays the number of seconds since the start of the process for each annotated log statement. This provides a better understanding of the execution time for different parts of a process.
Explanation:
The --type flag is used to specify the type of timestamp to be displayed. In this case, the value is set to elapsed-total to show the total elapsed time in seconds since the start of the process. The gnomon command is used with the npm test command using the pipe symbol.
Example output:
[2021-01-01 00:00:01 +0000][0s] INFO: Test started
[2021-01-01 00:00:02 +0000][1s] DEBUG: Processing data
[2021-01-01 00:00:03 +0000][2s] WARNING: Data validation failed
[2021-01-01 00:00:04 +0000][3s] ERROR: Unable to connect to the database
Use case 3: Showing an absolute timestamp in UTC
Code:
npm test | gnomon --type=absolute
Motivation:
Sometimes, it is important to view the log statements with absolute timestamps in UTC to maintain consistency across different systems and time zones. By using the --type=absolute argument, gnomon can display log statements with timestamps in UTC.
Explanation:
The --type flag is again used to specify the type of timestamp to be displayed. In this case, the value is set to absolute to show the absolute timestamp in UTC. The gnomon command is used in conjunction with the npm test command using the pipe symbol.
Example output:
[2021-01-01 00:00:01 +0000] INFO: Test started
[2021-01-01 00:00:02 +0000] DEBUG: Processing data
[2021-01-01 00:00:03 +0000] WARNING: Data validation failed
[2021-01-01 00:00:04 +0000] ERROR: Unable to connect to the database
Use case 4: Setting a high threshold for elapsed time
Code:
npm test | gnomon --high 0.5
Motivation:
Sometimes, it is necessary to highlight log statements that take a significant amount of time to execute. By setting a high threshold for the elapsed time, we can identify and focus on these potentially slow processes.
Explanation:
The --high flag is used to specify a high threshold for the elapsed time. In this example, the value is set to 0.5 seconds. If any log statements take longer than 0.5 seconds, the timestamp for those statements will be colored bright red. The gnomon command is used with the npm test command using the pipe symbol.
Example output:
[2021-01-01 00:00:01 +0000] INFO: Test started
[2021-01-01 00:00:02 +0000] DEBUG: Processing data // Colored bright red
[2021-01-01 00:00:03 +0000] WARNING: Data validation failed
[2021-01-01 00:00:04 +0000] ERROR: Unable to connect to the database
Use case 5: Setting a medium threshold for elapsed time
Code:
npm test | gnomon --medium 0.2
Motivation:
Similar to the previous use case, setting a medium threshold for the elapsed time allows us to identify log statements that take a moderate amount of time to execute. By using a different color, we can easily distinguish these statements from others.
Explanation:
The --medium flag is used to specify a medium threshold for the elapsed time. In this example, the value is set to 0.2 seconds. If any log statements take longer than 0.2 seconds but less than the high threshold, the timestamp for those statements will be colored bright yellow. The gnomon command is used with the npm test command using the pipe symbol.
Example output:
[2021-01-01 00:00:01 +0000] INFO: Test started
[2021-01-01 00:00:02 +0000] DEBUG: Processing data // Colored bright yellow
[2021-01-01 00:00:03 +0000] WARNING: Data validation failed
[2021-01-01 00:00:04 +0000] ERROR: Unable to connect to the database
Conclusion:
Gnomon is a powerful utility that adds timestamp annotations to console logging statements. It can be used to improve the visibility of log data, understand the timing of processes, identify slow processes, and format timestamps in different ways. By following the use cases mentioned in this article, users can leverage the capabilities of gnomon effectively.
