Home | History | Annotate | Download | only in docs 
      1 # Perfetto trace config
      2 
      3 *** note
      4 **This doc is WIP**, stay tuned.
      5 <!-- TODO(primiano): write trace config doc. -->
      6 ***
      7 
      8 ![Trace Config](https://storage.googleapis.com/perfetto/markdown_img/trace-config.png)
      9 
     10 The [`TraceConfig`](/protos/perfetto/config/trace_config.proto) is an extensible
     11 protobuf message, sent by the consumer to the service, that defines:
     12 - The number and size of the trace buffer.
     13 - The duration of the trace.
     14 - [optionally] a file descriptor for the output trace and a periodic write
     15   interval. If omitted the trace is kept only in memory.  
     16 - The producers involved in the trace session.
     17 - The data sources involved in the trace session.
     18 - The configuration of each data source.
     19 - The crossbar mapping between each data source and the trace buffers.
     20 
     21 Each data source can create its own specialized schema for the config, like
     22 [this](/protos/perfetto/config/ftrace/ftrace_config.proto)
     23 
     24 See [`trace_config.proto`](/protos/perfetto/config/trace_config.proto) for more
     25 details.
     26 
     27 For convenience, a vulcanized trace config where all the nested protobuf
     28 sub-message definitions are squashed together is available in
     29 [`perfetto_config.proto`](/protos/perfetto/config/perfetto_config.proto).
     30 
     31 
     32 Specifying a custom trace config
     33 --------------------------------
     34 ```
     35 cat > /tmp/config.txpb <<EOF
     36 # This is a text-encoded protobuf for /protos/perfetto/config/trace_config.proto
     37 duration_ms: 10000
     38 
     39 # For long traces set the following variables. It will periodically drain the
     40 # trace buffers into the output file, allowing to save a trace larger than the
     41 # buffer size.
     42 write_into_file: true
     43 file_write_period_ms: 5000
     44 
     45 buffers {
     46   size_kb: 10240
     47 }
     48 
     49 data_sources {
     50   config {
     51     name: "linux.ftrace"
     52     target_buffer: 0
     53     ftrace_config {
     54       buffer_size_kb: 40 # Kernel ftrace buffer size.
     55       ftrace_events: "sched_switch"
     56       ftrace_events: "print"
     57     }
     58   }
     59 }
     60 
     61 data_sources {
     62   config {
     63     name: "linux.process_stats"
     64     target_buffer: 0
     65   }
     66 }
     67 EOF
     68 
     69 protoc=$(pwd)/out/android/gcc_like_host/protoc
     70 
     71 $protoc --encode=perfetto.protos.TraceConfig \
     72         -I$(pwd)/external/perfetto/protos \
     73         $(pwd)/external/perfetto/protos/perfetto/config/perfetto_config.proto \
     74         < /tmp/config.txpb \
     75         > /tmp/config.pb
     76 
     77 cat /tmp/config.pb | adb shell perfetto -c - -o /data/misc/perfetto-traces/trace.pb
     78 adb shell cat /data/misc/perfetto-traces/trace.pb > /tmp/trace.pb
     79 out/android/trace_to_text json < /tmp/trace.pb > /tmp/trace.json
     80 
     81 # The file can now be viewed in chrome://tracing
     82 ```
     83