Runbooks

Runbooks are structured operating procedures that Firetiger agents follow when investigating or resolving issues. Each runbook contains instructional text and a set of connections with specific tools that the agent is allowed to use while executing the runbook.

Service: firetiger.runbooks.v1.RunbooksService

Resource name pattern: runbooks/{runbook_id}

Access: Read-write

Resource type: Runbook

Example flow

Create a runbook that pairs connections with specific tools, then list all runbooks.

1. Create a runbook with connections and tools

curl -X POST "https://api.ft-scaletowin.firetigerapi.com/firetiger.runbooks.v1.RunbooksService/CreateRunbook" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "runbook_id": "high-error-rate-triage",
    "runbook": {
      "display_name": "High Error Rate Triage",
      "description": "Steps for triaging elevated error rates on production services",
      "text": "1. Query the database for recent deployments.\n2. Check HTTP error rates via Prometheus.\n3. If a recent deploy correlates, escalate to the owning team.",
      "connections": [
        {
          "name": "connections/prod-postgres",
          "enabled_tools": ["TOOL_POSTGRES_QUERY"]
        },
        {
          "name": "connections/prod-prometheus",
          "enabled_tools": ["TOOL_PROMQL_QUERY", "TOOL_PROMQL_QUERY_RANGE"]
        }
      ]
    }
  }'

{
  "runbook": {
    "name": "runbooks/high-error-rate-triage",
    "displayName": "High Error Rate Triage",
    "description": "Steps for triaging elevated error rates on production services",
    "text": "1. Query the database for recent deployments.\n2. Check HTTP error rates via Prometheus.\n3. If a recent deploy correlates, escalate to the owning team.",
    "connections": [
      {
        "name": "connections/prod-postgres",
        "enabledTools": ["TOOL_POSTGRES_QUERY"]
      },
      {
        "name": "connections/prod-prometheus",
        "enabledTools": ["TOOL_PROMQL_QUERY", "TOOL_PROMQL_QUERY_RANGE"]
      }
    ],
    "createTime": "2024-08-10T09:00:00Z",
    "updateTime": "2024-08-10T09:00:00Z"
  }
}

2. Create a second runbook

curl -X POST "https://api.ft-scaletowin.firetigerapi.com/firetiger.runbooks.v1.RunbooksService/CreateRunbook" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "runbook_id": "deployment-rollback",
    "runbook": {
      "display_name": "Deployment Rollback",
      "description": "Procedure for rolling back a bad deployment",
      "text": "1. Identify the failing deployment via CI/CD.\n2. Trigger rollback to the last known-good version.\n3. Verify error rates return to baseline."
    }
  }'

{
  "runbook": {
    "name": "runbooks/deployment-rollback",
    "displayName": "Deployment Rollback",
    "description": "Procedure for rolling back a bad deployment",
    "text": "1. Identify the failing deployment via CI/CD.\n2. Trigger rollback to the last known-good version.\n3. Verify error rates return to baseline.",
    "createTime": "2024-08-10T09:01:00Z",
    "updateTime": "2024-08-10T09:01:00Z"
  }
}

3. List all runbooks

curl -X POST "https://api.ft-scaletowin.firetigerapi.com/firetiger.runbooks.v1.RunbooksService/ListRunbooks" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "runbooks": [
    {
      "name": "runbooks/high-error-rate-triage",
      "displayName": "High Error Rate Triage",
      "description": "Steps for triaging elevated error rates on production services",
      "createTime": "2024-08-10T09:00:00Z",
      "updateTime": "2024-08-10T09:00:00Z"
    },
    {
      "name": "runbooks/deployment-rollback",
      "displayName": "Deployment Rollback",
      "description": "Procedure for rolling back a bad deployment",
      "createTime": "2024-08-10T09:01:00Z",
      "updateTime": "2024-08-10T09:01:00Z"
    }
  ],
  "nextPageToken": ""
}

Methods

Method Description
CreateRunbook Create a new runbook
GetRunbook Retrieve a runbook by name
UpdateRunbook Update an existing runbook
DeleteRunbook Soft-delete a runbook
ListRunbooks List runbooks with filtering and pagination

CreateRunbook

Create a new runbook.

POST /firetiger.runbooks.v1.RunbooksService/CreateRunbook

Request body

Field Type Required Description
runbook_id string Yes ID for the new runbook (alphanumeric, hyphens, underscores)
runbook Runbook Yes The runbook to create

Example

curl -X POST "https://api.ft-scaletowin.firetigerapi.com/firetiger.runbooks.v1.RunbooksService/CreateRunbook" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "runbook_id": "high-error-rate-triage",
    "runbook": {
      "display_name": "High Error Rate Triage",
      "description": "Steps for triaging elevated error rates on production services",
      "text": "1. Query the database for recent deployments.\n2. Check HTTP error rates via Prometheus.\n3. If a recent deploy correlates, escalate to the owning team.",
      "connections": [
        {
          "name": "connections/prod-postgres",
          "enabled_tools": ["TOOL_POSTGRES_QUERY"]
        },
        {
          "name": "connections/prod-prometheus",
          "enabled_tools": ["TOOL_PROMQL_QUERY", "TOOL_PROMQL_QUERY_RANGE"]
        }
      ]
    }
  }'

Response

{
  "runbook": {
    "name": "runbooks/high-error-rate-triage",
    "displayName": "High Error Rate Triage",
    "description": "Steps for triaging elevated error rates on production services",
    "text": "1. Query the database for recent deployments.\n2. Check HTTP error rates via Prometheus.\n3. If a recent deploy correlates, escalate to the owning team.",
    "connections": [
      {
        "name": "connections/prod-postgres",
        "enabledTools": ["TOOL_POSTGRES_QUERY"]
      },
      {
        "name": "connections/prod-prometheus",
        "enabledTools": ["TOOL_PROMQL_QUERY", "TOOL_PROMQL_QUERY_RANGE"]
      }
    ],
    "createTime": "2024-08-10T09:00:00Z",
    "updateTime": "2024-08-10T09:00:00Z"
  }
}

GetRunbook

Retrieve a runbook by name.

POST /firetiger.runbooks.v1.RunbooksService/GetRunbook

Request body

Field Type Required Description
name string Yes Resource name of the runbook

Example

curl -X POST "https://api.ft-scaletowin.firetigerapi.com/firetiger.runbooks.v1.RunbooksService/GetRunbook" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"name": "runbooks/high-error-rate-triage"}'

UpdateRunbook

Update an existing runbook. Use update_mask to specify which fields to modify.

POST /firetiger.runbooks.v1.RunbooksService/UpdateRunbook

Request body

Field Type Required Description
runbook Runbook Yes The runbook with name set and updated fields
update_mask string No Comma-separated list of fields to update. If omitted, all provided fields are updated.

Example

curl -X POST "https://api.ft-scaletowin.firetigerapi.com/firetiger.runbooks.v1.RunbooksService/UpdateRunbook" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "runbook": {
      "name": "runbooks/high-error-rate-triage",
      "description": "Updated triage steps for elevated error rates, now includes log correlation"
    },
    "update_mask": "description"
  }'

DeleteRunbook

Soft-delete a runbook. The resource will still be accessible via Get but excluded from List results unless show_deleted is set.

POST /firetiger.runbooks.v1.RunbooksService/DeleteRunbook

Request body

Field Type Required Description
name string Yes Resource name of the runbook to delete

Example

curl -X POST "https://api.ft-scaletowin.firetigerapi.com/firetiger.runbooks.v1.RunbooksService/DeleteRunbook" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"name": "runbooks/high-error-rate-triage"}'

ListRunbooks

List runbooks with optional filtering and pagination.

POST /firetiger.runbooks.v1.RunbooksService/ListRunbooks

Request body

Field Type Required Description
filter string No Filter expression
order_by string No Field to sort by (e.g. create_time desc)
page_size integer No Maximum results per page
page_token string No Token for the next page of results
show_deleted boolean No Include soft-deleted runbooks

Example

curl -X POST "https://api.ft-scaletowin.firetigerapi.com/firetiger.runbooks.v1.RunbooksService/ListRunbooks" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"page_size": 25}'

Response

{
  "runbooks": [
    {
      "name": "runbooks/high-error-rate-triage",
      "displayName": "High Error Rate Triage",
      "description": "Steps for triaging elevated error rates on production services",
      "createTime": "2024-08-10T09:00:00Z",
      "updateTime": "2024-08-10T09:00:00Z"
    }
  ],
  "nextPageToken": ""
}
This site uses Just the Docs, a documentation theme for Jekyll.