Code Generation Submodule

Parses the configuration file to generate a header file and a metadata file, and adds the header file to the service code. It uses the Tracer to trace the service process.

Command Function

Parses the user-defined .ini configuration file to generate a header file and a metadata file. Users can write header file APIs into program code to record log information, and can also use the metadata file to parse log information.

If you do not need to use the code generation submodule to generate header and metadata files, you can use the usability interface provided by the tool. For details, see Example of Using the Usability API.

Syntax

./tracelog generator [-h | --help] [-l {0,1,2,3} | --log-level {0,1,2,3}] {-i <INI_FILE> | --input <INI_FILE>} [-o <OUTPUT_PATH> | --output <OUTPUT_PATH>]

Parameter Description

**Table 1** Parameter description
Parameter	Option	Description
-h/--help	-	Obtains help information. This parameter is optional.
-l/--log-level	0/1/2/3	Log level, which defaults to 1. This parameter is optional. 0: DEBUG 1: INFO 2: WARNING 3: ERROR
-i/--input	-	.ini configuration file. For details about this file, see .ini Configuration File. This parameter is mandatory.
-o/--output	-	Header file and metadata file directory, which defaults to the current directory. The generated header file has the same as the input .ini file. This parameter is optional.

.ini Configuration File

For example, user.ini:

memoryKBs=5120
tracelog="/var/log/trace.log"

[normal_example]
name=char*
id=int
character=char


[callstack_example]
key=int
callstack=3


[pmu_example]
key=int
enablepmu=true

The .ini configuration file contains the following content:

Global configuration items.
1. Cache size configuration, which defaults to 5,120 KB.
2. Log path and log file configuration, which defaults to /var/log/trace.log.
One or more (1 to 16) sections, each with a maximum of 16 parameters. Each section contains two parts:
1. Section name in the format of [section_name], for example, [normal_example].
2. You can set one or more parameters. Common log parameters are displayed in the format of Parameter_name=Parameter_type, for example, name=char*. For details about other parameters, see Table 2.

**Table 2** Parameters in the **.ini** file
Parameter Type	Parameter Description	Format
memoryKBs	Cache size.	The value of memoryKBs is a positive integer ranging from 80 to 81,920. The default value is 5,120.
tracelog	Log generation path.	A character string enclosed in quotation marks.
Section name	Event name.	A character string enclosed in square brackets ([]).
Common log parameter	Parameter transferred in the event.	The parameter type is int, char, or char*.
(Optional) Callstack parameter	Traces call stack parameters.	callstack=positive_integer. The integer ranges from 1 to 64 and defaults to 5.
(Optional) enablepmu parameter	Collects PMU event parameters.	enablepmu=true is case-insensitive. Spaces are allowed before and after the equal sign (=). Any other setting does not take effect. NOTE: When PMU collection is enabled in the configuration file, it is initialized (about within 6 ms to 7 ms) for calling the log API for the first time. The PMU data cannot be obtained by calling the log API, and the terminal displays "[WARNING] Event information cannot be obtained because PMU collection is being initialized." In this case, the default value 0 is returned for the cycles data. To use the PMU collection capability, call DestroyLoggerDevice() before the program ends. Otherwise, the program may become abnormal.

callstack and enablepmu parameter configuration rules:

If neither callstack nor enablepmu is configured in a section, only one API is generated.
If enablepmu is configured but callstack is not configured in a section, two APIs are generated. One API records PMU data, whereas the other API does not. To avoid duplicate function names, if a service application needs to call the API that records PMU data, add _enablepmu to the section name. (If only the enablepmu parameter is configured in this section, only one API is generated and only PMU data is collected.)
If callstack is configured but enablepmu is not configured in a section, two APIs are generated. One API records callstack data, whereas the other API does not. To avoid duplicate function names, if a service application needs to call the API that records callstack data, add _callstack to the section name. (If only the callstack parameter exists in this section, only one API is generated and only call stack data is collected.)
If both callstack and enablepmu are configured in a section, four APIs are generated.
One API records callstack and PMU data. One API records callstack data but does not record PMU data. One API records PMU data but does not record callstack data. The last API does not record callstack or PMU data.

To avoid duplicate function names:
- If a service application needs to invoke the API that records callstack and PMU data, add _enablepmu_callstack to the section name.
- If a service application needs to invoke the API that records only callstack data, add _callstack to the section name.
- If a service application needs to invoke the API that records only PMU data, add _enablepmu to the section name.

The preceding configuration rules do not take effect for the Tracer running on an x86 server.

Optimal Cache Size for Different Log Volumes

Assume the server has 128 CPU cores, a total of 250 GB memory, and higher than 99% of static CPU no-load rate, the optimal cache sizes are as follows:

When the service application starts 10 threads, each thread contains 10,000 logs, and each log is 100 bytes, the recommended cache size is 320 KB.
When the service application starts 10 threads, each thread contains 100,000 logs, and each log is 100 bytes, the recommended cache size is 320 KB.
When the service application starts 10 threads, each thread contains 1,000,000 logs, and each log is 100 bytes, the recommended cache size is 320 KB.

Example

View the functions supported by the code generation submodule:

1	./tracelog generator -h

Command output:

NAME
    tracelog generator - Run the command to parse the .ini configuration file and generate the needed header file and metadata file.
USAGE
    tracelog generator
    [-h | --help]
    [-l {0,1,2,3} | --log-level {0,1,2,3}]
    {-i <INI_FILE> | --input <INI_FILE>}
    [-o <OUTPUT_PATH> | --output <OUTPUT_PATH>]
DESCRIPTION
    The generated header file contains the corresponding API. You can use this header file for log development and the metadata file for log parsing.
OPTIONS
    -h, --help
        Get help information and exit.
    -l {0,1,2,3}, --log-level {0,1,2,3}
        Specify the print log level, 0(debug) | 1(info) | 2(warning) | 3(error).Default is 1(info).
    -o, --output
        Generated file directory, which defaults to the current directory. The name of the generated header file is the same as the name of the inputted .ini file.
    -i, --input
        Input .ini file. For details about how to write the .ini file, see the example.ini file in the current directory.

Parent topic: Tracer