1# Copyright (C) 2022 The Android Open Source Project 2# 3# Licensed under the Apache License, Version 2.0 (the 'License'); 4# you may not use this file except in compliance with the License. 5# You may obtain a copy of the License at 6# 7# http://www.apache.org/licenses/LICENSE-2.0 8# 9# Unless required by applicable law or agreed to in writing, software 10# distributed under the License is distributed on an 'AS IS' BASIS, 11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12# See the License for the specific language governing permissions and 13# limitations under the License. 14"""Contains metadata tables for a wide range of usecases.""" 15 16from python.generators.trace_processor_table.public import Alias 17from python.generators.trace_processor_table.public import Column as C 18from python.generators.trace_processor_table.public import ColumnDoc 19from python.generators.trace_processor_table.public import ColumnFlag 20from python.generators.trace_processor_table.public import CppDouble 21from python.generators.trace_processor_table.public import CppInt64 22from python.generators.trace_processor_table.public import CppOptional 23from python.generators.trace_processor_table.public import CppString 24from python.generators.trace_processor_table.public import Table 25from python.generators.trace_processor_table.public import TableDoc 26from python.generators.trace_processor_table.public import CppTableId 27from python.generators.trace_processor_table.public import CppUint32 28from python.generators.trace_processor_table.public import CppSelfTableId 29from python.generators.trace_processor_table.public import WrappingSqlView 30 31MACHINE_TABLE = Table( 32 python_module=__file__, 33 class_name='MachineTable', 34 sql_name='machine', 35 columns=[ 36 C('raw_id', CppUint32()), 37 ], 38 tabledoc=TableDoc( 39 doc=''' 40 Contains raw machine_id of trace packets emitted from remote machines. 41 ''', 42 group='Metadata', 43 columns={ 44 'raw_id': 45 ''' 46 Raw machine identifier in the trace packet, non-zero for 47 remote machines. 48 ''' 49 })) 50 51PROCESS_TABLE = Table( 52 python_module=__file__, 53 class_name='ProcessTable', 54 sql_name='__intrinsic_process', 55 columns=[ 56 C('upid', Alias(underlying_column='id')), 57 C('pid', CppUint32()), 58 C('name', CppOptional(CppString())), 59 C('start_ts', CppOptional(CppInt64())), 60 C('end_ts', CppOptional(CppInt64())), 61 C('parent_upid', CppOptional(CppSelfTableId())), 62 C('uid', CppOptional(CppUint32())), 63 C('android_appid', CppOptional(CppUint32())), 64 C('android_user_id', CppOptional(CppUint32())), 65 C('cmdline', CppOptional(CppString())), 66 C('arg_set_id', CppOptional(CppUint32())), 67 C('machine_id', CppOptional(CppTableId(MACHINE_TABLE))), 68 ], 69 wrapping_sql_view=WrappingSqlView(view_name='process',), 70 tabledoc=TableDoc( 71 doc='Contains information of processes seen during the trace', 72 group='Metadata', 73 skip_id_and_type=True, 74 columns={ 75 'upid': 76 ''' 77 Unique process id. This is != the OS pid. This is a 78 monotonic number associated to each process. The OS process 79 id (pid) cannot be used as primary key because tids and pids 80 are recycled by most kernels. 81 ''', 82 'pid': 83 ''' 84 The OS id for this process. Note: this is *not* unique 85 over the lifetime of the trace so cannot be used as a 86 primary key. Use |upid| instead. 87 ''', 88 'name': 89 ''' 90 The name of the process. Can be populated from many sources 91 (e.g. ftrace, /proc scraping, track event etc). 92 ''', 93 'start_ts': 94 ''' 95 The start timestamp of this process (if known). Is null 96 in most cases unless a process creation event is enabled 97 (e.g. task_newtask ftrace event on Linux/Android). 98 ''', 99 'end_ts': 100 ''' 101 The end timestamp of this process (if known). Is null in 102 most cases unless a process destruction event is enabled 103 (e.g. sched_process_free ftrace event on Linux/Android). 104 ''', 105 'parent_upid': 106 ColumnDoc( 107 ''' 108 The upid of the process which caused this process to be 109 spawned. 110 ''', 111 joinable='process.upid'), 112 'uid': 113 ColumnDoc( 114 'The Unix user id of the process.', 115 joinable='package_list.uid'), 116 'android_appid': 117 'Android appid of this process.', 118 'android_user_id': 119 ''' 120 Android user id running the process. 121 Related to Android multi-user (not to be confused with the 122 unix uid) 123 ''', 124 'cmdline': 125 '/proc/cmdline for this process.', 126 'arg_set_id': 127 ColumnDoc( 128 'Extra args for this process.', joinable='args.arg_set_id'), 129 'machine_id': 130 ''' 131 Machine identifier, non-null for processes on a remote 132 machine. 133 ''', 134 })) 135 136THREAD_TABLE = Table( 137 python_module=__file__, 138 class_name='ThreadTable', 139 sql_name='__intrinsic_thread', 140 columns=[ 141 C('utid', Alias(underlying_column='id')), 142 C('tid', CppUint32()), 143 C('name', CppOptional(CppString())), 144 C('start_ts', CppOptional(CppInt64())), 145 C('end_ts', CppOptional(CppInt64())), 146 C('upid', CppOptional(CppTableId(PROCESS_TABLE))), 147 C('is_main_thread', CppOptional(CppUint32())), 148 C('is_idle', CppUint32()), 149 C('machine_id', CppOptional(CppTableId(MACHINE_TABLE))), 150 ], 151 wrapping_sql_view=WrappingSqlView(view_name='thread',), 152 tabledoc=TableDoc( 153 doc='Contains information of threads seen during the trace', 154 group='Metadata', 155 skip_id_and_type=True, 156 columns={ 157 'utid': 158 ''' 159 Unique thread id. This is != the OS tid. This is a monotonic 160 number associated to each thread. The OS thread id (tid) 161 cannot be used as primary key because tids and pids are 162 recycled by most kernels. 163 ''', 164 'tid': 165 ''' 166 The OS id for this thread. Note: this is *not* unique over the 167 lifetime of the trace so cannot be used as a primary key. Use 168 |utid| instead. 169 ''', 170 'name': 171 ''' 172 The name of the thread. Can be populated from many sources 173 (e.g. ftrace, /proc scraping, track event etc). 174 ''', 175 'start_ts': 176 ''' 177 The start timestamp of this thread (if known). Is null in most 178 cases unless a thread creation event is enabled (e.g. 179 task_newtask ftrace event on Linux/Android). 180 ''', 181 'end_ts': 182 ''' 183 The end timestamp of this thread (if known). Is null in most 184 cases unless a thread destruction event is enabled (e.g. 185 sched_process_free ftrace event on Linux/Android). 186 ''', 187 'upid': 188 ColumnDoc( 189 'The process hosting this thread.', 190 joinable='process.upid'), 191 'is_main_thread': 192 ''' 193 Boolean indicating if this thread is the main thread 194 in the process. 195 ''', 196 'is_idle': 197 ''' 198 Boolean indicating if this thread is an kernel idle task ( 199 pid = 0 on Linux). 200 201 ''', 202 'machine_id': 203 ''' 204 Machine identifier, non-null for threads on a remote machine. 205 ''', 206 })) 207 208CPU_TABLE = Table( 209 python_module=__file__, 210 class_name='CpuTable', 211 sql_name='__intrinsic_cpu', 212 columns=[ 213 C('cpu', CppOptional(CppUint32())), 214 C('cluster_id', CppUint32()), 215 C('processor', CppString()), 216 C('machine_id', CppOptional(CppTableId(MACHINE_TABLE))), 217 C('capacity', CppOptional(CppUint32())), 218 C('arg_set_id', CppOptional(CppUint32())), 219 ], 220 wrapping_sql_view=WrappingSqlView('cpu'), 221 tabledoc=TableDoc( 222 doc=''' 223 Contains information of processes seen during the trace 224 ''', 225 group='Misc', 226 columns={ 227 'cpu': 228 '''the index (0-based) of the CPU core on the device''', 229 'cluster_id': 230 '''the cluster id is shared by CPUs in the same cluster''', 231 'processor': 232 '''a string describing this core''', 233 'machine_id': 234 ''' 235 Machine identifier, non-null for CPUs on a remote machine. 236 ''', 237 'capacity': 238 ''' 239 Capacity of a CPU of a device, a metric which indicates the 240 relative performance of a CPU on a device 241 For details see: 242 https://www.kernel.org/doc/Documentation/devicetree/bindings/arm/cpu-capacity.txt 243 ''', 244 'arg_set_id': 245 '''Extra args associated with the CPU''', 246 })) 247 248CHROME_RAW_TABLE = Table( 249 python_module=__file__, 250 class_name='ChromeRawTable', 251 sql_name='__intrinsic_chrome_raw', 252 columns=[ 253 C('ts', CppInt64(), flags=ColumnFlag.SORTED), 254 C('name', CppString()), 255 C('utid', CppTableId(THREAD_TABLE)), 256 C('arg_set_id', CppUint32()), 257 ]) 258 259FTRACE_EVENT_TABLE = Table( 260 python_module=__file__, 261 class_name='FtraceEventTable', 262 sql_name='__intrinsic_ftrace_event', 263 columns=[ 264 C('ts', CppInt64(), flags=ColumnFlag.SORTED), 265 C('name', CppString()), 266 C('utid', CppTableId(THREAD_TABLE)), 267 C('arg_set_id', CppUint32()), 268 C('common_flags', CppUint32()), 269 C('ucpu', CppTableId(CPU_TABLE)), 270 ], 271 wrapping_sql_view=WrappingSqlView('ftrace_event'), 272 tabledoc=TableDoc( 273 doc=''' 274 Contains all the ftrace events in the trace. This table exists only 275 for debugging purposes and should not be relied on in production 276 usecases (i.e. metrics, standard library etc). Note also that this 277 table might be empty if raw ftrace parsing has been disabled. 278 ''', 279 group='Events', 280 columns={ 281 'arg_set_id': 282 ColumnDoc( 283 'The set of key/value pairs associated with this event.', 284 joinable='args.arg_set_id'), 285 'ts': 286 'The timestamp of this event.', 287 'name': 288 ''' 289 The name of the event. For ftrace events, this will be the 290 ftrace event name. 291 ''', 292 'utid': 293 'The thread this event was emitted on.', 294 'common_flags': 295 ''' 296 Ftrace event flags for this event. Currently only emitted for 297 sched_waking events. 298 ''', 299 'ucpu': 300 ''' 301 The unique CPU indentifier. 302 ''', 303 })) 304 305ARG_TABLE = Table( 306 python_module=__file__, 307 class_name='ArgTable', 308 sql_name='__intrinsic_args', 309 columns=[ 310 C('arg_set_id', 311 CppUint32(), 312 flags=ColumnFlag.SORTED | ColumnFlag.SET_ID), 313 C('flat_key', CppString()), 314 C('key', CppString()), 315 C('int_value', CppOptional(CppInt64())), 316 C('string_value', CppOptional(CppString())), 317 C('real_value', CppOptional(CppDouble())), 318 C('value_type', CppString()), 319 ], 320 wrapping_sql_view=WrappingSqlView(view_name='args'), 321 tabledoc=TableDoc( 322 doc='''''', 323 group='Misc', 324 columns={ 325 'arg_set_id': '''''', 326 'flat_key': '''''', 327 'key': '''''', 328 'int_value': '''''', 329 'string_value': '''''', 330 'real_value': '''''', 331 'value_type': '''''' 332 })) 333 334METADATA_TABLE = Table( 335 python_module=__file__, 336 class_name='MetadataTable', 337 sql_name='metadata', 338 columns=[ 339 C('name', CppString()), 340 C('key_type', CppString()), 341 C('int_value', CppOptional(CppInt64())), 342 C('str_value', CppOptional(CppString())), 343 ], 344 tabledoc=TableDoc( 345 doc='''''', 346 group='Metadata', 347 columns={ 348 'name': '''''', 349 'key_type': '''''', 350 'int_value': '''''', 351 'str_value': '''''' 352 })) 353 354FILEDESCRIPTOR_TABLE = Table( 355 python_module=__file__, 356 class_name='FiledescriptorTable', 357 sql_name='filedescriptor', 358 columns=[ 359 C('ufd', CppInt64()), 360 C('fd', CppInt64()), 361 C('ts', CppOptional(CppInt64())), 362 C('upid', CppOptional(CppUint32())), 363 C('path', CppOptional(CppString())), 364 ], 365 tabledoc=TableDoc( 366 doc=''' 367 Contains information of filedescriptors collected during the trace 368 ''', 369 group='Metadata', 370 columns={ 371 'ufd': 372 '''Unique fd. This is != the OS fd. 373This is a monotonic number associated to each 374filedescriptor. The OS assigned fd cannot be used as 375primary key because fds are recycled by most kernels.''', 376 'fd': 377 '''The OS id for this process. Note: this is *not* 378unique over the lifetime of the trace so cannot be 379used as a primary key. Use |ufd| instead.''', 380 'ts': 381 '''The timestamp for when the fd was collected.''', 382 'upid': 383 ''' The upid of the process which 384opened the filedescriptor.''', 385 'path': 386 '''The path to the file or device backing the fd 387In case this was a socket the path will be the port 388number.''' 389 })) 390 391EXP_MISSING_CHROME_PROC_TABLE = Table( 392 python_module=__file__, 393 class_name='ExpMissingChromeProcTable', 394 sql_name='experimental_missing_chrome_processes', 395 columns=[ 396 C('upid', CppUint32()), 397 C('reliable_from', CppOptional(CppInt64())), 398 ], 399 tabledoc=TableDoc( 400 doc=''' 401 Experimental table, subject to arbitrary breaking changes. 402 ''', 403 group='Chrome', 404 columns={ 405 'upid': '''''', 406 'reliable_from': '''''' 407 })) 408 409CPU_FREQ_TABLE = Table( 410 python_module=__file__, 411 class_name='CpuFreqTable', 412 sql_name='__intrinsic_cpu_freq', 413 columns=[ 414 C('ucpu', CppTableId(CPU_TABLE)), 415 C('freq', CppUint32()), 416 ], 417 wrapping_sql_view=WrappingSqlView('cpu_freq'), 418 tabledoc=TableDoc( 419 doc='''''', group='Misc', columns={ 420 'ucpu': '''''', 421 'freq': '''''', 422 })) 423 424CLOCK_SNAPSHOT_TABLE = Table( 425 python_module=__file__, 426 class_name='ClockSnapshotTable', 427 sql_name='clock_snapshot', 428 columns=[ 429 C('ts', CppInt64()), 430 C('clock_id', CppInt64()), 431 C('clock_name', CppOptional(CppString())), 432 C('clock_value', CppInt64()), 433 C('snapshot_id', CppUint32()), 434 C('machine_id', CppOptional(CppTableId(MACHINE_TABLE))), 435 ], 436 tabledoc=TableDoc( 437 doc=''' 438 Contains all the mapping between clock snapshots and trace time. 439 440NOTE: this table is not sorted by timestamp; this is why we omit the 441sorted flag on the ts column. 442 ''', 443 group='Misc', 444 columns={ 445 'ts': 446 '''timestamp of the snapshot in trace time.''', 447 'clock_id': 448 '''id of the clock (corresponds to the id in the trace).''', 449 'clock_name': 450 '''the name of the clock for builtin clocks or null 451otherwise.''', 452 'clock_value': 453 '''timestamp of the snapshot in clock time.''', 454 'snapshot_id': 455 '''the index of this snapshot (only useful for debugging)''', 456 'machine_id': 457 ''' 458 Machine identifier, non-null for clock snapshots on a remote 459 machine. 460 ''', 461 })) 462 463TRACE_FILE_TABLE = Table( 464 python_module=__file__, 465 class_name='TraceFileTable', 466 sql_name='__intrinsic_trace_file', 467 columns=[ 468 C('parent_id', CppOptional(CppSelfTableId())), 469 C('name', CppOptional(CppString())), 470 C('size', CppInt64()), 471 C('trace_type', CppString()), 472 C('processing_order', CppOptional(CppInt64())), 473 ], 474 wrapping_sql_view=WrappingSqlView('trace_file'), 475 tabledoc=TableDoc( 476 doc=''' 477 Metadata related to the trace file parsed. Note the order in which 478 the files appear in this table corresponds to the order in which 479 they are read and sent to the tokenization stage. 480 ''', 481 group='Misc', 482 columns={ 483 'parent_id': 484 ''' 485 Parent file. E.g. files contained in a zip file will point to 486 the zip file. 487 ''', 488 'name': 489 '''File name, if known, NULL otherwise''', 490 'size': 491 '''Size in bytes''', 492 'trace_type': 493 '''Trace type''', 494 'processing_order': 495 '''In which order where the files were processed.''', 496 })) 497 498# Keep this list sorted. 499ALL_TABLES = [ 500 ARG_TABLE, 501 CHROME_RAW_TABLE, 502 CLOCK_SNAPSHOT_TABLE, 503 CPU_FREQ_TABLE, 504 CPU_TABLE, 505 EXP_MISSING_CHROME_PROC_TABLE, 506 FILEDESCRIPTOR_TABLE, 507 FTRACE_EVENT_TABLE, 508 MACHINE_TABLE, 509 METADATA_TABLE, 510 PROCESS_TABLE, 511 THREAD_TABLE, 512 TRACE_FILE_TABLE, 513] 514