REST Resource: projects.locations.investigations

Resource: Investigation

Holds the contents of a Gemini Cloud Assist Troubleshooting investigation.

JSON representation 
{
  "name": string,
  "createTime": string,
  "updateTime": string,
  "labels": {
    string: string,
    ...
  },
  "revision": string,
  "revisionIndex": integer,
  "revisionPredecessor": string,
  "annotations": {
    object (InvestigationAnnotations)
  },
  "executionState": enum (InvestigationExecutionState),
  "error": {
    object (Status)
  },
  "operation": string,
  "title": string,
  "observations": {
    string: {
      object (Observation)
    },
    ...
  },
  "observerStatuses": {
    string: {
      object (ObserverStatus)
    },
    ...
  }
}
Fields
name

string

Identifier. Name of the investigation, of the form: projects/{projectNumber}/locations/{locationId}/investigations/{investigationId}
createTime

string (Timestamp format)

Output only. The time when the investigation was created.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
updateTime

string (Timestamp format)

Output only. The time when the investigation was last updated.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
labels

map (key: string, value: string)

Optional. User-defined labels for the investigation.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
revision

string

Output only. Resource name of the investigation's current revision, of the form: projects/{projectNumber}/locations/{locationId}/investigations/{investigationId}/revisions/{revision_id}
revisionIndex

integer

Output only. Index of the current revision of the investigation.
revisionPredecessor

string

Optional. The name of the revision that was this revision's predecessor.
annotations

object (InvestigationAnnotations)

Optional. Additional annotations on the investigation.
executionState

enum (InvestigationExecutionState)

Output only. The execution state of the investigation.
error

object (Status)

Output only. The error if the investigation run failed. This field will only be set if executionState is INVESTIGATION_EXECUTION_STATE_FAILED.
operation

string

Output only. The resource name of the Run operation most recently performed on the investigation, of the form: projects/{projectNumber}/locations/{locationId}/operations/{operation_id}
title

string

Optional. Human-readable display title for the investigation.
observations

map (key: string, value: object (Observation))

Optional. Observations about the project state that comprise the contents of the investigation.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
observerStatuses

map (key: string, value: object (ObserverStatus))

Optional. Statuses of observers which have been invoked in order to run the investigation.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

InvestigationAnnotations

Additional annotations on an Investigation.

JSON representation 
{
  "supportCase": string,
  "revisionLastRunInterval": {
    object (Interval)
  },
  "pagePath": string,
  "extrasMap": {
    string: string,
    ...
  }
}
Fields
supportCase

string

Optional. A support case ID associated with the investigation.
revisionLastRunInterval

object (Interval)

Output only. The interval during which the investigation was last executed.
pagePath

string

Optional. The path of a web page from which this investigation was created.
extrasMap

map (key: string, value: string)

Optional. Additional client-specified annotations.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

Interval

Represents a time interval, encoded as a Timestamp start (inclusive) and a Timestamp end (exclusive).

The start must be less than or equal to the end. When the start equals the end, the interval is empty (matches no time). When both start and end are unspecified, the interval matches any time.

JSON representation 
{
  "startTime": string,
  "endTime": string
}
Fields
startTime

string (Timestamp format)

Optional. Inclusive start of the interval.

If specified, a Timestamp matching this interval will have to be the same or after the start.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
endTime

string (Timestamp format)

Optional. Exclusive end of the interval.

If specified, a Timestamp matching this interval will have to be before the end.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".

InvestigationExecutionState

The execution state of an investigation.

Enums
INVESTIGATION_EXECUTION_STATE_UNSPECIFIED Default value. This value is unused.
INVESTIGATION_EXECUTION_STATE_RUNNING The investigation is being executed.
INVESTIGATION_EXECUTION_STATE_MODIFIED The investigation has not yet been executed since it was last updated.
INVESTIGATION_EXECUTION_STATE_FAILED The investigation execution has completed, but the execution has failed.
INVESTIGATION_EXECUTION_STATE_COMPLETED All execution tasks have completed and the investigation is at rest.

Observation

An observation represents a single fact about the state of the system under investigation, along with a ranking of its relevance.

JSON representation 
{
  "id": string,
  "timeIntervals": [
    {
      object (Interval)
    }
  ],
  "title": string,
  "observationType": enum (ObservationType),
  "observerType": enum (ObserverType),
  "text": string,
  "data": {
    object
  },
  "dataUrls": {
    string: string,
    ...
  },
  "knowledgeUrls": {
    string: string,
    ...
  },
  "baseObservations": [
    string
  ],
  "relevantResources": [
    string
  ],
  "recommendation": string,
  "systemRelevanceScore": number,
  "relevanceOverride": enum (UserRelevance),
  "observationCompletionState": enum (ObservationCompletionState),
  "observedNormalOperation": boolean
}
Fields
id

string

Output only. Uniquely identifies this observation. This is always equal to the map key of this observation in the parent investigation.
timeIntervals[]

object (Interval)

Optional. When this observation occurred.
title

string

Optional. Human-readable display title for the observation.
observationType

enum (ObservationType)

Required. The type of the observation.
observerType

enum (ObserverType)

Required. The type of observer that produced this observation.
text

string

Optional. Natural-language or markdown text explaining the observation.
data

object (Struct format)

Optional. A structured representation of the observation. This is not required or guaranteed to conform to any particular schema.
dataUrls

map (key: string, value: string)

Optional. URLs pointing to evidence in support of this observation. Maps from a human-readable description to a URL.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
knowledgeUrls

map (key: string, value: string)

Optional. URLs pointing to reference knowledge related to this observation. Maps from a human-readable description to a URL.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
baseObservations[]

string

Optional. The IDs of other observations that this observation is based on. For example, a hypothesis observation will record the observations that support that hypothesis.
relevantResources[]

string

Optional. The Google Cloud resources relevant to the observation. These should be fully qualified resource URIs, e.g.: "//compute.googleapis.com/projects/my-project/zones/us-central1-a/instances/my-instance"
recommendation

string

Optional. Natural language or markdown text which describes a recommended action to remediate the root cause or further investigate the issue.
systemRelevanceScore

number

Optional. How relevant the observer perceives this observation to be. This is used to rank observations in generating hypotheses. The system outputs observations in the range [-1, 1], where -1 means completely irrelevant, 0 means neutral, and 1 means complete confidence in its relevance.
relevanceOverride

enum (UserRelevance)

Optional. The user's relevance judgement.
observationCompletionState

enum (ObservationCompletionState)

Optional. Represents whether the observation is fully formed and able to be used to draw conclusions.
observedNormalOperation

boolean

Optional. If false or unspecified, this observation gives information about an issue or root cause. If true, this observation indicates that a system was observed to be operating normally. Such negative results can be useful diagnostic findings, and this field has no correlation with the relevance score.

ObservationType

This represents the type of data constituting an observation. This is independent of the provenance: a log might be explicitly provided by the user, or extracted via AI, or spotted by a runbook.

Enums
OBSERVATION_TYPE_UNSPECIFIED Default value.
OBSERVATION_TYPE_CLOUD_LOG The text of this observation is a log entry.
OBSERVATION_TYPE_CLOUD_METRIC The content of this observation is a metric or group of metrics.
OBSERVATION_TYPE_CAIS_CONFIG A config
OBSERVATION_TYPE_CAIS_CONFIG_DIFF A change of config
OBSERVATION_TYPE_CLOUD_ALERT An alert
OBSERVATION_TYPE_CICD_EVENT An event from a continuous integration system, e.g. prober failure.
OBSERVATION_TYPE_TEXT_DESCRIPTION Free text input, such as the initial user input. Can be markdown.
OBSERVATION_TYPE_HYPOTHESIS This is for [tentative] conclusions drawn by the system. These can become inputs to a subsequent revision. In this case the recommendations will be used, but not the remediation.
OBSERVATION_TYPE_STRUCTURED_INPUT Structured input, e.g. runbook parameters put into a form
OBSERVATION_TYPE_COMPOSITE Used for an observation that includes more than one kind of evidence, such as a runbook output.
OBSERVATION_TYPE_OTHER Runbook output can be 'other' if none of the other types apply.
OBSERVATION_TYPE_LOG_THEME A theme discovered in the logs.
OBSERVATION_TYPE_CONFIG_ANALYSIS Signals output that includes a config analyzed by LLM.
OBSERVATION_TYPE_OUTAGE Signals output that includes an outage from PSH.
OBSERVATION_TYPE_KNOWLEDGE Text that provides knowledge about a particular user's problem. For example, error catalog instructions/external links, RAG etc.

ObserverType

This represents how the data got into the Investigation.

Enums
OBSERVER_TYPE_UNSPECIFIED Default value. Unused.
OBSERVER_TYPE_DIAGNOSTICS Diagnostics have an explicit notion of root causes, e.g. via runbooks.
OBSERVER_TYPE_SIGNALS Signals is for processing that doesn't have explicit root causes.
OBSERVER_TYPE_DETERMINISTIC_CODE This is for code that depends only on premises. In particular, error catalog lookups.
OBSERVER_TYPE_AI This is for AI inferences that depend only on observations listed as premises.
OBSERVER_TYPE_USER User-input observation, including answers to clarifications. All user-specified observations will be coerced to this type.
OBSERVER_TYPE_ALERT An observation from an alert.

UserRelevance

This represents a user's expressed relevance judgement of an observation.

Enums
USER_RELEVANCE_UNSPECIFIED The user has not marked this observation as relevant or irrelevant.
USER_RELEVANCE_PROMOTED The user marked this observation as relevant.
USER_RELEVANCE_REJECTED The user marked this observation as irrelevant.

ObservationCompletionState

Determines if the observation is fully formed and complete.

Enums
OBSERVATION_COMPLETION_STATE_UNSPECIFIED Default value. Will be treated as COMPLETE.
OBSERVATION_COMPLETION_STATE_COMPLETE This observation is fully formed.
OBSERVATION_COMPLETION_STATE_INCOMPLETE This observation is missing some information, or needs further processing by a different observer. This type of observation may be discarded in future investigation runs.

ObserverStatus

An ObserverStatus represents the status of an observer at a particular point during execution of an investigation.

JSON representation 
{
  "observer": string,
  "observerExecutionState": enum (ObserverExecution),
  "observerDisplayName": string,
  "updateTime": string,
  "startTime": string,
  "updateComment": string,
  "observerErrors": [
    {
      object (Status)
    }
  ]
}
Fields
observer

string

Output only. Uniquely identifies this observer. This is always equal to the map key of this observer in the parent investigation.
observerExecutionState

enum (ObserverExecution)

Optional. The current execution state of the observer.
observerDisplayName

string

Required. Human-readable display name for the observer.
updateTime

string (Timestamp format)

Optional. The time when the observer last updated the investigation. If the observerExecutionState is COMPLETE or FAILED, this is the time when the observer finished its observation.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
startTime

string (Timestamp format)

Optional. The time when the observer started its observation.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
updateComment

string

Optional. A status update from the observer.
observerErrors[]

object (Status)

Optional. An error that blocked an observer from making a particular observation.

ObserverExecution

The state of the observer.

Enums
OBSERVER_EXECUTION_UNSPECIFIED The observer state is unspecified.
OBSERVER_EXECUTION_NOT_STARTED The investigation has not yet started.
OBSERVER_EXECUTION_RUNNING The investigation is running and this observer is runnable or running.
OBSERVER_EXECUTION_COMPLETE The observer has finished without an internal error.
OBSERVER_EXECUTION_FAILED The observer tried to run but failed due to an error. This is specific to a component and may be rendered in the UI if the observation is shown, as very low priority.
OBSERVER_EXECUTION_BLOCKED The observer is blocked pending an input.
OBSERVER_EXECUTION_INVESTIGATION_BLOCKED The observer reports an error that blocks or severely impacts the investigation, for example CAIS or logging disabled. Should be rendered in the UI prominently.
OBSERVER_EXECUTION_INVESTIGATION_DEGRADED The observer reports an error that degrades the investigation, may require user to escalate or re-run the investigation after mitigating the cause.

Methods

create

 Creates a new Investigation in a given project.

delete

 Deletes a single Investigation.

get

 Gets details of a single Investigation.

getIamPolicy

 Gets the access control policy for a resource.

list

 Lists Investigations in a given project and location.

patch

 Updates the parameters of a single Investigation.

setIamPolicy

 Sets the access control policy on the specified resource.

testIamPermissions

 Returns permissions that a caller has on the specified resource.