Work with Lightrun Debug Runbooks🔗

Overview🔗

Debug Runbooks in Lightrun are structured, repeatable sets of diagnostic steps that can be executed during an incident to capture the right code-level evidence in real time. They remove guesswork and make it possible to standardize incident response, ensuring that crucial information is collected before it’s lost. Instead of relying on ad-hoc logging or developers manually reproducing issues after the fact, Debug Runbooks provide a predefined workflow of instrumentation (snapshots) that can be safely deployed in production, right when the problem occurs.

Why Debug Runbooks matter🔗

During live incidents, responders often face a recurring problem: the right data is not available at the right time. A failure may resolve itself, a rollback may restore stability, or logs may never have been added in the relevant code path. As a result, valuable evidence for root cause analysis is lost.

Debug Runbooks address this gap by providing a structured way to collect data during the incident itself. For example:

• Support engineers can capture the same information developers would normally need, without needing to make code changes.
• Automation can be used to freeze important production states immediately before a rollback, without slowing down the response process.

By standardizing these steps, Debug Runbooks make incident investigations more consistent and reduce the likelihood of missing critical information.

Typical use cases🔗

• Production failures that vanish before investigation can begin.
• Critical rollbacks (P0/P1) where stability is restored, but the underlying cause remains hidden.
• Recurring issues where a predefined debugging sequence saves time and ensures consistent investigation.
• Cross-team incidents where developers, SREs, and support engineers need a shared, codified way of gathering information.

Debug Runbooks terminology🔗

Debug Runbooks role and permissions🔗

Debug Runbooks usage in Lightrun is governed by a well-defined role and permissions. Lightrun introduces a dedicated Incident Responder role which is responsible for creating and managing cases. At the same time, the Debugging Runbooks category is shared across a number of roles. For an overview of Lightrun roles, see Lightrun Persona-based roles overview.

The following table summarizes the permissions available under the Debugging Runbooks category for the different roles.

^{Legend: W/R  Write/Read | R  Read only | –  No access}

Debug Runbooks workflow🔗

The Debug Runbooks workflow describes how Runbooks are used during incidents to capture, organize, and analyze diagnostic data for faster resolution.

1. Preliminary stage – runbook creation

   Admins define a Runbook in advance within the Lightrun Management Portal, specifying the diagnostic data to be captured.

2. Incident occurs

   A customer reports an issue to the Support team.

3. Run Case (Runbook execution)

   A Support Engineer initiates a case, which is the execution of one or more predefined Runbooks against the faulty application.

4. Developer analysis

   The captured data is made available through a shared URL, allowing the developers to see all hits captured in real time.

Create a Debug Runbook🔗

^{Required Role: Company Admin}

The Debug Runbook is generated as a JSON file and uploaded to the Lightrun Management Portal by the user assigned with the Company Admin role.

Step 1: Identify and define Debug Runbooks🔗

This section explains how to select and structure Debug Runbooks for consistent, effective use across teams.

Review the best practices below to guide the creation and definition of Debug Runbooks before proceeding to implementation.

Proceed to create the runbooks.

Step 2: Create the JSON configuration file🔗

^{Required Role: Company Admin}

JSON configuration file guidelines🔗

Blank JSON template🔗

Use this template as a starting point when defining your own Runbook JSON configuration. Replace the placeholder values as needed.

  {
    "runbooks": [
      {
        "name": "<runbook_name>",
        "arguments": [
          {
            "label": "<argument_label>",
            "variableName": "<variable_name>",
            "description": "<description_of_argument>",
            "expirationDurationMinutes": "<expiration_duration_in_minutes>"
          }
        ],
        "methods": [
          {
            "filename": "<filename>",
            "methodName": "<method_name>",
            "maxResults": <max_results>,
            "methodTimeoutSeconds": <timeout_in_seconds>,
            "condition": "<condition_expression>",
            "watchExpressions": []
          }
        ]
      }
    ]
  }

Step 3: Upload the JSON to the Lightrun Management Portal🔗

1. Log in to the Lightrun Management Portal.
2. Click Settings in the menu bar.

3. In the left navigation bar, under the Debug Runbooks section, select Configuration File.

   The Debug Runbooks page opens.

   

4. Click Upload.

5. Select the JSON file from your local drive, and click Open.
6. Click Save.

Create and run Debug Runbook cases🔗

^{Required roles: Company Admin, Incident Responder}

Step 1: Create a case🔗

1. Log in to the Lightrun Management Portal.

2. In the left navigation bar, click Debug Runbooks.

   

3. Click New Case.

   The New Case dialog opens.

   

4. In the Case Name field, enter a descriptive name that helps stakeholders understand the context.

5. Select an Environment from the list to run the case. An environment tag is assigned to a predefined Lightrun agent that runs the application and can also be a custom source that contains multiple agents and tags. Each case can run on only one environment.

6. Under the Case description, enter the description or paste a link that will allow users to understand what the case was trying to troubleshoot. Examples are: can’t place an order in the stock application.

7. Click Create.

   A dedicated case view opens with the basic information you entered in the previous step.

8. Click Add Runbook.

   The Add Runbook dialog opens with the listed runbooks

9. Select a Runbook checkbox. Each case can run multiple runbooks.

10. Click Add.

    

    Once created, the case instance is added to the Runbook list and can be viewed by the user who created it, in addition to those who have received a shared link.

Step 2: Run the Debug Runbook🔗

1. In the Case page, select the required runbook to run.

   An instance of the case is added to the runbooks list.

2. In the User field, type a user-friendly text to identify the instance. For example, name.

3. Click the Run icon.

   

   A red icon indicates that the Runbook is running.

4. Go to the application and perform the steps to reproduce the failure scenario. This allows the Runbook to generate Snapshot hits in the relevant code.

   If you’re not sure which Runbook applies, you can add and execute multiple Runbooks—especially if their scopes overlap.

   If you don’t get the expected results, you can modify the setup: change the environment, add or remove Runbooks, or edit Runbook parameters. Then click Play again to rerun the Case.

   Important

   Each time you click Play, the previously captured Snapshot hits for that case are overwritten.

Step 3: Share Debug Runbook hit results🔗

^{Required role: Incident Responder: View Case results permission.}

1. Under the relevant case, select the case to be shared.

2. Click the Share icon to share the case with the developer.

   

   A link is generated.

3. Paste the link to the ticket, which can be viewed by the developer at a later stage.

View and analyze the case results🔗

^{Required role; Incident Responder: View Case results permission.}

Retention: Case Hit results are retained for three months, after which they expire.

The results of the Runbook cases are displayed on the Debug Runbook page in the Lightrun Management Portal.

To view these results, the role assigned to you must include the View cases results permission, which grants read-only access. Note that users with the Developer role have minimal permissions — they can view Case results only through a shared link, since they do not have direct access to the Debug Runbook page in the Portal.

1. Click the shared link you received to open the dedicated URL.

   The page displays the Runbook case results, including a list of hits per Runbook instance, along with the Duration and Agent Name for each entry.

2. Click a hit to view its Snapshot In and Snapshot Out, showing the relevant code context.

   The hits are listed chronologically, from earliest to latest.

   

3. Proceed to debug the code.