1620595 - [docs] document adding crash annotations

Status: RESOLVED FIXED

(Socorro :: General, task, P2)

Description

[Will Kahn-Greene [:willkg] ET needinfo? me]

There's no good documentation covering how to add crash annotations to crash reports. The process differs a bit from product to product, but some of the steps are the same across all products.

We should document how to add crash annotations. Initially, let's stick it in the Socorro docs, but we'll likely want to move it somewhere else.

Comment 1

[Will Kahn-Greene [:willkg] ET needinfo? me]

Maybe something like this?:

1. Point to CrashAnnotations.yml
   1. new annotations should have names and not change the meaning of existing annotations
   2. new annotations should get documented in that file
2. new annotations need to undergo data collection review: https://wiki.mozilla.org/Firefox/Data_Collection
3. new annotations should get an r+ from Socorro engineers less so we can gate and more so we can advise
4. need a bug against Socorro for any of the following additional work:
   1. make annotation public
   2. make annotation searchable
   3. make annotation aggregatable

I don't know how to add the annotation to the export to Telemetry so it shows up in socorro_crash dataset.

Comment 2

[Will Kahn-Greene [:willkg] ET needinfo? me]

Gabriele: Does the above look right? What's it missing from your perspective? Would we want to talk about how adding new annotations gets implemented?

Comment 3

[Gabriele Svelto [:gsvelto]]

Yes, it might be worth mentioning that new annotations don't go in crash pings by default. To send them alongside a crash ping one must add ping: true to the annotation and mention it in the data review request.

Comment 4

[Will Kahn-Greene [:willkg] ET needinfo? me]

Attachment: pr 5349: bug 1620595: add annotations documentation

Comment 5

[Will Kahn-Greene [:willkg] ET needinfo? me]

willkg merged PR #5349: "bug 1620595: add annotations documentation" in 5382173.

Marking as FIXED.