Narrative Builder Tutorial

Jeli Part of PagerDuty

โฐ Time required: 20 mins to 1 hour

In this tutorial, you will learn how to prepare for an incident review meeting using the Narrative Builder. You will review your Slack transcript to create a Narrative timeline of your incident and prepare Questions you want to ask during the meeting. We will provide guidance on:

  • How to choose supporting evidence.
  • How to decide how many messages will fit in each marker.
  • What to include in the summary, time, and notes sections (including questions that can eventually go into the product).

๐Ÿ“˜

Import Data

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. The 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 that you spend some time creating your Narrative before your incident review meeting. We have seen that spending some time prepping helps with making the (expensive) meeting a productive one.

Choose Supporting Evidence

Step 1: Evaluate Messages

Go through your transcript line-by-line and ask yourself if each message is important in telling the story of the incident. You should also check to see if each message 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 the following questions:

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: Organize Messages Under a Narrative Marker

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. If multiple messages explain what is happening during that part of the story, they should be included as well.

Step 3: Add Supplemental Evidence

You can also add evidence from outside of Slack messages by clicking Add supplemental evidence. 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.

๐Ÿ“˜

Tip

As a rule of thumb, we recommend using multiple pieces of evidence under a single marker if you can summarize what is happening within two 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

  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.
  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. 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.

๐Ÿ“˜

Recommendations

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 more 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.

In the example above 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 menu next to their markers and select Edit, which will open up the Narrative Marker Details modal.

To delete an existing marker you can hover over the menu next to their markers and select 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.

Finish Your Narrative

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.