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='internal_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('cmdline', CppOptional(CppString())), 65 C('arg_set_id', CppUint32()), 66 C('machine_id', CppOptional(CppTableId(MACHINE_TABLE))), 67 ], 68 wrapping_sql_view=WrappingSqlView(view_name='process',), 69 tabledoc=TableDoc( 70 doc='Contains information of processes seen during the trace', 71 group='Metadata', 72 skip_id_and_type=True, 73 columns={ 74 'upid': 75 ''' 76 Unique process id. This is != the OS pid. This is a 77 monotonic number associated to each process. The OS process 78 id (pid) cannot be used as primary key because tids and pids 79 are recycled by most kernels. 80 ''', 81 'pid': 82 ''' 83 The OS id for this process. Note: this is *not* unique 84 over the lifetime of the trace so cannot be used as a 85 primary key. Use |upid| instead. 86 ''', 87 'name': 88 ''' 89 The name of the process. Can be populated from many sources 90 (e.g. ftrace, /proc scraping, track event etc). 91 ''', 92 'start_ts': 93 ''' 94 The start timestamp of this process (if known). Is null 95 in most cases unless a process creation event is enabled 96 (e.g. task_newtask ftrace event on Linux/Android). 97 ''', 98 'end_ts': 99 ''' 100 The end timestamp of this process (if known). Is null in 101 most cases unless a process destruction event is enabled 102 (e.g. sched_process_free ftrace event on Linux/Android). 103 ''', 104 'parent_upid': 105 ColumnDoc( 106 ''' 107 The upid of the process which caused this process to be 108 spawned. 109 ''', 110 joinable='process.upid'), 111 'uid': 112 ColumnDoc( 113 'The Unix user id of the process.', 114 joinable='package_list.uid'), 115 'android_appid': 116 'Android appid of this process.', 117 'cmdline': 118 '/proc/cmdline for this process.', 119 'arg_set_id': 120 ColumnDoc( 121 'Extra args for this process.', joinable='args.arg_set_id'), 122 'machine_id': 123 ''' 124 Machine identifier, non-null for processes on a remote 125 machine. 126 ''', 127 })) 128 129THREAD_TABLE = Table( 130 python_module=__file__, 131 class_name='ThreadTable', 132 sql_name='internal_thread', 133 columns=[ 134 C('utid', Alias(underlying_column='id')), 135 C('tid', CppUint32()), 136 C('name', CppOptional(CppString())), 137 C('start_ts', CppOptional(CppInt64())), 138 C('end_ts', CppOptional(CppInt64())), 139 C('upid', CppOptional(CppTableId(PROCESS_TABLE))), 140 C('is_main_thread', CppOptional(CppUint32())), 141 C('machine_id', CppOptional(CppTableId(MACHINE_TABLE))), 142 ], 143 wrapping_sql_view=WrappingSqlView(view_name='thread',), 144 tabledoc=TableDoc( 145 doc='Contains information of threads seen during the trace', 146 group='Metadata', 147 skip_id_and_type=True, 148 columns={ 149 'utid': 150 ''' 151 Unique thread id. This is != the OS tid. This is a monotonic 152 number associated to each thread. The OS thread id (tid) 153 cannot be used as primary key because tids and pids are 154 recycled by most kernels. 155 ''', 156 'tid': 157 ''' 158 The OS id for this thread. Note: this is *not* unique over the 159 lifetime of the trace so cannot be used as a primary key. Use 160 |utid| instead. 161 ''', 162 'name': 163 ''' 164 The name of the thread. Can be populated from many sources 165 (e.g. ftrace, /proc scraping, track event etc). 166 ''', 167 'start_ts': 168 ''' 169 The start timestamp of this thread (if known). Is null in most 170 cases unless a thread creation event is enabled (e.g. 171 task_newtask ftrace event on Linux/Android). 172 ''', 173 'end_ts': 174 ''' 175 The end timestamp of this thread (if known). Is null in most 176 cases unless a thread destruction event is enabled (e.g. 177 sched_process_free ftrace event on Linux/Android). 178 ''', 179 'upid': 180 ColumnDoc( 181 'The process hosting this thread.', 182 joinable='process.upid'), 183 'is_main_thread': 184 ''' 185 Boolean indicating if this thread is the main thread 186 in the process. 187 ''', 188 'machine_id': 189 ''' 190 Machine identifier, non-null for threads on a remote machine. 191 ''', 192 })) 193 194CPU_TABLE = Table( 195 python_module=__file__, 196 class_name='CpuTable', 197 sql_name='__intrinsic_cpu', 198 columns=[ 199 C('cpu', CppOptional(CppUint32())), 200 C('cluster_id', CppUint32()), 201 C('processor', CppString()), 202 C('machine_id', CppOptional(CppTableId(MACHINE_TABLE))), 203 ], 204 tabledoc=TableDoc( 205 doc=''' 206 Contains information of processes seen during the trace 207 ''', 208 group='Misc', 209 columns={ 210 'cpu': 211 '''the index (0-based) of the CPU core on the device''', 212 'cluster_id': 213 '''the cluster id is shared by CPUs in 214the same cluster''', 215 'processor': 216 '''a string describing this core''', 217 'machine_id': 218 ''' 219 Machine identifier, non-null for CPUs on a remote machine. 220 ''', 221 })) 222 223RAW_TABLE = Table( 224 python_module=__file__, 225 class_name='RawTable', 226 sql_name='__intrinsic_raw', 227 columns=[ 228 C('ts', CppInt64(), flags=ColumnFlag.SORTED), 229 C('name', CppString()), 230 C('utid', CppTableId(THREAD_TABLE)), 231 C('arg_set_id', CppUint32()), 232 C('common_flags', CppUint32()), 233 C('ucpu', CppTableId(CPU_TABLE)) 234 ], 235 tabledoc=TableDoc( 236 doc=''' 237 Contains 'raw' events from the trace for some types of events. This 238 table only exists for debugging purposes and should not be relied on 239 in production usecases (i.e. metrics, standard library etc). 240 ''', 241 group='Events', 242 columns={ 243 'arg_set_id': 244 ColumnDoc( 245 'The set of key/value pairs associated with this event.', 246 joinable='args.arg_set_id'), 247 'ts': 248 'The timestamp of this event.', 249 'name': 250 ''' 251 The name of the event. For ftrace events, this will be the 252 ftrace event name. 253 ''', 254 'utid': 255 'The thread this event was emitted on.', 256 'common_flags': 257 ''' 258 Ftrace event flags for this event. Currently only emitted for 259 sched_waking events. 260 ''', 261 'ucpu': 262 ''' 263 The unique CPU indentifier. 264 ''', 265 })) 266 267FTRACE_EVENT_TABLE = Table( 268 python_module=__file__, 269 class_name='FtraceEventTable', 270 sql_name='__intrinsic_ftrace_event', 271 parent=RAW_TABLE, 272 columns=[], 273 tabledoc=TableDoc( 274 doc=''' 275 Contains all the ftrace events in the trace. This table exists only 276 for debugging purposes and should not be relied on in production 277 usecases (i.e. metrics, standard library etc). Note also that this 278 table might be empty if raw ftrace parsing has been disabled. 279 ''', 280 group='Events', 281 columns={})) 282 283ARG_TABLE = Table( 284 python_module=__file__, 285 class_name='ArgTable', 286 sql_name='internal_args', 287 columns=[ 288 C('arg_set_id', CppUint32(), flags=ColumnFlag.SORTED), 289 C('flat_key', CppString()), 290 C('key', CppString()), 291 C('int_value', CppOptional(CppInt64())), 292 C('string_value', CppOptional(CppString())), 293 C('real_value', CppOptional(CppDouble())), 294 C('value_type', CppString()), 295 ], 296 wrapping_sql_view=WrappingSqlView(view_name='args'), 297 tabledoc=TableDoc( 298 doc='''''', 299 group='Misc', 300 columns={ 301 'arg_set_id': '''''', 302 'flat_key': '''''', 303 'key': '''''', 304 'int_value': '''''', 305 'string_value': '''''', 306 'real_value': '''''', 307 'value_type': '''''' 308 })) 309 310METADATA_TABLE = Table( 311 python_module=__file__, 312 class_name='MetadataTable', 313 sql_name='metadata', 314 columns=[ 315 C('name', CppString()), 316 C('key_type', CppString()), 317 C('int_value', CppOptional(CppInt64())), 318 C('str_value', CppOptional(CppString())), 319 ], 320 tabledoc=TableDoc( 321 doc='''''', 322 group='Metadata', 323 columns={ 324 'name': '''''', 325 'key_type': '''''', 326 'int_value': '''''', 327 'str_value': '''''' 328 })) 329 330FILEDESCRIPTOR_TABLE = Table( 331 python_module=__file__, 332 class_name='FiledescriptorTable', 333 sql_name='filedescriptor', 334 columns=[ 335 C('ufd', CppInt64()), 336 C('fd', CppInt64()), 337 C('ts', CppOptional(CppInt64())), 338 C('upid', CppOptional(CppUint32())), 339 C('path', CppOptional(CppString())), 340 ], 341 tabledoc=TableDoc( 342 doc=''' 343 Contains information of filedescriptors collected during the trace 344 ''', 345 group='Metadata', 346 columns={ 347 'ufd': 348 '''Unique fd. This is != the OS fd. 349This is a monotonic number associated to each 350filedescriptor. The OS assigned fd cannot be used as 351primary key because fds are recycled by most kernels.''', 352 'fd': 353 '''The OS id for this process. Note: this is *not* 354unique over the lifetime of the trace so cannot be 355used as a primary key. Use |ufd| instead.''', 356 'ts': 357 '''The timestamp for when the fd was collected.''', 358 'upid': 359 ''' The upid of the process which 360opened the filedescriptor.''', 361 'path': 362 '''The path to the file or device backing the fd 363In case this was a socket the path will be the port 364number.''' 365 })) 366 367EXP_MISSING_CHROME_PROC_TABLE = Table( 368 python_module=__file__, 369 class_name='ExpMissingChromeProcTable', 370 sql_name='experimental_missing_chrome_processes', 371 columns=[ 372 C('upid', CppUint32()), 373 C('reliable_from', CppOptional(CppInt64())), 374 ], 375 tabledoc=TableDoc( 376 doc=''' 377 Experimental table, subject to arbitrary breaking changes. 378 ''', 379 group='Chrome', 380 columns={ 381 'upid': '''''', 382 'reliable_from': '''''' 383 })) 384 385CPU_FREQ_TABLE = Table( 386 python_module=__file__, 387 class_name='CpuFreqTable', 388 sql_name='__intrinsic_cpu_freq', 389 columns=[ 390 C('ucpu', CppTableId(CPU_TABLE)), 391 C('freq', CppUint32()), 392 ], 393 tabledoc=TableDoc( 394 doc='''''', group='Misc', columns={ 395 'ucpu': '''''', 396 'freq': '''''', 397 })) 398 399CLOCK_SNAPSHOT_TABLE = Table( 400 python_module=__file__, 401 class_name='ClockSnapshotTable', 402 sql_name='clock_snapshot', 403 columns=[ 404 C('ts', CppInt64()), 405 C('clock_id', CppInt64()), 406 C('clock_name', CppOptional(CppString())), 407 C('clock_value', CppInt64()), 408 C('snapshot_id', CppUint32()), 409 C('machine_id', CppOptional(CppTableId(MACHINE_TABLE))), 410 ], 411 tabledoc=TableDoc( 412 doc=''' 413 Contains all the mapping between clock snapshots and trace time. 414 415NOTE: this table is not sorted by timestamp; this is why we omit the 416sorted flag on the ts column. 417 ''', 418 group='Misc', 419 columns={ 420 'ts': 421 '''timestamp of the snapshot in trace time.''', 422 'clock_id': 423 '''id of the clock (corresponds to the id in the trace).''', 424 'clock_name': 425 '''the name of the clock for builtin clocks or null 426otherwise.''', 427 'clock_value': 428 '''timestamp of the snapshot in clock time.''', 429 'snapshot_id': 430 '''the index of this snapshot (only useful for debugging)''', 431 'machine_id': 432 ''' 433 Machine identifier, non-null for clock snapshots on a remote 434 machine. 435 ''', 436 })) 437 438# Keep this list sorted. 439ALL_TABLES = [ 440 ARG_TABLE, 441 CLOCK_SNAPSHOT_TABLE, 442 CPU_FREQ_TABLE, 443 CPU_TABLE, 444 EXP_MISSING_CHROME_PROC_TABLE, 445 FILEDESCRIPTOR_TABLE, 446 METADATA_TABLE, 447 PROCESS_TABLE, 448 RAW_TABLE, 449 THREAD_TABLE, 450 FTRACE_EVENT_TABLE, 451 MACHINE_TABLE, 452] 453