This page explains how to use Cloud Monitoring to view usage metrics for your
service accounts and service account keys. These metrics let you view and track
usage patterns, which can help you identify anomalies, either automatically or
manually.
Service accounts and service account keys appear in these metrics if they are
used to call any Google API, including APIs that are not part of Google Cloud.
The metrics include both successful and failed API calls. For example, if an API
call fails because the caller is not authorized to call that API, or because the
request referred to a resource that does not exist, the service account or key
that was used for that API call appears in the metrics.
Service account keys also appear in these metrics if a system lists the keys
while attempting to authenticate a request, even if the system doesn't use
the key to authenticate the request. This behavior is
most common when using
signed URLs for Cloud Storage
or when authenticating to third-party applications. As a
result it is possible to see usage metrics for keys that have not been used for
authentication.
Monitoring retains service account metrics for
6 weeks. If
you need to access data for a longer time period, you can periodically export
the results to BigQuery. For more information, see
Monitoring metric export
in the Solutions
documentation.
After you use a service account or service account key, usage metrics are
usually available within a few minutes.
Before you begin
Required roles
To get the permissions that you need to view recent usage for service accounts and keys,
ask your administrator to grant you the
Monitoring Viewer
(
roles/monitoring.viewer
) IAM role on the project.
For more information about granting roles, see
Manage access
.
You might also be able to get
the required permissions through
custom
roles
or other
predefined
roles
.
View usage metrics for all service accounts or keys
To view the usage metrics for your service accounts or service account keys,
follow these steps:
Console
To view the metrics for a monitored resource by using the
Metrics Explorer, do the following:
-
In the Google Cloud console, go to the
leaderboard
Metrics explorer
page:
Go to
Metrics explorer
If you use the search bar to find this page, then select the result whose subheading is
Monitoring
.
- In the
Metric
element, expand the
Select a metric
menu,
enter
IAM Service Account
in the filter bar, and then use the submenus to select a specific resource type and metric:
- In the
Active resources
menu, select
IAM Service Account
.
- In the
Active metric categories
menu, select
Service_account
.
- In the
Active metrics
menu, select a service account metric.
The following metrics are available within your selected time interval:
- For service account usage metrics,
select
Service account authentication events
.
- For service account key usage metrics,
select
Service account key authentication events
.
- Click
Apply
.
To remove time series from the display, use the
Filter
element
.
To combine time series, use the menus on the
Aggregation
element
.
For example, to display the CPU utilization for your VMs, based on their zone, set the
first menu to
Mean
and the second menu to
zone
.
All time series are displayed when the first menu of the
Aggregation
element is set
to
Unaggregated
. The default settings for the
Aggregation
element
are determined by the metric type you selected.
- For quota and other metrics that report one sample per day, do the following:
- In the
Display
pane,
set the
Widget type
to
Stacked bar chart
.
- Set the time period to at least one week.
REST
The Cloud Monitoring API API's
timeSeries.list
method allows you to access usage metrics programmatically.
Before using any of the request data,
make the following replacements:
HTTP method and URL:
GET https://monitoring.googleapis.com/v3/projects/
PROJECT_ID
/timeSeries?filter=metric.type%3D%22
METRIC_TYPE
%22&interval.endTime=
END_TIME
&interval.startTime=
START_TIME
To send your request, expand one of these options:
curl (Linux, macOS, or Cloud Shell)
Execute the following command:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://monitoring.googleapis.com/v3/projects/
PROJECT_ID
/timeSeries?filter=metric.type%3D%22
METRIC_TYPE
%22&interval.endTime=
END_TIME
&interval.startTime=
START_TIME
"
PowerShell (Windows)
Execute the following command:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://monitoring.googleapis.com/v3/projects/
PROJECT_ID
/timeSeries?filter=metric.type%3D%22
METRIC_TYPE
%22&interval.endTime=
END_TIME
&interval.startTime=
START_TIME
" | Select-Object -Expand Content
APIs Explorer (browser)
Open the
method reference page
.
The APIs Explorer panel opens on the right side of the page.
You can interact with this tool to send requests.
Complete any required fields and click
Execute
.
For more information about programmatically reading usage metrics, see
Reading metric data
in the
Monitoring documentation.
View usage metrics for a single service account
To view usage metrics for a single service account, follow these steps:
Console
In the Google Cloud console, go to the
Service Accounts
page.
Go to Service Accounts
Select the project that contains your service account.
Click the email address of your service account.
Click the
Metrics
tab. The
Authentication traffic
chart shows
the usage metrics for the service account.
Optional: To view the chart on the
Metrics explorer
page, which offers
additional filtering and viewing options, click
more_vert
>
View in Metrics Explorer
.
REST
The Cloud Monitoring API's
timeSeries.list
method , when used with specific filters, allows you to get usage metrics for
a single service account. You can then use those metrics to determine when the account was last
used.
Before using any of the request data,
make the following replacements:
HTTP method and URL:
GET https://monitoring.googleapis.com/v3/projects/
PROJECT_ID
/timeSeries?filter=metric.type%3D%22iam.googleapis.com%2Fservice_account%2Fauthn_events_count%22%20AND%20resource.labels.unique_id%3D%22
SERVICE_ACCOUNT_ID
%22&interval.endTime=
END_TIME
&interval.startTime=
START_TIME
To send your request, expand one of these options:
curl (Linux, macOS, or Cloud Shell)
Execute the following command:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://monitoring.googleapis.com/v3/projects/
PROJECT_ID
/timeSeries?filter=metric.type%3D%22iam.googleapis.com%2Fservice_account%2Fauthn_events_count%22%20AND%20resource.labels.unique_id%3D%22
SERVICE_ACCOUNT_ID
%22&interval.endTime=
END_TIME
&interval.startTime=
START_TIME
"
PowerShell (Windows)
Execute the following command:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://monitoring.googleapis.com/v3/projects/
PROJECT_ID
/timeSeries?filter=metric.type%3D%22iam.googleapis.com%2Fservice_account%2Fauthn_events_count%22%20AND%20resource.labels.unique_id%3D%22
SERVICE_ACCOUNT_ID
%22&interval.endTime=
END_TIME
&interval.startTime=
START_TIME
" | Select-Object -Expand Content
APIs Explorer (browser)
Open the
method reference page
.
The APIs Explorer panel opens on the right side of the page.
You can interact with this tool to send requests.
Complete any required fields and click
Execute
.
The response contains a
timeSeries
object
with all of the recent authentication events for the specified service account.
View usage metrics for a single service account key
To view usage metrics for a single service account key, follow these steps:
Console
In the Google Cloud console, go to the
Service Accounts
page.
Go to Service Accounts
Select the project that contains the service account associated with
your key.
Click the email address of the service account associated with your key.
Click the
Metrics
tab. The
Authentication traffic per key
chart
shows usage metrics for all keys associated with the service account.
In the chart legend, click the ID of the service account key that you want to
view usage metrics for. The chart updates to show metrics for only that
service account key.
Optional: To view the chart on the
Metrics explorer
page, which offers
additional filtering and viewing options, click
more_vert
>
View in Metrics Explorer
.
REST
First, get the service account key's ID.
List the service account keys:
The
projects.serviceAccounts.keys.list
method lists all of the service account keys for a service account.
Before using any of the request data,
make the following replacements:
PROJECT_ID
: Your Google Cloud project
ID. Project IDs are alphanumeric strings, like
my-project
.
SA_NAME
: The name of the service account whose keys you want to list.
KEY_TYPES
: Optional. A comma-separated list of key types that you want
to include in the response. The key type indicates whether a key is user-managed
(
USER_MANAGED
) or system-managed (
SYSTEM_MANAGED
). If left blank, all
keys are returned.
HTTP method and URL:
GET https://iam.googleapis.com/v1/projects/
PROJECT_ID
/serviceAccounts/
SA_NAME
@
PROJECT_ID
.iam.gserviceaccount.com/keys?keyTypes=
KEY_TYPES
To send your request, expand one of these options:
curl (Linux, macOS, or Cloud Shell)
Execute the following command:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://iam.googleapis.com/v1/projects/
PROJECT_ID
/serviceAccounts/
SA_NAME
@
PROJECT_ID
.iam.gserviceaccount.com/keys?keyTypes=
KEY_TYPES
"
PowerShell (Windows)
Execute the following command:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://iam.googleapis.com/v1/projects/
PROJECT_ID
/serviceAccounts/
SA_NAME
@
PROJECT_ID
.iam.gserviceaccount.com/keys?keyTypes=
KEY_TYPES
" | Select-Object -Expand Content
APIs Explorer (browser)
Open the
method reference page
.
The APIs Explorer panel opens on the right side of the page.
You can interact with this tool to send requests.
Complete any required fields and click
Execute
.
You should receive a JSON response similar to the following:
{
"keys": [
{
"name": "projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com/keys/90c48f61c65cd56224a12ab18e6ee9ca9c3aee7c",
"validAfterTime": "2020-03-04T17:39:47Z",
"validBeforeTime": "9999-12-31T23:59:59Z",
"keyAlgorithm": "KEY_ALG_RSA_2048",
"keyOrigin": "GOOGLE_PROVIDED",
"keyType": "USER_MANAGED"
},
{
"name": "projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com/keys/e5e3800831ac1adc8a5849da7d827b4724b1fce8",
"validAfterTime": "2020-03-31T23:50:09Z",
"validBeforeTime": "9999-12-31T23:59:59Z",
"keyAlgorithm": "KEY_ALG_RSA_2048",
"keyOrigin": "GOOGLE_PROVIDED",
"keyType": "USER_MANAGED"
},
{
"name": "projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com/keys/b97699f042b8eee6a846f4f96259fbcd13e2682e",
"validAfterTime": "2020-05-17T18:58:13Z",
"validBeforeTime": "9999-12-31T23:59:59Z",
"keyAlgorithm": "KEY_ALG_RSA_2048",
"keyOrigin": "GOOGLE_PROVIDED",
"keyType": "USER_MANAGED",
"disabled": true
}
]
}
Use the metadata in the response to identify the key you want to track.
Then, copy the key's unique ID from the end of the
name
field.
The
name
field has the following format:
"name": "projects/
PROJECT_ID
/serviceAccounts/
SERVICE_ACCOUNT_EMAIL
/keys/
KEY_ID
"
The key's unique ID is everything after
keys/
.
For example, the unique ID in the following key name is
0f561cc41650ff521899de2fd653bd3de08e2da4
:
"name": "projects/my-project/serviceAccounts/my-account@my-project.iam.gserviceaccount.com/keys/0f561cc41650ff521899de2fd653bd3de08e2da4"
Then, use the ID to view usage metrics for the service account key.
The Cloud Monitoring API's
timeSeries.list
method , when used with specific filters, allows you to get usage metrics for
a single service account key. You can then use those metrics to determine when the key was last
used.
Before using any of the request data,
make the following replacements:
HTTP method and URL:
GET https://monitoring.googleapis.com/v3/projects/
PROJECT_ID
/timeSeries?filter=metric.type%3D%22iam.googleapis.com%2Fservice_account%2Fkey%2Fauthn_events_count%22%20AND%20metric.labels.key_id%3D%22
KEY_ID
%22&interval.endTime=
END_TIME
&interval.startTime=
START_TIME
To send your request, expand one of these options:
curl (Linux, macOS, or Cloud Shell)
Execute the following command:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://monitoring.googleapis.com/v3/projects/
PROJECT_ID
/timeSeries?filter=metric.type%3D%22iam.googleapis.com%2Fservice_account%2Fkey%2Fauthn_events_count%22%20AND%20metric.labels.key_id%3D%22
KEY_ID
%22&interval.endTime=
END_TIME
&interval.startTime=
START_TIME
"
PowerShell (Windows)
Execute the following command:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://monitoring.googleapis.com/v3/projects/
PROJECT_ID
/timeSeries?filter=metric.type%3D%22iam.googleapis.com%2Fservice_account%2Fkey%2Fauthn_events_count%22%20AND%20metric.labels.key_id%3D%22
KEY_ID
%22&interval.endTime=
END_TIME
&interval.startTime=
START_TIME
" | Select-Object -Expand Content
APIs Explorer (browser)
Open the
method reference page
.
The APIs Explorer panel opens on the right side of the page.
You can interact with this tool to send requests.
Complete any required fields and click
Execute
.
The response contains a
timeSeries
object
with all of the recent authentication events for the specified service account key.
Export metrics
You can use Monitoring to export your metrics
to BigQuery. Exporting metrics is useful for performing
long-term analysis because Monitoring only retains metrics for a
limited time.
For instructions, see
Monitoring metric export
in the Solutions documentation.
What's next