Using a Standalone Package

Prerequisites

You have obtained the Link Latency Detection tool package (tracelib-collector-aarch64.tar.gz or tracelib-collector-x86_64.tar.gz) from Obtaining the Tool Packages.

Tool Package Overview

Select a Link Latency Detection tool package (tracelib-collector-xxx.tar.gz) based on your server type. After the tracelib-collector-xxx.tar.gz package is extracted, the following files are generated:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

tracelib-collector-xxx/
├── analyze
├── Software License Agreement.txt
├── libglib-2.0.so -> libglib-2.0.so.0
├── libglib-2.0.so.0 -> libglib-2.0.so.0.7500.0
├── libglib-2.0.so.0.7500.0
├── libgobject-2.0.so -> libgobject-2.0.so.0
├── libgobject-2.0.so.0 -> libgobject-2.0.so.0.7500.0
├── libgobject-2.0.so.0.7500.0
├── librecord.so -> librecord.so.25
├── librecord.so.25 -> librecord.so.25.2.0
├── librecord.so.25.2.0
├── README.md
├── symbol
└── Software License Agreement.txt

Usage Description

1. Upload the compressed package of the Link Latency Detection tool to the corresponding directory (for example, /home/) on the server.
2. Extract the tool package.

   1 2	tar -zxvf tracelib-collector-xxx.tar.gz cd tracelib-collector-xxx

3. Create a configuration file quickly using symbol or edit a configuration file.
   • Create the configuration file using the symbol tool.

     1	./symbol /path/to/your_app -e 'Test&Symbol' -o path/to/output.conf

     Table 2 Parameters of symbol

     Parameter	Description
     -e/--expr	Function symbols to be collected. For example, Test&Symbol indicates that all symbols containing Test and Symbol are collected.
     -f/--file	File to be read. Each line contains one function.
     -o/--output	Path to the configuration file to be created.

   • Create the configuration file manually.

     For details about the configuration file, see Configuration File (RECORD_CONF).

4. Set environment variables and start the application.

   librecord.so depends on libglib-2.0.so and libgobject-2.0.so in the same directory. Therefore, you need to specify LD_LIBRARY_PATH.

   1	LD_LIBRARY_PATH=/directory/of/:$LD_LIBRARY_PATH LD_PRELOAD=/path/to/librecord.so RECORD_CONF=/path/to/my_app.conf /path/to/your_app [app_arguments]

   

   • LD_LIBRARY_PATH points to the directory where librecord.so is located.
   • LD_PRELOAD points to the collection library librecord.so.
   • RECORD_CONF points to the configuration file.

   To collect runtime data, you need to specify the dynamic library path, configure environment variables, and the path to the binary file to be collected. You can configure one or more environment variables, among which RECORD_CONF is mandatory. Separate multiple environment variables using spaces.

   Table 3 Parameter description

   Parameter	Description
   /path/to/your_app	Replace it with the actual path to the binary file to be collected. This parameter is mandatory.
   app_arguments	Arguments required by the binary file.

   Table 4 Environment variables

   Environment Variable	Data Type	Description
   RECORD_CONF	str	Configuration file, which specifies the path to the configuration file of the functions to be recorded. This parameter is mandatory. Even when the pthread_create and fork functions are not specified in the configuration file, the two functions are still collected by default.
   RECORD_OUT_DIR	str	Data file output directory. This parameter is optional. If this parameter is not set, the record.data folder is created in the current directory. Function information is collected based on the configuration file specified by RECORD_CONF. The collected data is stored in the output directory specified by RECORD_OUT_DIR. Data of different thread IDs is stored in different files.
   RECORD_VERBOSE	int	Indicates whether to print log information. The default value is 0. This parameter is optional. 1: prints logs. 0: does not print logs.

5. View the collected data.

   The tool generates an independent data file named record.tid for each thread that executes the target function.

   An original data file records the entry and exit timestamps and time consumption of each function call. The following is an example:

   1 2 3 4 5 6 7

   1 36149310 3081497 3081497 3081504 3081497 2740656 2 35935130 3081504 3081497 0 _Z4funcv 34587450 34714230 126780 0 bind 34739850 34746540 6690 0 3 4 P1{sin_family:2,sin_port:0,sin_addr:{s_addr:16777343}} 16 ... ... 3 1798

   • Pay attention to the data lines starting with 0, which record function call information. The timestamps and time consumptions are in the unit of nanosecond. The format is as follows:

     1	0 <Function name> <Entry timestamp> <Exit timestamp> <Function time consumption> [<Return value> <Number of parameters> <Parameter 1> <Parameter 2> ...

   • The data lines starting with 1 and 2 record the creation information of the processes and threads. The formats are as follows:

     1	1 <timestamp> <process ID> <process group ID> <thread ID> <thread group ID> <parent process ID>

     1	2 <timestamp> <current thread ID> <parent thread ID>

   • If the parent thread is collected, the data lines starting with 3 are also included. The data is obtained through getrusage at the start and end time of the process. The unit is nanosecond. The format is as follows:

     1	3 <user-mode CPU time consumption information of the process>

6. Analyze the collected data.
   You can use the simple analysis tool analyze to analyze the generated data files. The analyze tool collects statistics on the time consumed by top N functions, P99, P75, and average value.

   1	./analyze record.data -m --demangle -c -o metrics

   Table 5 Parameters of analyze

   Parameter	Option	Description
   -o/--output_dir	-	Directory for storing the statistical result.
   -n/--top_n	-	Number of top N functions contained in the statistical result.
   -s/--sort	{avg,max,min,P90,P75,P50,count}	Sorting mode of the result data. By default, the data is sorted in descending order of average time consumption. Sort the values in square brackets as required.
   -c/--csv	-	Specifies the format of the statistical result file as csv. The default format is text.
   -m/--merge	-	Indicates that all data is combined into one file for output. By default, statistics are collected separately for each thread.
   --demangle	-	Symbol name of the statistical result.