Skip to content

Commit 20685b9

Browse files
al45tairal45tair
committed
[Docs] Update backtracing documentation.
Added documentation for the JSON output. rdar://121430255
1 parent bc2722e commit 20685b9

File tree

1 file changed

+189
-0
lines changed

1 file changed

+189
-0
lines changed

‎docs/Backtracing.rst‎

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -92,9 +92,17 @@ follows:
9292
| | | only has effect on platforms that have a symbol |
9393
| | | cache that can be controlled by the runtime. |
9494
+-----------------+---------+--------------------------------------------------+
95+
| format | text | Set to ``json`` to output JSON crash logs rather |
96+
| | | than plain text. |
97+
+-----------------+---------+--------------------------------------------------+
9598
| output-to | stdout | Set to ``stderr`` to send the backtrace to the |
9699
| | | standard error instead of standard output. This |
97100
| | | may be useful in some CI systems. |
101+
| | | |
102+
| | | You may also specify a path; if this points at a |
103+
| | | directory, the backtracer will generate unique |
104+
| | | filenames within that directory. Otherwise it |
105+
| | | is assumed to be a filename. |
98106
+-----------------+---------+--------------------------------------------------+
99107
| symbolicate | full | Options are ``full``, ``fast``, or ``off``. |
100108
| | | Full means to look up source locations and |
@@ -334,3 +342,184 @@ large number of frames in a much smaller space than would otherwise be possible.
334342
Similarly, where we need to store address to image mappings, we
335343
use :download:`Compact ImageMap Format <CompactImageMapFormat.md>` to minimise
336344
storage requirements.
345+
346+
JSON Crash Logs
347+
---------------
348+
349+
JSON crash logs are a structured crash log format that the backtracer is able
350+
to output. Note that addresses are represented in this format as hexadecimal
351+
strings, rather than as numbers, in order to avoid representational issues.
352+
Additionally, boolean fields that are ``false``, as well as fields whose
353+
values are unknown or empty, will normally be completely omitted to save space.
354+
355+
JSON crash logs will always contain the following top level fields:
356+
357+
+-------------------+--------------------------------------------------------+
358+
| Field | Value |
359+
+===================+========================================================+
360+
| timestamp | An ISO-8601 formatted timestamp, as a string. |
361+
+-------------------+--------------------------------------------------------+
362+
| kind | The string ``crashReport``. |
363+
+-------------------+--------------------------------------------------------+
364+
| description | A textual description of the crash or runtime failure. |
365+
+-------------------+--------------------------------------------------------+
366+
| faultAddress | The fault address associated with the crash. |
367+
+-------------------+--------------------------------------------------------+
368+
| platform | A string describing the platform; the first token |
369+
| | identifies the platform itself and is followed by |
370+
| | platform specific version information. |
371+
| | |
372+
| | e.g. "macOS 13.0 (22A380)", |
373+
| | "linux (Ubuntu 22.04.5 LTS)" |
374+
+-------------------+--------------------------------------------------------+
375+
| architecture | The name of the processor architecture for this crash. |
376+
+-------------------+--------------------------------------------------------+
377+
378+
These will be followed by some or all of the following, according to the
379+
backtracer settings:
380+
381+
+-------------------+--------------------------------------------------------+
382+
| Field | Value |
383+
+===================+========================================================+
384+
| threads | An array of thread record, one for each thread (if the |
385+
| | backtracer is set to give backtraces for all threads). |
386+
+-------------------+--------------------------------------------------------+
387+
| crashedThread | A single thread record for the crashing thread (if the |
388+
| | backtracer is set to give a backtrace only for the |
389+
| | crashed thread). |
390+
+-------------------+--------------------------------------------------------+
391+
| registers | A dictionary containing the register contents on the |
392+
| | crashed thread (if set to give registers for only the |
393+
| | crashed thread). |
394+
| | |
395+
| | The dictionary is keyed by architecture specific |
396+
| | register name; values are given as hexadecimal |
397+
| | strings. |
398+
+-------------------+--------------------------------------------------------+
399+
| capturedMemory | A dictionary containing captured memory contents, if |
400+
| | any. This will not be present if the ``sanitize`` |
401+
| | setting is enabled, or if no data was captured. |
402+
| | |
403+
| | The dictionary is keyed by hexadecimal addresses, as |
404+
| | strings; values are also hexadecimal strings. |
405+
+-------------------+--------------------------------------------------------+
406+
| omittedImages | If ``images`` is set to ``mentioned``, this is an |
407+
| | integer giving the number of images whose details were |
408+
| | omitted from the crash log. |
409+
+-------------------+--------------------------------------------------------+
410+
| images | Unless ``images`` is ``none``, an array of records |
411+
| | describing the loaded images in the crashed process. |
412+
+-------------------+--------------------------------------------------------+
413+
| backtraceTime | The time taken to generate the crash report, in |
414+
| | seconds. |
415+
+-------------------+--------------------------------------------------------+
416+
417+
Thread Records
418+
^^^^^^^^^^^^^^
419+
420+
A thread record is a dictionary with the following fields:
421+
422+
+-------------------+--------------------------------------------------------+
423+
| Field | Value |
424+
+===================+========================================================+
425+
| name | The name of the thread. Omitted if no name. |
426+
+-------------------+--------------------------------------------------------+
427+
| crashed | ``true`` if the thread is the one that crashed, |
428+
| | omitted otherwise. |
429+
+-------------------+--------------------------------------------------------+
430+
| registers | If ``registers`` is set to ``all``, the registers for |
431+
| | the thread (see above for the format). |
432+
+-------------------+--------------------------------------------------------+
433+
| frames | An array of frames forming the backtrace for the |
434+
| | thread. |
435+
+-------------------+--------------------------------------------------------+
436+
437+
Each frame in the backtrace is described by a dictionary containing the
438+
following fields:
439+
440+
+-------------------+--------------------------------------------------------+
441+
| Field | Value |
442+
+===================+========================================================+
443+
| kind | ``programCounter`` if the frame address is a directly |
444+
| | captured program counter/instruction pointer. |
445+
| | |
446+
| | ``returnAddress`` if the frame address is a return |
447+
| | address. |
448+
| | |
449+
| | ``asyncResumePoint`` if the frame address is a |
450+
| | resumption point in an ``async`` function. |
451+
| | |
452+
| | ``omittedFrames`` if this is a frame omission record. |
453+
| | |
454+
| | ``truncated`` to indicate that the backtrace is |
455+
| | truncated at this point and that more frames were |
456+
| | available but not captured. |
457+
+-------------------+--------------------------------------------------------+
458+
| address | The frame address as a string (for records containing |
459+
| | an address). |
460+
+-------------------+--------------------------------------------------------+
461+
| count | The number of frames omitted at this point in the |
462+
| | backtrace (``omittedFrames`` only). |
463+
+-------------------+--------------------------------------------------------+
464+
465+
If the backtrace is symbolicated, the frame record may also contain the
466+
following additional information:
467+
468+
+-------------------+--------------------------------------------------------+
469+
| Field | Value |
470+
+===================+========================================================+
471+
| inlined | ``true`` if this frame is inlined, omitted otherwise. |
472+
+-------------------+--------------------------------------------------------+
473+
| runtimeFailure | ``true`` if this frame represents a Swift runtime |
474+
| | failure, omitted otherwise. |
475+
+-------------------+--------------------------------------------------------+
476+
| thunk | ``true`` if this frame is a compiler-generated thunk |
477+
| | function, omitted otherwise. |
478+
+-------------------+--------------------------------------------------------+
479+
| system | ``true`` if this frame is a system frame, omitted |
480+
| | otherwise. |
481+
+-------------------+--------------------------------------------------------+
482+
483+
If symbol lookup succeeded for the frame address, the following additional
484+
fields will be present:
485+
486+
+-------------------+--------------------------------------------------------+
487+
| Field | Value |
488+
+===================+========================================================+
489+
| symbol | The mangled name of the symbol corresponding to the |
490+
| | frame address. |
491+
+-------------------+--------------------------------------------------------+
492+
| offset | The offset from the symbol to the frame address. |
493+
+-------------------+--------------------------------------------------------+
494+
| description | If demangling is enabled, a human readable description |
495+
| | of the frame address, otherwise omitted. |
496+
+-------------------+--------------------------------------------------------+
497+
| image | The name of the image in which the symbol was found; |
498+
| | omitted if no corresponding image exists. |
499+
+-------------------+--------------------------------------------------------+
500+
| sourceLocation | If the source location of the symbol is known, a |
501+
| | dictionary containing ``file``, ``line`` and |
502+
| | ``column`` keys that identify the location of the |
503+
| | symbol in the source files. |
504+
+-------------------+--------------------------------------------------------+
505+
506+
Image Records
507+
^^^^^^^^^^^^^
508+
509+
An image record is a dictionary with the following fields:
510+
511+
+-------------------+--------------------------------------------------------+
512+
| Field | Value |
513+
+===================+========================================================+
514+
| name | The name of the image (omitted if not known). |
515+
+-------------------+--------------------------------------------------------+
516+
| buildId | The build ID (aka unique ID) of the image (omitted if |
517+
| | not known). |
518+
+-------------------+--------------------------------------------------------+
519+
| path | The path to the image (omitted if not known). |
520+
+-------------------+--------------------------------------------------------+
521+
| baseAddress | The base address of the image text, as a hexadecimal |
522+
| | string. |
523+
+-------------------+--------------------------------------------------------+
524+
| endOfText | The end of the image text, as a hexadecimal string. |
525+
+-------------------+--------------------------------------------------------+

0 commit comments

Comments
 (0)