Known Issues

Known issues are problems your team is actively tracking. They can be linked to objectives, and Firetiger’s agents use them to contextualize new findings against previously seen problems.

While Issues are raw findings submitted by agents, known issues let you curate and group those findings into tracked problems with their own lifecycle (active, resolved, etc.).

Service: firetiger.knownissues.v1.KnownIssuesService

Resource name pattern: known-issues/{known_issue_id}

Access: Read-write

Resource type: Known Issue

Example flow

Create a known issue to track a recurring problem, list active issues to check on it, then mark it resolved once the fix is deployed.

1. Create a known issue

curl -X POST "https://api.ft-scaletowin.firetigerapi.com/firetiger.knownissues.v1.KnownIssuesService/CreateKnownIssue" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "known_issue_id": "ki-db-connection-pool",
    "known_issue": {
      "title": "Database connection pool exhaustion under load",
      "context": "First observed after migrating to the new connection pooler. Connections are not being released properly when queries time out.",
      "human_description": "Under sustained load, the database connection pool fills up and new queries start failing with connection timeout errors.",
      "status": "KNOWN_ISSUE_STATUS_ACTIVE"
    }
  }'

{
  "knownIssue": {
    "name": "known-issues/ki-db-connection-pool",
    "title": "Database connection pool exhaustion under load",
    "context": "First observed after migrating to the new connection pooler. Connections are not being released properly when queries time out.",
    "humanDescription": "Under sustained load, the database connection pool fills up and new queries start failing with connection timeout errors.",
    "status": "KNOWN_ISSUE_STATUS_ACTIVE",
    "createTime": "2024-06-15T14:30:00Z",
    "updateTime": "2024-06-15T14:30:00Z"
  }
}

2. List active known issues

curl -X POST "https://api.ft-scaletowin.firetigerapi.com/firetiger.knownissues.v1.KnownIssuesService/ListKnownIssues" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"filter": "status = \"KNOWN_ISSUE_STATUS_ACTIVE\""}'

{
  "knownIssues": [
    {
      "name": "known-issues/ki-db-connection-pool",
      "title": "Database connection pool exhaustion under load",
      "status": "KNOWN_ISSUE_STATUS_ACTIVE",
      "createTime": "2024-06-15T14:30:00Z",
      "updateTime": "2024-06-15T14:30:00Z"
    }
  ],
  "nextPageToken": ""
}

3. Mark it resolved after deploying a fix

curl -X POST "https://api.ft-scaletowin.firetigerapi.com/firetiger.knownissues.v1.KnownIssuesService/UpdateKnownIssue" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "known_issue": {
      "name": "known-issues/ki-db-connection-pool",
      "status": "KNOWN_ISSUE_STATUS_RESOLVED"
    },
    "update_mask": "status"
  }'

{
  "knownIssue": {
    "name": "known-issues/ki-db-connection-pool",
    "title": "Database connection pool exhaustion under load",
    "context": "First observed after migrating to the new connection pooler. Connections are not being released properly when queries time out.",
    "humanDescription": "Under sustained load, the database connection pool fills up and new queries start failing with connection timeout errors.",
    "status": "KNOWN_ISSUE_STATUS_RESOLVED",
    "createTime": "2024-06-15T14:30:00Z",
    "updateTime": "2024-06-15T15:45:00Z"
  }
}

Methods

Method Description
CreateKnownIssue Create a new known issue
GetKnownIssue Retrieve a known issue by name
UpdateKnownIssue Update an existing known issue
DeleteKnownIssue Soft-delete a known issue
ListKnownIssues List known issues with filtering and pagination

CreateKnownIssue

Create a new known issue.

POST /firetiger.knownissues.v1.KnownIssuesService/CreateKnownIssue

Request body

Field Type Required Description
known_issue_id string Yes ID for the new known issue (alphanumeric, hyphens, underscores)
known_issue KnownIssue Yes The known issue to create

Example

curl -X POST "https://api.ft-scaletowin.firetigerapi.com/firetiger.knownissues.v1.KnownIssuesService/CreateKnownIssue" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "known_issue_id": "ki-auth-timeout",
    "known_issue": {
      "title": "Auth service timeouts during peak hours",
      "context": "Started after the v2.3 deploy. Auth service pods are hitting memory limits.",
      "human_description": "The auth service times out intermittently during peak traffic, causing login failures for about 5% of users.",
      "status": "KNOWN_ISSUE_STATUS_ACTIVE"
    }
  }'

Response

{
  "knownIssue": {
    "name": "known-issues/ki-auth-timeout",
    "title": "Auth service timeouts during peak hours",
    "context": "Started after the v2.3 deploy. Auth service pods are hitting memory limits.",
    "humanDescription": "The auth service times out intermittently during peak traffic, causing login failures for about 5% of users.",
    "status": "KNOWN_ISSUE_STATUS_ACTIVE",
    "createTime": "2024-06-15T14:30:00Z",
    "updateTime": "2024-06-15T14:30:00Z"
  }
}

GetKnownIssue

Retrieve a known issue by name.

POST /firetiger.knownissues.v1.KnownIssuesService/GetKnownIssue

Request body

Field Type Required Description
name string Yes Resource name of the known issue

Example

curl -X POST "https://api.ft-scaletowin.firetigerapi.com/firetiger.knownissues.v1.KnownIssuesService/GetKnownIssue" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"name": "known-issues/ki-auth-timeout"}'

UpdateKnownIssue

Update an existing known issue. Use update_mask to specify which fields to modify.

POST /firetiger.knownissues.v1.KnownIssuesService/UpdateKnownIssue

Request body

Field Type Required Description
known_issue KnownIssue Yes The known issue 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.knownissues.v1.KnownIssuesService/UpdateKnownIssue" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "known_issue": {
      "name": "known-issues/ki-auth-timeout",
      "status": "KNOWN_ISSUE_STATUS_RESOLVED"
    },
    "update_mask": "status"
  }'

DeleteKnownIssue

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

POST /firetiger.knownissues.v1.KnownIssuesService/DeleteKnownIssue

Request body

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

Example

curl -X POST "https://api.ft-scaletowin.firetigerapi.com/firetiger.knownissues.v1.KnownIssuesService/DeleteKnownIssue" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"name": "known-issues/ki-auth-timeout"}'

ListKnownIssues

List known issues with optional filtering and pagination.

POST /firetiger.knownissues.v1.KnownIssuesService/ListKnownIssues

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 known issues

Example

curl -X POST "https://api.ft-scaletowin.firetigerapi.com/firetiger.knownissues.v1.KnownIssuesService/ListKnownIssues" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"filter": "status = \"KNOWN_ISSUE_STATUS_ACTIVE\"", "page_size": 25}'

Response

{
  "knownIssues": [
    {
      "name": "known-issues/ki-auth-timeout",
      "title": "Auth service timeouts during peak hours",
      "status": "KNOWN_ISSUE_STATUS_ACTIVE",
      "createTime": "2024-06-15T14:30:00Z",
      "updateTime": "2024-06-15T14:30:00Z"
    }
  ],
  "nextPageToken": ""
}
This site uses Just the Docs, a documentation theme for Jekyll.