Monitoring Plans

Monitoring plans track deployment risk for pull requests. When a PR is merged and deployed, Firetiger monitors the deployment for unintended effects based on a plan written by an agent during code review.

This page covers three services: MonitoringPlanService for plan lifecycle and status updates, ChangeMonitorNotificationsService for personal Change Monitor notification setup, and MonitoringRunService (legacy) for backward-compatible run access.

Services: firetiger.monitoring_plans.v1.MonitoringPlanService, firetiger.monitoring_plans.v1.ChangeMonitorNotificationsService, firetiger.monitoring_plans.v1.MonitoringRunService

Resource name patterns: monitoring-plans/{plan_id} and monitoring-plans/{plan_id}/runs/{run_id}

Access: Read-write for status updates, read-only for externally managed monitoring state

Resource types: Monitoring Plan, Monitoring Run

Example flow

List recent monitoring plans, then fetch details for a specific one.

1. List monitoring plans

curl -X POST "https://api.cloud.firetiger.com/firetiger.monitoring_plans.v1.MonitoringPlanService/ListMonitoringPlans" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"page_size": 5, "order_by": "create_time desc"}'

{
  "monitoringPlans": [
    {
      "name": "monitoring-plans/plan-abc123",
      "origin": {
        "repository": "acme-corp/backend",
        "prNumber": 42,
        "prTitle": "Fix auth service timeout handling",
        "prAuthorGithubLogin": "engineer",
        "prAuthorGithubUserId": "1234567"
      },
      "planSummary": "Fixes auth service timeout handling to prevent cascading failures during peak traffic.",
      "createTime": "2024-06-15T14:30:00Z"
    }
  ],
  "nextPageToken": ""
}

2. Get plan details

curl -X POST "https://api.cloud.firetiger.com/firetiger.monitoring_plans.v1.MonitoringPlanService/GetMonitoringPlan" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"name": "monitoring-plans/plan-abc123"}'

{
  "monitoringPlan": {
    "name": "monitoring-plans/plan-abc123",
    "origin": {
      "repository": "acme-corp/backend",
      "prNumber": 42,
      "prUrl": "https://github.com/acme-corp/backend/pull/42",
      "headSha": "a1b2c3d4e5f6",
      "prTitle": "Fix auth service timeout handling",
      "prAuthorGithubLogin": "engineer",
      "prAuthorGithubUserId": "1234567"
    },
    "activation": {
      "mergeSha": "f6e5d4c3b2a1",
      "environments": ["production"]
    },
    "planContent": "## Intended Effect\nFixes timeout handling in auth service...",
    "planSummary": "Fixes auth service timeout handling to prevent cascading failures during peak traffic.",
    "notificationChannel": "#deploy-alerts",
    "authorSession": "agents/plan-author/sessions/sess-xyz",
    "createTime": "2024-06-15T14:30:00Z",
    "updateTime": "2024-06-15T15:00:00Z",
    "deployments": [
      {
        "environment": "production",
        "deployment": "deployments/dep-789",
        "deployTime": "2024-06-15T16:00:00Z",
        "intendedEffectConfirmed": true,
        "outcome": "MONITORING_OUTCOME_NO_ISSUE",
        "completeTime": "2024-06-15T17:30:00Z"
      }
    ],
    "lastCheckTime": "2024-06-15T17:30:00Z"
  }
}

Methods

Method Service Description
GetMonitoringPlan MonitoringPlanService Retrieve a monitoring plan by name
ListMonitoringPlans MonitoringPlanService List monitoring plans with filtering and pagination
PostPlanComment MonitoringPlanService Post a monitoring update to the originating pull request and configured user DMs
GetMyChangeMonitorSetup ChangeMonitorNotificationsService Read the current user’s Change Monitor notification setup
UpdateMyChangeMonitorNotificationPreference ChangeMonitorNotificationsService Enable or disable the current user’s Change Monitor notifications
VerifyMyChangeMonitorSlackDM ChangeMonitorNotificationsService Send a test Slack DM and store the verified Slack destination
GetMonitoringRun MonitoringRunService Retrieve a monitoring run by name
ListMonitoringRuns MonitoringRunService List monitoring runs for a plan

GetMonitoringPlan

Retrieve a monitoring plan by name.

POST /firetiger.monitoring_plans.v1.MonitoringPlanService/GetMonitoringPlan

Request body

Field Type Required Description
name string Yes Resource name of the monitoring plan

Example

curl -X POST "https://api.cloud.firetiger.com/firetiger.monitoring_plans.v1.MonitoringPlanService/GetMonitoringPlan" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"name": "monitoring-plans/plan-abc123"}'

Response

{
  "monitoringPlan": {
    "name": "monitoring-plans/plan-abc123",
    "origin": {
      "repository": "acme-corp/backend",
      "prNumber": 42,
      "prUrl": "https://github.com/acme-corp/backend/pull/42",
      "headSha": "a1b2c3d4e5f6",
      "prTitle": "Fix auth service timeout handling",
      "prAuthorGithubLogin": "engineer",
      "prAuthorGithubUserId": "1234567"
    },
    "activation": {
      "mergeSha": "f6e5d4c3b2a1",
      "environments": ["production"]
    },
    "planContent": "## Intended Effect\nFixes timeout handling in auth service...",
    "planSummary": "Fixes auth service timeout handling to prevent cascading failures during peak traffic.",
    "notificationChannel": "#deploy-alerts",
    "authorSession": "agents/plan-author/sessions/sess-xyz",
    "createTime": "2024-06-15T14:30:00Z",
    "updateTime": "2024-06-15T15:00:00Z",
    "deployments": [
      {
        "environment": "production",
        "deployment": "deployments/dep-789",
        "deployTime": "2024-06-15T16:00:00Z",
        "intendedEffectConfirmed": true,
        "outcome": "MONITORING_OUTCOME_NO_ISSUE",
        "completeTime": "2024-06-15T17:30:00Z"
      }
    ],
    "lastCheckTime": "2024-06-15T17:30:00Z"
  }
}

ListMonitoringPlans

List monitoring plans with optional filtering and pagination.

POST /firetiger.monitoring_plans.v1.MonitoringPlanService/ListMonitoringPlans

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 monitoring plans

Example

curl -X POST "https://api.cloud.firetiger.com/firetiger.monitoring_plans.v1.MonitoringPlanService/ListMonitoringPlans" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"page_size": 10, "order_by": "create_time desc"}'

Response

{
  "monitoringPlans": [
    {
      "name": "monitoring-plans/plan-abc123",
      "origin": {
        "repository": "acme-corp/backend",
        "prNumber": 42,
        "prUrl": "https://github.com/acme-corp/backend/pull/42",
        "prTitle": "Fix auth service timeout handling",
        "prAuthorGithubLogin": "engineer",
        "prAuthorGithubUserId": "1234567"
      },
      "planSummary": "Fixes auth service timeout handling to prevent cascading failures during peak traffic.",
      "createTime": "2024-06-15T14:30:00Z",
      "updateTime": "2024-06-15T15:00:00Z"
    }
  ],
  "nextPageToken": ""
}

PostPlanComment

Post a Markdown monitoring update to the pull request associated with a monitoring plan. If the PR author has linked GitHub and Slack and enabled Change Monitor DMs, Firetiger also sends the same update to their Slack DM. GitHub comment posting and Slack delivery are best-effort and independent.

POST /v1/monitoring-plans/{plan_id}:postComment

Path parameters

Field Type Required Description
plan_id string Yes ID portion of the monitoring plan resource name

Request body

Field Type Required Description
comment_body string Yes Markdown body to post on the pull request

Example

curl -X POST "https://api.cloud.firetiger.com/v1/monitoring-plans/plan-abc123:postComment" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "comment_body": "Post-deployment verification completed. No anomalies were detected."
  }'

Response

{
  "commentUrl": "https://github.com/acme-corp/backend/pull/42#issuecomment-1234567890"
}

GetMyChangeMonitorSetup

Read the current user’s personal Change Monitor notification setup. This includes their GitHub identity link, Slack identity link, installed Slack app connection, and notification preference.

GET /v1/users/me/change-monitor-setup

Example

curl "https://api.cloud.firetiger.com/v1/users/me/change-monitor-setup" \
  -u "$USERNAME:$PASSWORD"

Response

{
  "setup": {
    "preference": {
      "enabled": true,
      "slackDestination": {
        "slackConnection": "connections/slack-test",
        "slackExternalIdentity": "users/user-123/external-identities/slack"
      }
    },
    "status": "CHANGE_MONITOR_NOTIFICATION_SETUP_STATUS_READY"
  }
}

UpdateMyChangeMonitorNotificationPreference

Enable or disable Change Monitor notifications for the current user. When enabled, every Change Monitor notification is delivered to the verified Slack DM destination.

PATCH /v1/users/me/change-monitor-notification-preference

Request body

Field Type Required Description
preference.enabled boolean No Whether Change Monitor notifications are enabled
update_mask string No Comma-separated field mask. Defaults to enabled

Example

curl -X PATCH "https://api.cloud.firetiger.com/v1/users/me/change-monitor-notification-preference" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "preference": {
      "enabled": true
    },
    "update_mask": "enabled"
  }'

Response

{
  "preference": {
    "enabled": true,
    "slackDestination": {
      "slackConnection": "connections/slack-test",
      "slackExternalIdentity": "users/user-123/external-identities/slack"
    }
  }
}

VerifyMyChangeMonitorSlackDM

Send a test DM to the current user’s linked Slack account and store that Slack connection as the verified destination for Change Monitor notifications.

POST /v1/users/me/change-monitor-notification-preference:verify-slack-dm

Request body

Field Type Required Description
slack_connection string Yes Slack app connection resource name to verify

Example

curl -X POST "https://api.cloud.firetiger.com/v1/users/me/change-monitor-notification-preference:verify-slack-dm" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"slack_connection": "connections/slack-test"}'

Response

{
  "preference": {
    "enabled": true,
    "slackDestination": {
      "slackConnection": "connections/slack-test",
      "slackExternalIdentity": "users/user-123/external-identities/slack"
    }
  }
}

GetMonitoringRun

MonitoringRunService is a legacy service. New monitoring state is stored directly on MonitoringPlan.deployments. The run endpoints are retained for backward compatibility.

Retrieve a monitoring run by name.

POST /firetiger.monitoring_plans.v1.MonitoringRunService/GetMonitoringRun

Request body

Field Type Required Description
name string Yes Resource name of the monitoring run

Example

curl -X POST "https://api.cloud.firetiger.com/firetiger.monitoring_plans.v1.MonitoringRunService/GetMonitoringRun" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"name": "monitoring-plans/plan-abc123/runs/run-prod-001"}'

Response

{
  "monitoringRun": {
    "name": "monitoring-plans/plan-abc123/runs/run-prod-001",
    "environment": "production",
    "deployment": "deployments/dep-789",
    "status": "MONITORING_RUN_STATUS_COMPLETED",
    "outcome": "MONITORING_RUN_OUTCOME_NO_ISSUE",
    "intendedEffectConfirmed": true,
    "activateTime": "2024-06-15T16:00:00Z",
    "completeTime": "2024-06-15T17:30:00Z",
    "lastCheckTime": "2024-06-15T17:30:00Z",
    "createTime": "2024-06-15T16:00:00Z",
    "updateTime": "2024-06-15T17:30:00Z"
  }
}

ListMonitoringRuns

MonitoringRunService is a legacy service. New monitoring state is stored directly on MonitoringPlan.deployments. The run endpoints are retained for backward compatibility.

List monitoring runs for a plan with optional filtering and pagination.

POST /firetiger.monitoring_plans.v1.MonitoringRunService/ListMonitoringRuns

Request body

Field Type Required Description
parent string Yes Parent monitoring plan resource name
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 monitoring runs

Example

curl -X POST "https://api.cloud.firetiger.com/firetiger.monitoring_plans.v1.MonitoringRunService/ListMonitoringRuns" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"parent": "monitoring-plans/plan-abc123", "page_size": 10}'

Response

{
  "monitoringRuns": [
    {
      "name": "monitoring-plans/plan-abc123/runs/run-prod-001",
      "environment": "production",
      "deployment": "deployments/dep-789",
      "status": "MONITORING_RUN_STATUS_COMPLETED",
      "outcome": "MONITORING_RUN_OUTCOME_NO_ISSUE",
      "intendedEffectConfirmed": true,
      "activateTime": "2024-06-15T16:00:00Z",
      "completeTime": "2024-06-15T17:30:00Z",
      "createTime": "2024-06-15T16:00:00Z",
      "updateTime": "2024-06-15T17:30:00Z"
    }
  ],
  "nextPageToken": ""
}
This site uses Just the Docs, a documentation theme for Jekyll.