Narrative Builder

Jeli Part of PagerDuty

Narrative Builder is designed to help you discover, tell, and share the story of an incident. You'll write an executive summary, and develop a shareable visualization that you can center post-incident meetings around.

By using Narrative Builder you will:

  • Create a rich, detailed timeline of what happened during the incident and highlight key events.
  • Quickly and easily attach evidence to different parts of the timeline so that people who weren't there can follow along and learn from the incident.
  • Use event markers to indicate important moments of the incident.
  • Add descriptive notes that offer additional color and insight into the incident.
Narrative Builder

Narrative Builder

View the Narrative Timeline

To the view Narrative timeline, in the Jeli web app select your preferred opportunity and navigate to Report Narrative. The Narrative timeline displays all of an incident's event markers, along with their summaries, in chronological order, including its start and end times. Any event markers created without a set time will be displayed at the bottom.

You can open any of your event markers and see any attached supporting evidence, including the data source and timestamp. You can also see any attached notes, and edit them from the timeline view.

Narrative timeline with event markers and supporting evidence

Narrative timeline with event markers and supporting evidence

Timeline Zoom

Click-and-drag over your desired timeframe to zoom in on a particular part of the timeline. This is helpful if you'd like take a closer look at a point in time that:

  • Was particularly interesting.
  • Presented a red herring.
  • A key moment occurred.
  • Is critical to understanding the opportunity.

Click Reset zoom to go back to the default zoom level.

Reset zoom

Reset zoom

Build the Narrative

In the Jeli web app, select your preferred incident and click Go to Opportunity. Select the report's Narrative tab and click Edit narrative to enter the Builder view. This will be your main workspace as you identify incident events that you want to mark in your timeline.

Add a Detection event to the Narrative timeline

Add a Detection event to the Narrative timeline

Narrative Builder Components

The Builder view is split into two side-by-side panes with imported Slack channels and opportunity data on the left, and your working narrative timeline with event markers on the right.

Opportunity Data contains message logs from imported Slack channels with search and filter options to help you find the messages that marked different events throughout the incident.

Narrative Timeline is where you create and flesh out event markers, add summaries, notes and pull in supporting evidence from messages you find in opportunity data. The event markers you create build out the story of the incident and make up the visual timeline you see at the top of the presentation view.

๐Ÿ“˜

Tip

A helpful approach to narrative building is to think of the opportunity data as the pieces of a puzzle, and the narrative timeline as the canvas where you piece them together to form the bigger picture of the incident.

Opportunity Data and Narrative

Opportunity Data and Narrative

๐Ÿ‘

Narrative Builder Tutorial

Visit our Basic Investigation Tutorial to learn how to build your first Narrative.

Event Markers

Event markers are the points along your Narrative timeline that compose the story of your incident. There are four types of event markers:

  • Detection event markers tell the story about how participants detected the problem, for example automated notifications, responder notifications, customer reports, etc.
  • Diagnosis event markers are activities and messages where participants figured out what happened: tracking hypotheses, results from diagnostic tests, sharing dashboards and graphs, etc.
  • Repair event markers tell the story of how the problem was fixed or impact was minimized: brainstorming solutions, actions taken to repair, monitoring impacts of the fix, etc.
  • Key Moment event markers are flexible in definition and use. They help tell the story of the incident and denote various changes during incident response: planning external comms, starting a Zoom call, a new feature launch, etc.
Event markers

Event markers

To add an event marker use the + Add marker button in the top right hand corner:

Add an event marker

Add an event marker

Within each event marker you can add a summary, supporting evidence, notes, and the time of the event.

  • The Summary is where you will describe the nature of the event. What makes this important, or how does it change the story of the incident?
    • Note: This is the primary information that is displayed for each event marker in the timeline view.
  • Supporting Evidence is where you link relevant Slack messages to the marker. You can drag them from the opportunity data side of the screen directly into the marker. Supporting evidence for the earliest detection marker in your timeline might be an exchange of messages in a public engineering channel asking about a confusing dashboard, or a single ping in an alerts channel.
    • Drag and drop events directly into a narrative marker under Supporting Evidence in the Narrative Marker Details panel. This will add them as evidence within the marker.
Add supporting evidence

Add supporting evidence

  • 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.
Add supplemental evidence

Add supplemental evidence

  • Notes are your workspace to track questions, log insights, and gather thoughts. You can also edit notes from the timeline view, so that you can update or add new information while running interviews or a review meeting, for example.
Add notes

Add notes

  • The time can be set manually to the second. It is in 24-hour time in your local timezone. For each event you can set a single time, or add an end time to indicate the duration of the effort depicted by this event marker.
    • You can also check the box Use supporting event evidence to set time to automatically set a marker's timeframe using the time of your events under Supporting Evidence.
    • In the timeline, event markers are represented as a single point in time. If you add an end time to an event, it will show as a continuous line for the duration of the eventโ€™s timeframe. If you leave the time blank, the event marker will fall at the end of the narrative timeline and will not be a visual point on the timeline display.
arrative marker details: Detection

Narrative marker details: Detection

You can edit any of the fields in an event marker from the builder at any time. If you realize the supporting evidence and notes you have added suggest a different type of event marker, you can select a different one from the Marker Type dropdown.

Narrative marker details: Key moment

Narrative marker details: Key moment

When starting a new investigation, the narrative timeline will show two event markers by default: Opportunity Started and Opportunity Ended. These markers' times are set automatically based on the timeframe of the imported Slack messages, but can be customized. These events cannot be deleted or changed to other event marker types.

Search and Filter Opportunity Data

In the Opportunity Data section you can search for keywords and phrases, and filter your data by Participants, Reactions, Event Source, and Tags.

  • Participants are the responders who engaged in the imported Slack channels during the incident.
    • This is a helpful filter when you are looking for messages or conversations between specific individuals.
  • Reactions are the emojis or reactjis used in response to Slack messages.
    • Filtering by reaction can be a useful shorthand for finding relevant moments in the story of the incident. Every company has its own culture of Slack reactions; you may have common ones used to indicate important information, interesting questions, or celebrating successes.
  • Event Sources are the channels imported from Slack, and PagerDuty, if your account has that integration configured.
    • This filter is good to add to a search or other parameters to narrow results to a specific channel or to look for a distinct PagerDuty notification.
  • Tags are metadata you can add in the Event Data view to associate additional context with a message.
    • The Responder Joins tag is automatically added for each new participant who joined the Slack channel. This is helpful for getting a feel for how and when people joined the incident. All other tags are applied through the Event Data view in Jeli.

You can combine searching for a keyword or phrase with multiple of the filter types above to help narrow down your search results.

ilter search results

Filter search results

In addition to searching and filtering, if you imported multiple Slack channels, you toggle between messages from all channels (default) or individual channels.

As you search and filter to uncover the incident story, you may wish to review a message in its original context. There are two options for this: Jump to log and View in context:

  • Jump to log takes you to the message in the original message log, removing all applied searches or filters.
  • View in context opens the original message log on the left-hand side of the screen, preserving your search and filtered results on the right hand side of the screen.

Present Using Narrative Builder

Narrative Builder makes it easy to run your post-incident meeting.

By sharing your screen you can navigate the timeline view and talk through the markers that you've made, as well the supporting evidence.

You can also see your notes that you've made as part of each marker and update them on the screen as you learn new information from attendees, or uncover new questions or insights.

๐Ÿ“˜

Edit Notes

At this time, only one person can edit the notes section at a time.

Narrative Builder

Narrative Builder