Narrative Builder Tutorial
⏰ Time required: 20 mins to 1 hour
This document explains how to choose supporting evidence, how to decide how many messages will fit in each marker, and what to include in the summary, time, and notes sections (including questions that can eventually go into the product).
You've had an incident; now it's time to use Jeli to make it easier to prepare for your incident review meeting. In this tutorial you will learn how to review your Slack transcript to create a Narrative timeline of your incident and prepare Questions you want to ask during the meeting.
📣 If you haven’t already, go to Slack to import your data into Jeli using the /jeli import command to import additional Slack channels.
Narrative Builder view
Jeli’s Narrative Builder makes it easy to tell the story of how your incident happened while taking into account multiple points of view. Narrative Builder allows you to use the primary data as evidence for the building blocks of your narrative, this allows for a blame-aware analysis of the incident that looks at what actually happened (rather than focusing on counterfactuals).
🔥TIP: We recommend you spend some time before your Incident Review Meeting creating your Narrative. We have seen that spending some time prepping helps with making the (expensive) meeting a productive one.
Choose supporting evidence
Step 1) Go through your transcript line by line and ask yourself if each message is important in telling the story of the incident and if it fits within one of the marker types: Detection, Diagnosis, Repair, and Key Moment. If so, choose the marker and bring the message in as Supporting Evidence.
🔥TIP: It might be helpful to ask yourself: Does this message help explain how we found out we were in an incident, how we realized what the problem was or wasn’t, how we worked towards resolution, or how people interacted with each other and the problem?
Step 2) You may include multiple pieces of evidence under the same marker when they all relate to the same point.
🔥TIP: When choosing a narrative marker, read the messages around it, and if multiple messages explain what is happening during that part of the story they should be included as well.
Step 3) You can also add evidence from outside of Slack messages by clicking the "Add supplemental evidence" button. Here you can add images, text, and links to add context to the story of the incident. This might be screenshots of graphs, links to a specific query, or a copy and paste of relevant logs.
📣 As a rule of thumb we recommend using multiple pieces of evidence under a single marker if you can summarize what is happening within 2 sentences. Any more is a signal that you may want to break it out into separate markers. For example: A conversation about a team deciding to revert a change may include multiple messages as supporting evidence under the same Repair Marker.
Update your marker details
Step 1) After you’ve added your supporting evidence you may update the timing fields. The start time will update automatically with the timestamp of the first message. If you’ve added multiple pieces of evidence you can add the end time here as well.
Step 2) Update the summary field with a couple of sentences describing what is happening in the supporting evidence. For example: “SREs and Software Engineers decide to move forward and revert the change made earlier in the day”
🔥TIP: We recommend using plain words as if you are telling the story of what happened to a coworker or in front of your incident review meeting.
Add additional notes
We suggest you use the notes section to ask any question you have based on the supporting evidence.
🔥TIP: Even if you think you know the answer, if something is unclear it is helpful to ask it during the review meeting so others can learn from it.
🔥TIP: A few possible questions to ask depending on the marker type are:
For Detection:
How were we alerted? Where did we see this alerting and why was this brought to our attention?
Who knew at the beginning and how did they find out?
Who did they bring in and how did they know to do this?
What background information did they have on this topic?
For Diagnosis:
What were folks looking at and why?
What did the problem mean? What was the impact?
What did people think was happening?
What did they try to do? What tools did they use for this?
How did they communicate this with each other?
For Repair:
What were some possible solutions to the issue
How did folks arrive at this solution? What constraints did they have?
How did they confirm if the solution worked or didn’t work?
For Key Moment:
How did responders collaborate?
Was anything confusing?
Did the communication methods change?
Did they share information with outside parties?
Did people learn something new?
Add more markers to help tell your story
You can choose as many markers as you need to tell your story, you do not have to go in a linear detection-diagnosis-repair manner either. Often incidents will jump back stages as information becomes available.
For example, we may realize halfway through the repair that there is another component impacted and we need to reach out to a new set of folks.
Here is an example where we have annotated the rich insights that the markers highlight.
Edit and delete existing markers
To edit an existing marker you can hover over the three dots next to their markers and click “Edit” which will open up the Narrative Marker Details modal.
To delete an existing marker you can hover over the three dots next to their markers and click “Delete”.
Opportunity Start and Opportunity End Time
The Opportunity Start and End Times are automatically generated based on the first channel ingested into the Opportunity. To change this information, you can choose the markers and edit them as necessary.
Finishing
Once your Narrative is complete you may use it in the next step of your Incident Analysis process, we recommend turning it into your agenda for your review meeting as explained in the Basic Investigation Tutorial.
