REST Resource: projects.locations.investigations

Resource: Investigation

Message describing Investigation object Next Id: 24

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)
    },
    ...
  },
  "clarificationsNeeded": {
    string: {
      object (ClarificationNeeded)
    },
    ...
  }
}
Fields
name

string

Identifier. name of resource
createTime

string (Timestamp format)

Output only. [Output only] Create time stamp

Uses RFC 3339, where generated output will always be Z-normalized and uses 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. [Output only] Update time stamp

Uses RFC 3339, where generated output will always be Z-normalized and uses 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. Labels as key value pairs

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

string

Output only. [Output only] Current revision of the investigation
revisionIndex

integer

Output only. [Output only] Index of the current revision of the investigation. 1-based.
revisionPredecessor

string

Optional. The name of the revision that was this revision's predecessor. The UI, for example, will set this to the existing revision when when a new revision is created due to an edit.
annotations

object (InvestigationAnnotations)

Optional. Annotations on the investigation. Unlike labels, these may carry semantic meaning in running the investigation, and will not be read by other systems such as billing.
executionState

enum (InvestigationExecutionState)

Output only. [Output only] The execution state of this investigation.
error

object (Status)

Output only. [Output only] If the investigation execution state is FAILED, this field will contain the error message.
operation

string

Output only. The Run operation most recently performed on the investigation.
title

string

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

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

Optional. A map from observation ID to the observation. This is a map so that we can cleanly overwrite old observations with the version from the latest revision. See Observation for guidance on choosing IDs.

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. Plural version of above. Code will transition to this over time.

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

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

Optional. Questions that the system needs to ask the user. The results will be passed back by the UI as new Observations. The ID for those observations will be the key of the entry in the clarificationsNeeded map.

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

InvestigationAnnotations

Additional user-defined annotations on an Investigation. There are some pre-defined ones, and a map for new applications to add their own.

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

boolean

Output only. Follow-up is required to continue the investigation. Generally set to true by the troubleshooter and false when the questions have been answered.
extrasMap

map (key: string, value: string)

Optional. Additional annotations required by applications. These will not be redacted and should NOT contain any CCC/PII.

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

object (Interval)

Optional. Start/end time when the revision was last run.

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 uses 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 uses 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 the symptom 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 is the basic unit of interchange between user and system, or between different components of the system. It is the element that has a relevance. They should therefore be relatively small; if you expect users to react to "part" of an observation, it should be broken up into smaller observations. A particular runbook run, a particular user parameter input, a particular interesting log entry might all be separate observations. This means there might be dozens or hundreds in an investigation. Next Id: 26

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

Required. Uniquely identifies this observation. Should depend on the 'core content' of the observation, but not e.g. on the relevance. Should not depend on anything that can vary unpredictably from revision to revision to run. This is also the map key in the parent Investigation. They should be hierarchical with '.' as the separator starting with the name of the observer. So for instance, diagnostics.runbook.ABC, or signals.logs, or user.input.2 It should be usable as a URL component. (Case-insensitive [a-z0-9-._]+) These will not be rendered for users, but will be visible in the data model. They will be used by Google engineers to localize bugs so should be semi-readable.
timeIntervals[]

object (Interval)

Optional. When this observation occurred. Observations should have at least one time range so that the observations can be shown on a timeline and so we can find related events. For a repeated but not continuous event, it is appropriate to have more than one range. The UI may combine these.
title

string

Optional. The label shown in the UI. This need not be unique within an investigation. However, it should be specific and less than 80 characters so that the user can easily scan across many observations. "Nettools pod configured with ALL capabilities dropped" is much better than "Interesting pod configuration".
observationType

enum (ObservationType)

Required. The type of the observation (e.g. log, metric, etc.)
observerType

enum (ObserverType)

Required. The origin of the data, e.g. user, system code, LLM etc.
text

string

Optional. Natural-language [markdown] text associated with the observation. This is the core content, not a metadata description.
data

object (Struct format)

Optional. A structured representation of the observation, as chosen by the observer. Optional. If present, an observer SHOULD also supply a text description of the observation to facilitate processing by an LLM and rendering in the UI.
dataUrls

map (key: string, value: string)

Optional. A map from human-readable names to URLs for supportive evidence. The map key will be rendered as URL anchor text. Fill this in whenever an observation depends on a thing outside the system. For example, logging/metrics/etc query that can regenerate the observation.

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

map (key: string, value: string)

Optional. A map from human-readable names to URLs for documentation.

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 conclusion observation will record the observations that were used to generate it. An extracted param will record what it was extracted from. The graph of premises and conclusions will be acyclic within a revision.
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 [markdown] text which describes a recommended action to remediate / fix the root cause. This is free form and not machine- processed at this time. A recommendation can be: - High-level remediation descriptions - Specific and tactical remediation steps with executable commands - Specific and tactical troubleshooting steps for where to investigate next with executable commands
systemRelevanceScore

number

Optional. How relevant this observation is to the investigation, as inferred by the system. Optional. Should be in the range [-1, 1]. For OBSERVATION_TYPE_HYPOTHESIS, represents confidence in the explanation. Only root-cause hypotheses are ranked against each other. For other ObservationTypes, this represents a relevance score, and they are ranked against each other. A value of 0 is neutral.
relevanceOverride

enum (UserRelevance)

Optional. The user's relevance judgement.
observationCompletionState

enum (ObservationCompletionState)

Optional. An ObservationCompletionState represents whether the emitted observation is fully formed and should be shown the to the user. This is intended to allow hiding observations that are in an intermediate state.
observedNormalOperation

boolean

Optional. Whether this observation gives us information about an issue / root cause (false) or indicates normal operation (true). This is conceptually different from the relevance and used differently. An irrelevant observation should be hidden from the LLM and also the user. A relevant observation of a problem should be shown as an observation and should motivate a hypothesis. A relevant finding of normalcy may / may not be shown in the UI, but should be used by the LLM to filter out hypotheses that are refuted by the finding.

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 Do not use. Specify the type of the observation. Add a new enum if you need it.
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 Do not use. Specify where the observation came from. Add a new enum if you need it.
OBSERVER_TYPE_DIAGNOSTICS We separate these for internal attribution reasons. 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 made along the way that depend only on observations listed as premises.
OBSERVER_TYPE_USER User-input observation, including answers to clarifications.
OBSERVER_TYPE_ALERT An observation from an external-to-GCA alert.

UserRelevance

This represents the user's expressed relevance judgement of an observation. The UI will be something like thumbs-up or thumbs-down.

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. As a side effect, this determines if the observation is shown to the user.

Enums
OBSERVATION_COMPLETION_STATE_UNSPECIFIED Do not use.
OBSERVATION_COMPLETION_STATE_COMPLETE This observation is fully formed and should be shown the to the user.
OBSERVATION_COMPLETION_STATE_INCOMPLETE This observation is missing some information, or needs further processing by a different observer. This type of Observation should not be persisted into future investigation revisions.

ObserverStatus

An ObserverStatus represents the status of an observer at a particular point during execution of an investigation. NOTE: By default, nothing in this message is redacted. Components should NOT put PII / CCC here except where redacted. Next Id: 13

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

string

Required. The ID of the observer that this status is for. Observer IDs should be human-readable and hierarchical, e.g. "signals.logs.firewall_rules" or "diagnostics.error_catalog".
observerExecutionState

enum (ObserverExecution)

Optional. The current execution state of the observer.
observerDisplayName

string

Required. The name to show the user when describing this observer. Note that the UI might replace this with an internationalized counterpart, so it should not be generated dynamically. Required so that the user can see which observer (e.g. runbook) the system is talking about.
updateTime

string (Timestamp format)

Optional. The time when the status was updated. Optional because the observer is responsible for setting it. Becomes endTime when the observer is complete.

Uses RFC 3339, where generated output will always be Z-normalized and uses 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. Optional because the observer is responsible for setting it. When the observer is finished, the difference between this and updateTime is the observer run time.

Uses RFC 3339, where generated output will always be Z-normalized and uses 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. May be logged for debugging purposes. These may be shown to users. A good update would be "parameters matched, queued for execution" or "checked log file 2/5".
observerErrors[]

object (Status)

Optional. An error within the Investigation system that blocked an observer from making a particular observation. The error string here will be shown to users. Repeated because an observer might lack multiple permissions.

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.

AbsentObservation

An identifier of an observation that is needed. Typically a parameter but extensible to other cases.

JSON representation 
{

  // Union field t can be only one of the following:
  "param": string,
  "generalMissingObservation": {
    object (GeneralAbsentObservation)
  },
  "pendingObservation": string
  // End of list of possible types for union field t.
}
Fields
Union field t. There is more than one kind of missing params. t can be only one of the following:
param

string

Optional. A runbook parameter.
generalMissingObservation

object (GeneralAbsentObservation)

Optional. A missing observation that the user could supply that is not a runbook parameter.
pendingObservation

string

Optional. An observation that is not yet created that an observer should create by running. This might prompt the system to execute a runbook.

GeneralAbsentObservation

An absent observation that is not a runbook parameter.

JSON representation 
{
  "id": string,
  "title": string,
  "validationRegex": string
}
Fields
id

string

Optional. The ID of the missing observation.
title

string

Optional. The title to display in the UI
validationRegex

string

Optional. The regex that the answer must match. Must conform to JavaScript's regular expression string pattern syntax. See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/RegExp#syntax

ObserverLogEntry

A log entry from an observer.

JSON representation 
{
  "logTime": string,
  "logMessage": string,
  "logSeverity": enum (LogSeverity),
  "data": {
    object
  },
  "sensitiveData": {
    object
  }
}
Fields
logTime

string (Timestamp format)

Required. The time when the log was created.

Uses RFC 3339, where generated output will always be Z-normalized and uses 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".
logMessage

string

Required. The human-readable message.
logSeverity

enum (LogSeverity)

Required. The severity of the log message.
data

object (Struct format)

Optional. Any additional data, such as an RPC error. Warning: like the rest of ObserverStatus, the contents of this field may be read for Observer debugging purposes. For sensitive data, use sensitiveData instead.
sensitiveData

object (Struct format)

Optional. Any additional data that may contain sensitive information about the project under investigation. This field will be redacted when the ObserverStatus is read for debugging purposes.

LogSeverity

The severity of the event described in a log entry, expressed as one of the standard severity levels listed below. For your reference, the levels are assigned the listed numeric values. The effect of using numeric values other than those listed is undefined.

You can filter for log entries by severity. For example, the following filter expression will match log entries with severities INFO, NOTICE, and WARNING:

severity > DEBUG AND severity <= WARNING

If you are writing log entries, you should map other severity encodings to one of these standard levels. For example, you might map all of Java's FINE, FINER, and FINEST levels to LogSeverity.DEBUG. You can preserve the original severity level in the log entry payload if you wish.

Enums
DEFAULT (0) The log entry has no assigned severity level.
DEBUG (100) Debug or trace information.
INFO (200) Routine information, such as ongoing status or performance.
NOTICE (300) Normal but significant events, such as start up, shut down, or a configuration change.
WARNING (400) Warning events might cause problems.
ERROR (500) Error events are likely to cause problems.
CRITICAL (600) Critical events cause more severe problems or outages.
ALERT (700) A person must take an action immediately.
EMERGENCY (800) One or more systems are unusable.

ClarificationNeeded

A clarification needed by the system.

JSON representation 
{
  "runbookParameter": {
    object (RunbookParameter)
  },
  "generalMissingObservation": {
    object (GeneralAbsentObservation)
  },
  "parentObserverNames": [
    string
  ]
}
Fields
runbookParameter

object (RunbookParameter)

Optional. The result of a clarification is an observation. A runbook parameter that the user needs to provide.
generalMissingObservation

object (GeneralAbsentObservation)

Optional. A missing observation that is not a runbook parameter.
parentObserverNames[]

string

Optional. The display names of the observers that asked for this clarification. The UI will group by these names.

RunbookParameter

Parameter metadata for runbooks updated by the Diagnostic task.

JSON representation 
{
  "id": string,
  "displayName": string,
  "description": string,
  "exampleValues": [
    string
  ],
  "value": string,
  "associatedAssetTypes": [
    string
  ]
}
Fields
id

string

Optional. The name of the parameter.
displayName

string

Optional. The name of the parameter to be displayed to the user.
description

string

Optional. The description of the parameter.
exampleValues[]

string

Optional. Examples of the parameter value.
value

string

Optional. The value of the parameter if available.
associatedAssetTypes[]

string

Optional. If present, a list of resource types that this parameter might be. For example, "compute.googleapis.com/Instance".

Methods

create

 Creates a new Investigation in a given project and location.

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.