# Insights

Recommender uses machine learning to provide detailed and high quality
*insights* . Insights are findings that you can use to proactively focus on
important patterns in resource usage. You can use insights independently from
recommendations. Some insights link to
[recommendations](https://docs.cloud.google.com/recommender/docs/key-concepts.md.txt#recommendations) and provide
evidence for the associated recommendations.

This page describes key concepts for interpreting and using insights.

## Insight types

Each insight has a specific *insight type*. Insight types are specific to a
single Google Cloud product and resource type. A single product can have
multiple insight types, where each provides a different type of insight for a
different resource.

Each insight type has a unique insight type ID that identifies the service
internally. You use the insight type ID when interacting with insights using the
Recommender [`gcloud` commands](https://docs.cloud.google.com/sdk/gcloud/reference/recommender), or
the [REST](https://docs.cloud.google.com/recommender/docs/reference/rest.md.txt) or
[RPC](https://docs.cloud.google.com/recommender/docs/reference/rpc.md.txt) APIs.

For more information, see [Insight types](https://docs.cloud.google.com/recommender/docs/insights/insight-types.md.txt).

## Insights

An *insight* is a machine-generated finding that may be linked to one or more
recommendations. An insight has the following core attributes:

- [Name](https://docs.cloud.google.com/recommender/docs/insights/using-insights.md.txt#name)
- [Description](https://docs.cloud.google.com/recommender/docs/insights/using-insights.md.txt#description)
- [Insight Subtype](https://docs.cloud.google.com/recommender/docs/insights/using-insights.md.txt#insight_subtype)
- [Content](https://docs.cloud.google.com/recommender/docs/insights/using-insights.md.txt#content)
- [Category](https://docs.cloud.google.com/recommender/docs/insights/using-insights.md.txt#category)
- [Target Resources](https://docs.cloud.google.com/recommender/docs/insights/using-insights.md.txt#target_resources)
- [State Info](https://docs.cloud.google.com/recommender/docs/insights/using-insights.md.txt#state_info)
- [Etag](https://docs.cloud.google.com/recommender/docs/insights/using-insights.md.txt#etag)
- [Severity](https://docs.cloud.google.com/recommender/docs/insights/using-insights.md.txt#severity)
- [Last Refresh Time](https://docs.cloud.google.com/recommender/docs/insights/using-insights.md.txt#last_refresh_time)
- [Observation Period](https://docs.cloud.google.com/recommender/docs/insights/using-insights.md.txt#observation_period)
- [Recommendation reference](https://docs.cloud.google.com/recommender/docs/insights/using-insights.md.txt#recommendation_reference)

### Name

The insight name is stored in the `name` field of the Insight entity. It has
the following format:

```
projects/TARGET_PROJECT_ID/locations/LOCATION/insightTypes/INSIGHT_TYPE_ID/insights/INSIGHT_ID
```

where:

- <var translate="no">TARGET_PROJECT_ID</var> is the ID of the project where the insight was generated.
- <var translate="no">LOCATION</var> is the Google Cloud [location](https://cloud.google.com/about/locations) where resources associated with the insight are located (for example, `global` or `us-central1-a`)
- <var translate="no">INSIGHT_TYPE_ID</var> is the fully-qualified insight type ID (for example, `google.compute.firewall.Insight`)
- <var translate="no">INSIGHT_ID</var> is a unique ID for the insight

### Description

This is human-readable summary of the insight. It is only available in
English.

### Insight Subtype

Each insight type may support multiple subtypes. The content schema is stable
for a given subtype.

### Content

Structured fields that include insight details. Content schema is determined by
insight type and subtype. For example, `"grantedPermissionsCount": "1000"`

### Category

Similar to [impacts](https://docs.cloud.google.com/recommender/docs/key-concepts.md.txt#impact) for recommendations,
there are categories for insights:

- `COST`
- `SECURITY`
- `PERFORMANCE`

### Target Resources

Fully qualified resource names of the Google Cloud resources the insight is targeting.

### State Info

#### State

Insights go through multiple state transitions after they are proposed:

- `ACTIVE`, which means that the insight has been generated, but no actions have been taken in response. Content for active insights is updated when the underlying data changes. Active insights can be marked `DISMISSED` OR `ACCEPTED`.
- `ACCEPTED`, which means that some action has been taken based on the insight. Insights become accepted when an associated recommendation has been marked `CLAIMED`, `SUCCEEDED`, or `FAILED`. Insights can also be accepted directly. Content for accepted insights is immutable. Accepted insights are retained for 90 days from the time of the state change.
- `DISMISSED`, which means that the insight has been dismissed without taking any action based on it. Content for dismissed insights is updated when the underlying data changes.

#### State Metadata

When directly marking an insight ACCEPTED, you can include additional metadata
about the operation with state metadata. The metadata is specified as
`key:value` pairs. Updates to the state metadata field overwrite any existing
state metadata.

### Etag

An *etag* is a unique fingerprint that identifies the current state of an
insight. Each time the insight changes, a new etag value is assigned.  

In order to change insight state, you must provide the etag of the existing
insight. This makes sure that any operations are performed only if the insight
has not changed since you last retrieved it.

### Severity

A [*severity*](https://docs.cloud.google.com/recommender/docs/reference/rest/v1/billingAccounts.locations.insightTypes.insights.md.txt#severity)
for an insight indicates the likelihood of one of the following [impacts](https://docs.cloud.google.com/recommender/docs/key-concepts.md.txt#impact):

- An outage (for a performance impact)
- A compromise (for a security impact)
- An overspend (for a cost impact)
- A mismanagement (for a manageability impact)

This field comes with values `CRITICAL`, `HIGH`, `MEDIUM`, and `LOW` with `LOW` set as the
default severity.
Each [insight type](https://docs.cloud.google.com/recommender/docs/insights/insight-types.md.txt) can have its own
severity strategy defined.

### Last Refresh Time

The last refresh time indicates the freshness of the data used to generate the
insight.

### Observation Period

Observation period is the time period leading up to the insight. The source data
used to generate the insight ends at`last_refresh_time` and begins at
`last_refresh_time` minus `observation_period`.

### Recommendation reference

Reference to an associated
[recommendation](https://docs.cloud.google.com/recommender/docs/key-concepts.md.txt#recommendations). References
link insights with their associated recommendations. This field is empty when
there are no recommendations derived from the insight.