Documentation
Rate This Document
Findability
Accuracy
Completeness
Readability
SubmitClose

Collecting Data During Runtime

The K-NET data collection and analysis tool packages tracelib-collector-aarch64.tar.gz and tracelib-collector-x86_64.tar.gz are available on Kunpeng and x86 servers, respectively. After the packages are decompressed, the dynamic library librecord.so is generated in the decompression directory. This dynamic library is loaded through the LD_PRELOAD environment variable when applications are running, allowing it to collect POSIX function and parameter information.

  • The dynamic library is compatible with both x86 and Kunpeng architectures and requires Glibc 2.17 or later.
  • The tool does not collect variable parameter functions in common scenarios. For the variable parameter functions in the compatibility list, only the first three parameters (fcntl, fcntl64, and ioctl) required for compatibility analysis are collected.

Command Function

Collects POSIX functions and parameters during runtime.

Syntax

Executing librecord.so depends on the libglib-2.0.so and libgobject-2.0.so files distributed in the same package. Therefore, set LD_LIBRARY_PATH to include the directories of the two dynamic libraries. This setting prevents the "undefined symbol" error caused by the failure to find the dependent libraries.

LD_LIBRARY_PATH=/directory/of/:$LD_LIBRARY_PATH LD_PRELOAD=/path/to/librecord.so [Environment variable 1=Argument 1] ... [Environment variable n=Argument n] executable args

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.

  • /directory/of/: directory where librecord.so, libglib-2.0.so, and libgobject-2.0.so are located.
  • /path/to/: path to the librecord.so file.
  • executable: Mandatory. Replace it with the actual path to the binary file to be collected.
  • args: Replace it with the argument required by the binary file.

Parameter Description

Table 1 Environment variables

Environment Variable

Data Type

Description

RECORD_CONF

str

Configuration file, which specifies the path to the configuration file of the POSIX 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.

POSIX 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.

RECORD_FUNC_LIMIT

int

Maximum number of records for each function in a single thread ID. If this parameter is not specified, the maximum number of records is 2^31-1. This parameter is optional.

RECORD_TIMEOUT

int

Collection timeout duration, in seconds. If this parameter is not specified, it is 2^63-1 seconds. This parameter is optional.

If a preset function call is triggered after the specified time, the program automatically exits and the data collected before the exit is retained.

Configuration File Description

The configuration file specified by RECORD_CONF is in the following format:

pthread_create 1
fork 1
socket 1
bind 0

Each line in the configuration file contains only two columns. The first column is the POSIX function name. The second column indicates whether to (0 or 1) record the parameter of the called function. Spaces are used as separators.

Storage of Collected Data Files

Data of different threads is stored in different files whose names are record.TID. These collected data files are in the following format:

1
2
3
4
5
6
7
1 36149310 3081497 3081497 3081504 3081497 2740656
2 35935130 3081504 3081497
0 bind 36216020 36222800 0 3 4 P1{sin_family:2,sin_port:0,sin_addr:{s_addr:16777343}} 16
0 getsockname 36345480 36347240 0 3 4 P1{sin_family:2,sin_port:5531,sin_addr:{s_addr:16777343}} P1{16}
0 connect 36528690 36600760 -1 3 5 P1{sin_family:2,sin_port:5531,sin_addr:{s_addr:16777343}} 16 16777343 24295
0 select 36703260 36709980 1 5 6 P0 P1 P0 P1{tv_sec:4,tv_usec:999997}
3 413

Each line in the data file indicates a data packet. The first digit of a data packet indicates the data packet type:

  • 0: Function information.
    The number of parameters and whether parameter data is recorded depend on the configuration file. Spaces are used as separators. The parameters in this type of data packet are used for subsequent compatibility analysis. The timestamp and function name are used for drawing sequence diagrams.
    0 <Function name> <Entry timestamp> <Exit timestamp> <Return value> [<Number of parameters> <Parameter data 1> <Parameter data 2> ...]

    The parameter data can be a value or pointer. The format of a pointer parameter is as follows:

    • Null pointer: P0 indicates that the pointer is null.
    • Integer pointer: P1 indicates that the pointer is not null, followed by the integer value to which the pointer in {} points, for example, P1{16}.
    • Structure pointer: P1 indicates that the pointer is not null, followed by the structure data to which the pointer points. The structure field is enclosed by {}, and its format is {Member name 1:Formatted data of member 1,Member name 2:Formatted data of member 2...}. If a member in a structure is also a structure, it is formatted in the same format.
  • 1: process information
    Information such as process IDs in data packets of this type is mainly used to represent the relationship between processes during the creation of a sequence diagram. Spaces are used as separators.
     1 <Timestamp> <Process ID> <Process group ID> <Thread ID> <Thread group ID> <Parent process ID>
  • 2: thread creation information
    Information such as thread IDs in data packets of this type is mainly used to represent the relationship between threads during the creation of a sequence diagram. Spaces are used as separators.
    2 <Timestamp> <Current thread ID> <Parent thread ID>
  • 3: user-mode time consumption information of a process

    Spaces are used as separators. Data packets of this type are recorded in the last line of the data file corresponding to the main thread of each process. These data packets provide statistics (unit: ns) for network I/O feature analysis.

    3 <User-mode time consumption information of a process>