You copied the Doc URL to your clipboard.

How do I use the attributes in the events-ftrace.xml file

Article ID: 162271352

Published date: 13 Feb 2018

Last updated: -

Applies to: Streamline Performance Analyzer

Problem/Question

How do I use the attributes in the events-ftrace.xml file?

Scenario

I am not sure about how to use the attributes in events-ftrace.xml. Can you provide detailed usage information of the attributes in the events-ftrace.xml file?

Answer

The usage information of some key attributes in events-ftrace.xml file is listed below:

counter=”ftrace_xxx

The attribute specifies the name of the event. You can define the name yourself. ftrace_xxx does not have to be the same as the ftrace event name in tracing/events/. However, the name must start with ftrace_ and be unique.

title=”xxx”

The attribute defines the title shown in the Timeline view. You can define title yourself.

name=“xxx”

The attribute defines the name shown in the TimeLine view. You can define name yourself.

description=”xxx”

The attribute describes the meaning of the event.

tracepoint=”xxx”

The attribute specifies the name of the tracepoint. The name must match the ftrace event name in /sys/kernel/debug/tracing/events/.

For example:

  • tracepoint="kmem/kmalloc" specifies the trace event /sys/kernel/debug/tracing/events/kmem/kmalloc.

  • tracepoint="ext4/ext4_da_write_end" specifies the trace event /sys/kernel/debug/tracing/events/ext4/ext4_da_write_end.

class=”xxx”

The attribute is not specific to ftrace events.

Use one of the following values for the class attribute:

  • delta, which is used for values that increment or are accumulated over time, such as hardware performance counters. The exact time when the data occurs is unknown, so the data is interpolated between timestamps.

  • Incident, which is the same as delta except the exact time is known. Therefore, no interpolation is calculated and is used for counters, such as software trace.

  • absolute, which is used for singular or impulse values, such as system memory used.

  • activity, which is used with scheduler trace data, such as CPU activity. The default value is delta. This attribute is optional.

For more information about this attribute, see the protocol documentation. Normally, you can find it in C:\Program Files\DS-5 v5.x.x\sw\streamline\protocol\gator.

regex=”xxx

This attribute can be used to count the number of times an event occurs or extract a number from an event. For example, a trace message is as follows:

```

hello: 5

bye: 2

hello: 1

hello: 3

bye: 9

hello: 56

```

Regex=`^hello:` counts the event by returning 1,0,1,1,0,1, while Regex=`^hello: ([0-9]+)$` returns 5,0,1,3,0,56. In the result, 0 indicates that the event is not counted.

arg=”xxxx”

This attribute applies to only tracepoints. When setting the arg attribute, you must match the arg name with the format.

An example of a trace event is as follows:

<event counter="ftrace_ext4_ext4_da_write" title="Ext4" name="ext4_da_write" regex="^ext4_da_write_end:.* len ([0-9]+) " tracepoint="ext4/ext4_da_write_end" arg="len" class="incident" description="Number of bytes written to an ext4 filesystem"/>

An example of the event format on a Hikey960 board is as follows:

hikey960:/sys/kernel/debug/tracing/events/ext4/ext4_da_write_end # cat format

name: ext4_da_write_end

ID: 748

format:

field:unsigned short common_type; offset:0; size:2; signed:0;

field:unsigned char common_flags; offset:2; size:1; signed:0;

field:unsigned char common_preempt_count; offset:3; size:1; signed:0;

field:int common_pid; offset:4; size:4; signed:1;

field:dev_t dev; offset:8; size:4; signed:0;

field:ino_t ino; offset:16; size:8; signed:0;

field:loff_t pos; offset:24; size:8; signed:1;

field:unsigned int len; offset:32; size:4; signed:0;

field:unsigned int copied; offset:36; size:4; signed:0;

print fmt: "dev %d,%d ino %lu pos %lld len %u copied %u", ((unsigned int) ((REC->dev) >> 20)), ((unsigned int) ((REC->de

v) & ((1U << 20) - 1))), (unsigned long) REC->ino, REC->pos, REC->len, REC->copied

In the previous example, if you want to extract the value of len, you must assign arg with the name len. It means that arg comes from the TP_STRUCT_entry part of the TRACE_EVENT macro, while regex for tracepoints must be based on the TP_printk part of the TRACE_EVENT macro. To reference examples, see samples/trace_events/trace-events-sample.h in the kernel source.

To learn how these attributes are defined for existing tracepoints, see /sys/kernel/debug/tracing/events/*/*/format file. The arg can be determined from “format:” and regex can be determined from “print fmt:”.

Choose arg or regex depending on the capture method you use. Gator collects tracepoints in three different ways:

  • Kernel space gator without Use more efficient Ftrace collection ticked, as shown in figure 1: This reads /sys/kernel/debug/tracing/trace_pipe, which is in textual format. Streamline parses the file using regex to match the correct counter. If regex has a group (for example [0-9]+), it uses the group to extract the value. Otherwise, Streamline uses a value of 1.

Figure 1 Capture and Analysis Options


  • Kernel space gator with Use more efficient Ftrace collection ticked: This reads /sys/kernel/debug/tracing/cpu*/trace_pipe_raw, which is in binary format. Streamline parses the file and uses arg to know which value to take from a tracepoint. If arg is missing, Streamline uses a value of 1.

  • Use User space gator and the tracepoint attribute: This uses the Perf Application Program Interfaces (APIs) to collect the tracepoint in binary form. Streamline parses the Perf data and uses arg to know which value to take from a tracepoint. If arg is missing, Streamline uses a value of 1.

For example, if you check the counting ftrace counters section in events-ftrace.xml, you can find that there is no group in the regex and arg is not present. The reason is that Streamline only counts the event and does not extract any value from it.

If you check ftrace_kmem_kmalloc in events-ftrace.xml, you can find that the number of bytes allocated must be extracted from the trace.

Display the file /sys/kernel/debug/tracing/events/kmem/kmalloc/format, and:

  • Check the content under "format:", and you can find that the name of the field is bytes_alloc. That is what arg needs to be.

  • Check the content under "print fmt:", and you can find that ".*bytes_alloc=([0-9]+)" matches the value. However, remember that the name of the tracepoint is also printed first, so regex must be "^kmalloc:.* bytes_alloc=([0-9]+)". Otherwise, you also count any other tracepoint with bytes_alloc like kmalloc_node.

Workaround

N/A

Example

N/A

Related Information

N/A

Was this page helpful? Yes No