Issues

Issues are problems detected automatically by Firetiger’s monitoring agents. Each issue represents a distinct problem observed in your system, linked to the agent session that discovered it. Issues are managed by the system and available as read-only resources.

This page also covers the issue notification policy, which controls how and where Firetiger sends alerts when new issues are detected.

Services: firetiger.issues.v1.IssuesService, firetiger.issues.v2.IssueValidationService, firetiger.issuenotificationpolicy.v1.IssueNotificationPolicyService

Resource name patterns: issues/{issue_id} and issue-notification-policies/{issue_notification_policy_id}

Access: Issues are read-only. Issue evidence validation is read-only and does not create or update issues. The notification policy is read-write.

Resource types: Issue, ValidateIssueEvidenceResponse, Issue Notification Policy

Filtering notes: ListIssues supports environment-aware filtering via deployment_environments, for example deployment_environments:"deployment-environments/firetiger-cloud".

Example flow

List recent issues with a filter, get a specific one, then update the notification policy to route alerts to a new channel.

1. List issues

curl -X POST "https://api.cloud.firetiger.com/firetiger.issues.v1.IssuesService/ListIssues" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"page_size": 10}'

{
  "issues": [
    {
      "name": "issues/iss-db-connection-pool",
      "displayName": "Database connection pool exhaustion",
      "description": "The primary database connection pool is consistently hitting its max limit during peak hours.",
      "source": "deployment-environments/firetiger-cloud",
      "deploymentEnvironments": [
        "deployment-environments/firetiger-cloud"
      ],
      "session": "agents/monitor/sessions/s-abc123",
      "createTime": "2024-06-15T14:30:00Z",
      "updateTime": "2024-06-15T14:30:00Z"
    }
  ]
}

2. Get a specific issue

curl -X POST "https://api.cloud.firetiger.com/firetiger.issues.v1.IssuesService/GetIssue" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"name": "issues/iss-db-connection-pool"}'

{
  "issue": {
    "name": "issues/iss-db-connection-pool",
    "displayName": "Database connection pool exhaustion",
    "description": "The primary database connection pool is consistently hitting its max limit during peak hours, causing request queuing and timeouts for downstream services.",
    "source": "deployment-environments/firetiger-cloud",
    "deploymentEnvironments": [
      "deployment-environments/firetiger-cloud"
    ],
    "session": "agents/monitor/sessions/s-abc123",
    "createTime": "2024-06-15T14:30:00Z",
    "updateTime": "2024-06-15T14:30:00Z"
  }
}

3. Update the notification policy

curl -X POST "https://api.cloud.firetiger.com/firetiger.issuenotificationpolicy.v1.IssueNotificationPolicyService/UpdateIssueNotificationPolicy" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "issue_notification_policy": {
      "connections": ["connections/slack-oncall", "connections/pagerduty-prod"],
      "prompt": "Send critical issues to #oncall-alerts in Slack and create a PagerDuty incident."
    },
    "update_mask": "connections,prompt"
  }'

{
  "issueNotificationPolicy": {
    "name": "issue-notification-policies/default",
    "description": "Route critical issues to the on-call Slack channel and PagerDuty",
    "connections": [
      "connections/slack-oncall",
      "connections/pagerduty-prod"
    ],
    "prompt": "Send critical issues to #oncall-alerts in Slack and create a PagerDuty incident.",
    "state": "ISSUE_NOTIFICATION_POLICY_STATE_ACTIVE",
    "createTime": "2024-06-10T09:00:00Z",
    "updateTime": "2024-06-16T10:15:00Z"
  }
}

Methods

Method Service Description
GetIssue IssuesService Retrieve an issue by name
ListIssues IssuesService List issues with filtering and pagination
ValidateIssueEvidence IssueValidationService Validate that proposed issues are supported by supplied evidence
GetIssueNotificationPolicy IssueNotificationPolicyService Retrieve the current notification policy
UpdateIssueNotificationPolicy IssueNotificationPolicyService Update the notification policy

GetIssue

Retrieve an issue by name.

POST /firetiger.issues.v1.IssuesService/GetIssue

Request body

Field Type Required Description
name string Yes Resource name of the issue (issues/{id})

Example

curl -X POST "https://api.cloud.firetiger.com/firetiger.issues.v1.IssuesService/GetIssue" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"name": "issues/iss-db-connection-pool"}'

Response

{
  "issue": {
    "name": "issues/iss-db-connection-pool",
    "displayName": "Database connection pool exhaustion",
    "description": "The primary database connection pool is consistently hitting its max limit during peak hours, causing request queuing and timeouts for downstream services.",
    "session": "agents/monitor/sessions/s-abc123",
    "createTime": "2024-06-15T14:30:00Z",
    "updateTime": "2024-06-15T14:30:00Z"
  }
}

ListIssues

List issues with optional filtering and pagination.

POST /firetiger.issues.v1.IssuesService/ListIssues

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 issues

Example filters

  • deployment_environments:"deployment-environments/firetiger-cloud" – issues affecting a specific deployment environment
  • workflow_state = 'ISSUE_WORKFLOW_STATE_ACTIONABLE' AND deployment_environments:"deployment-environments/firetiger-cloud" – actionable issues scoped to one environment
  • services:"services/api-gateway" – issues belonging to a specific Service
  • workflow_state != 'ISSUE_WORKFLOW_STATE_CLOSED' AND services:"services/api-gateway" – open issues for a Service (how the triage agent dedups)
  • objectives:"objectives/api-server-latency" – issues belonging to a specific Objective (set on objective-breach escalations)

Example

curl -X POST "https://api.cloud.firetiger.com/firetiger.issues.v1.IssuesService/ListIssues" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"page_size": 25}'

Response

{
  "issues": [
    {
      "name": "issues/iss-db-connection-pool",
      "displayName": "Database connection pool exhaustion",
      "description": "The primary database connection pool is consistently hitting its max limit during peak hours, causing request queuing and timeouts for downstream services.",
      "source": "deployment-environments/firetiger-cloud",
      "deploymentEnvironments": [
        "deployment-environments/firetiger-cloud"
      ],
      "session": "agents/monitor/sessions/s-abc123",
      "createTime": "2024-06-15T14:30:00Z",
      "updateTime": "2024-06-15T14:30:00Z"
    }
  ],
  "nextPageToken": ""
}

ValidateIssueEvidence

Validate that proposed issues are supported by concrete evidence before a caller creates or escalates them. This method is advisory: it does not create, update, or delete issues.

POST /firetiger.issues.v2.IssueValidationService/ValidateIssueEvidence
POST /v2/issues:validateEvidence

Request body

Field Type Required Description
issues Issue[] Yes Proposed issues to validate. Issues may be unsaved and do not need name set yet. Send 1 to 10 issues.
evidence_context string Yes Evidence and transcript context the validator should use when judging whether the proposed issues are supported. Maximum 15,000 characters.
source_session string No Agent session that produced the evidence (agents/{agent}/sessions/{session})

Decision semantics

  • ISSUE_EVIDENCE_VALIDATION_DECISION_PASS: every proposed issue is supported by the supplied evidence.
  • ISSUE_EVIDENCE_VALIDATION_DECISION_FAIL: at least one proposed issue lacks sufficient evidence. Callers that enforce validation should block creation on this decision.
  • ISSUE_EVIDENCE_VALIDATION_DECISION_SKIPPED: validation was not configured or could not complete. passes is true for this fail-open decision, so callers that need audit detail should inspect decision as well as passes.

Example

curl -X POST "https://api.cloud.firetiger.com/firetiger.issues.v2.IssueValidationService/ValidateIssueEvidence" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "issues": [
      {
        "title": "Checkout API errors increased",
        "description": "Checkout API 500 responses increased in production after the deploy.",
        "details": "Query at 2026-06-05T18:00:00Z returned 124 500 responses in 5 minutes versus 3 in the same window last week."
      }
    ],
    "evidence_context": "Query at 2026-06-05T18:00:00Z returned 124 500 responses in 5 minutes versus 3 in the same window last week.",
    "source_session": "agents/change-monitor/sessions/session-123"
  }'

Response

{
  "decision": "ISSUE_EVIDENCE_VALIDATION_DECISION_PASS",
  "passes": true,
  "feedback": "Issue evidence validation passed.",
  "findings": [],
  "validatorVersion": "issue-evidence-v1"
}

GetIssueNotificationPolicy

Retrieve the current issue notification policy. The notification policy is a singleton resource that controls how Firetiger routes alerts when issues are detected. It defines which connections (e.g. Slack, PagerDuty) receive notifications and includes a prompt that guides the notification agent’s behavior.

POST /firetiger.issuenotificationpolicy.v1.IssueNotificationPolicyService/GetIssueNotificationPolicy

Request body

This method takes no parameters. Send an empty JSON object.

Example

curl -X POST "https://api.cloud.firetiger.com/firetiger.issuenotificationpolicy.v1.IssueNotificationPolicyService/GetIssueNotificationPolicy" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{}'

Response

{
  "issueNotificationPolicy": {
    "name": "issue-notification-policies/default",
    "description": "Route critical issues to the on-call Slack channel and PagerDuty",
    "connections": [
      "connections/slack-oncall",
      "connections/pagerduty-prod"
    ],
    "prompt": "Send critical issues to #oncall-alerts in Slack and create a PagerDuty incident. For non-critical issues, post to #issues in Slack only.",
    "state": "ISSUE_NOTIFICATION_POLICY_STATE_ACTIVE",
    "createTime": "2024-06-10T09:00:00Z",
    "updateTime": "2024-06-15T14:30:00Z"
  }
}

UpdateIssueNotificationPolicy

Update the issue notification policy. Use update_mask to specify which fields to modify.

POST /firetiger.issuenotificationpolicy.v1.IssueNotificationPolicyService/UpdateIssueNotificationPolicy

Request body

Field Type Required Description
issue_notification_policy IssueNotificationPolicy Yes The policy 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.cloud.firetiger.com/firetiger.issuenotificationpolicy.v1.IssueNotificationPolicyService/UpdateIssueNotificationPolicy" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "issue_notification_policy": {
      "name": "issue-notification-policies/default",
      "connections": [
        "connections/slack-oncall",
        "connections/pagerduty-prod",
        "connections/email-eng-leads"
      ],
      "prompt": "Send critical issues to #oncall-alerts in Slack and create a PagerDuty incident. For non-critical issues, post to #issues in Slack and email engineering leads."
    },
    "update_mask": "connections,prompt"
  }'

Response

{
  "issueNotificationPolicy": {
    "name": "issue-notification-policies/default",
    "description": "Route critical issues to the on-call Slack channel and PagerDuty",
    "connections": [
      "connections/slack-oncall",
      "connections/pagerduty-prod",
      "connections/email-eng-leads"
    ],
    "prompt": "Send critical issues to #oncall-alerts in Slack and create a PagerDuty incident. For non-critical issues, post to #issues in Slack and email engineering leads.",
    "state": "ISSUE_NOTIFICATION_POLICY_STATE_ACTIVE",
    "createTime": "2024-06-10T09:00:00Z",
    "updateTime": "2024-06-16T10:15:00Z"
  }
}
This site uses Just the Docs, a documentation theme for Jekyll.