Access and use platform logs

Configure platform logs in Artifact Registry so that you can view information about successful and failed requests made to your Artifact Registry repositories. Platform logs are generated by Cloud Logging and can be viewed in the Logs Explorer. You can review your Artifact Registry platform logs to help troubleshoot failed requests, maintain records of successful requests, and view the number of downloads for an artifact.

A platform log is formatted as a LogEntry.

Overview

Artifact Registry generates platform logs for data plane API calls and control plane API calls. Control plane actions include repository management operations like creating repositories, editing repository descriptions, and deleting repositories, and artifact management actions such as listing artifacts, tagging artifacts, and deleting artifacts. Data plane actions include operations like pushing and pulling artifacts from Artifact Registry repositories.

Logs for both types of calls contain the following information:

Request details
Response details
Status
Labels
- Method name
- Resource name
- Resource location
- Operation ID (for long-running operations)
- Repository format (for repository resources)
- Repository mode (for repository resources)

In addition, logs for control plane API calls contain the following information:

HTTP Information
- Request method
- Request URL
- Request size (in bytes)
- Status
- Response size (in bytes)
- User agent
- Remote IP (client IP that issued the request)
- Protocol
- Referer
- Latency

You can view platform logs for Artifact Registry in the Logs Explorer.

Before you begin

Enable the Logging API.

Required roles

To get the permissions that you need to manage platform logs, ask your administrator to grant you the following IAM roles on your project:

Artifact Registry Admin (roles/artifactregistry.admin)
Logging Viewer (roles/logging.viewer)

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Enable platform logging

You can enable platform logging across your entire Google Cloud project or for a specific repository.

Enable platform logging for a project

To enable platform logging for your Google Cloud project, run the following command:

gcloud CLI

gcloud artifacts projects update --enable-platform-logs --severity=SEVERITY --location LOCATION --project PROJECT

curl

curl -v -H "Authorization: Bearer $(gcloud auth print-access-token)" -X PATCH -H "X-GFE-SSL: yes" -H "Content-Type: application/json" -d '{"name": "projects/'PROJECT'/locations/'LOCATION'/projectConfig", "platformLogsConfig": {"logging_state": "ENABLED", "severity_level": "SEVERITY"}}' "https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/projectConfig"

Where:

SEVERITY determines the type of actions that trigger Artifact Registry platform log creation. You can enter INFO, ERROR, or exclude the --severity field to create platform logs for all supported actions.
LOCATION is the location of your repository.
PROJECT is the project ID. If this flag is omitted, then the current or default project is used.

Enable platform logging for a repository

gcloud CLI

gcloud artifacts repositories update --enable-platform-logs --severity=SEVERITY REPOSITORY --location LOCATION --project PROJECT

curl

curl -v -H "Authorization: Bearer $(gcloud auth print-access-token)" -X PATCH \
-H "X-GFE-SSL: yes" -H "Content-Type: application/json" \
-d '{"name": "projects/'PROJECT'/locations/'LOCATION'/repositories/'REPOSITORY'", "platformLogsConfig": {"loggingState": "ENABLED", "severityLevel": "SEVERITY"}' \
"https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY?updateMask=platformLogsConfig"

Where:

SEVERITY determines the type of actions that trigger Artifact Registry platform log creation. You can enter INFO, ERROR, or exclude the --severity field to create platform logs for all supported actions.
REPOSITORY is the name of your repository in Artifact Registry.
LOCATION is the location of your repository.
PROJECT is the project ID. If this flag is omitted, then the current or default project is used.

Verify platform logging configuration

You can verify whether Artifact Registry platform logging is enabled in your project or for a specific repository.

Verify platform logging for a project

To verify whether Artifact Registry platform logging is enabled in your project, run the following command:

gcloud CLI

gcloud artifacts projects describe --location LOCATION --project PROJECT

curl

curl -v -H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/projectConfig"

Where:

LOCATION is the location of your repository.
PROJECT is the project ID. If this flag is omitted, then the current or default project is used.

The output is similar to the following:

{
  "name": "projects/PROJECT/locations/{"<var>LOCATION</var>"}}/projectConfig"
  "platformLogsConfig": {
    "loggingState": "ENABLED"
    "severityLevel": "INFO"
  }
}

Verify platform logging for a repository

To verify whether Artifact Registry platform logging is enabled in a repository, run the following command:

gcloud CLI

gcloud artifacts repositories describe REPOSITORY --location LOCATION --project PROJECT

curl

curl -v -H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY"

Where:

REPOSITORY is the name of your repository.
LOCATION is the location of your repository.
PROJECT is the project ID. If this flag is omitted, then the current or default project is used.

The output is similar to the following:

{
  "name": "projects/PROJECT/locations/LOCATION/repositories/REPOSITORY"
  "platformLogsConfig": {
    "loggingState": "ENABLED",
    "severityLevel": "INFO"
  }
}

Disable platform logging

You can disable platform logging for your entire Google Cloud project or for a specific repository.

Disable platform logging for a project

To disable platform logging for your Google Cloud project, run the following command:

gcloud CLI

gcloud artifacts projects update --disable-platform-logs --location LOCATION --project PROJECT

curl

curl -v -H "Authorization: Bearer $(gcloud auth print-access-token)" -X PATCH \
-H "X-GFE-SSL: yes" -H "Content-Type: application/json" \
-d '{"name": "projects/'PROJECT'/locations/'LOCATION'/projectConfig", "platformLogsConfig": {"logging_state": "DISABLED"}}' \
"https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/projectConfig"

Where:

LOCATION is the location of your repository.
PROJECT is the project ID. If this flag is omitted, then the current or default project is used.

Disable platform logging for a repository

To disable platform logging for a repository, run the following command:

gcloud CLI

gcloud artifacts repositories update --disable-platform-logs REPOSITORY --location LOCATION --project PROJECT

curl

curl -v -H "Authorization: Bearer $(gcloud auth print-access-token)" -X PATCH \
-H "X-GFE-SSL: yes" -H "Content-Type: application/json" \
-d '{"name": "projects/'PROJECT'/locations/'LOCATION'/repositories/'REPOSITORY'", "platformLogsConfig": {"loggingState": "DISABLED", "severityLevel": "INFO"}' \
"https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY?updateMask=platformLogsConfig"

Where:

REPOSITORY is the name of your repository in Artifact Registry.
LOCATION is the location of your repository.
PROJECT is the project ID. If this flag is omitted, then the current or default project is used.

Clear platform logging configuration

You can clear the platform logging configuration for a project or for a repository. When you run the clearing command, the loggingState and severityLevel of your project or repository are set to null.

If you clear your configuration for your project, then only repositories where platform logging has already been enabled will produce platform logs. If you clear your configuration for a repository, that repository inherits its platform logging configuration from your project.

Clear platform logging configuration for a project

To clear the platform logging configuration of your Google Cloud project, run the following command:

gcloud CLI

gcloud artifacts projects update --clear-platform-logs --location LOCATION --project PROJECT

curl

curl -v -H "Authorization: Bearer $(gcloud auth print-access-token)" -X PATCH \
-H "X-GFE-SSL: yes" -H "Content-Type: application/json" \
-d '{"name": "projects/'PROJECT'/locations/'LOCATION'/projectConfig", "platformLogsConfig": {}}' \
"https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/projectConfig"

Where:

LOCATION is the location of your repository.
PROJECT is the project ID. If this flag is omitted, then the current or default project is used.

Clear platform logging configuration for a repository

To clear the platform logging configuration of a repository, run the following command:

gcloud CLI

gcloud artifacts repositories update --clear-platform-logs REPOSITORY --location LOCATION --project PROJECT

curl

curl -v -H "Authorization: Bearer $(gcloud auth print-access-token)" -X PATCH \
-H "X-GFE-SSL: yes" -H "Content-Type: application/json" \
-d '{"name": "projects/'PROJECT'/locations/'LOCATION'/repositories/'REPOSITORY'", "platformLogsConfig": {}' \
"https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY?updateMask=platformLogsConfig"

Where:

REPOSITORY is the name of your repository in Artifact Registry.
LOCATION is the location of your repository.
PROJECT is the project ID. If this flag is omitted, then the current or default project is used.

View platform logs

To view your platform logs, do the following:

Open the Logs Explorer page in the Google Cloud console.

Open the Logs Explorer page
In the query pane, click the Log name drop-down.
Enter requests, and then select the requests checkbox under the Artifact Registry header.
Click Apply.

Logging shows logs from data plane and control plane API calls in the Query results pane.
To view the contents of a log, click the arrow next to any log listed in the query results.

For more information about understanding query results in the Logs Explorer, see View your query results.

Analyze platform logs with Observability Analytics

You can use Observability Analytics to run SQL queries against your Artifact Registry logs, letting you analyze your logs in greater detail. This section contains several sample queries for common use cases. You can adapt these queries to analyze other aspects of your Artifact Registry usage by filtering on different fields within the LogEntry structure.

Before you begin using Observability Analytics, do the following:

Configure your log buckets to use Observability Analytics.
Configure Identity and Access Management roles and permissions to use Observability Analytics.

Next, follow the steps to Enter and run a custom query. When you get to the SQL Query pane, you can enter one of the following sample queries:

Example: Top 10 IP addresses by downloaded volume

This query evaluates your Artifact Registry platform logs and returns the top 10 IP addresses that have downloaded the most data from your repositories over the last seven days:

SELECT
  http_request.remote_ip AS client_ip,
  SUM(http_request.response_size) AS total_download_bytes
FROM
  `YOUR_PROJECT.YOUR_LOCATION.YOUR_BUCKET._AllLogs`
WHERE
  log_id = "artifactregistry.googleapis.com/requests"
  AND JSON_VALUE(resource.labels.repository_id) IS NOT NULL
  AND http_request.request_method = "GET"
  AND http_request.status >= 200 AND http_request.status < 300
  AND http_request.response_size > 0
  AND CAST(http_request.response_size AS INT64) > 0
  AND timestamp >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY)
GROUP BY
  client_ip
ORDER BY
  total_download_bytes DESC
LIMIT 10;

Example: Requests per repository

This query evaluates your Artifact Registry platform logs and returns the number of requests made to each repository in the last 24 hours:

SELECT
  JSON_VALUE(resource.labels.repository_id) AS repository,
  JSON_VALUE(resource.labels.location) AS location,
  COUNT(*) AS request_count
FROM
  `YOUR_PROJECT.YOUR_LOCATION.YOUR_BUCKET._AllLogs`
WHERE
  log_id = "artifactregistry.googleapis.com/requests"
  AND JSON_VALUE(resource.labels.repository_id) IS NOT NULL
  AND timestamp >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 DAY)
GROUP BY
  repository,
  location
ORDER BY
  request_count DESC;

Example: Failed requests

This query evaluates your Artifact Registry platform logs and lists details for the 10 most recent failed requests over the last hour:

SELECT
  timestamp,
  http_request.status,
  http_request.request_method,
  http_request.request_url,
  http_request.remote_ip,
  JSON_VALUE(resource.labels.repository_id) AS repository,
  JSON_VALUE(labels.resource_name) AS artifact_name,
  trace
FROM
  `YOUR_PROJECT.YOUR_LOCATION.YOUR_BUCKET._AllLogs`
WHERE
  log_id = "artifactregistry.googleapis.com/requests"
  AND JSON_VALUE(resource.labels.repository_id) IS NOT NULL
  AND http_request.status >= 400
  AND timestamp >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR)
ORDER BY
  timestamp DESC
LIMIT 10;

Access and use platform logs Stay organized with collections Save and categorize content based on your preferences.

Overview

Before you begin

Required roles

Enable platform logging

Enable platform logging for a project

gcloud CLI

curl

Enable platform logging for a repository

gcloud CLI

curl

Verify platform logging configuration

Verify platform logging for a project

gcloud CLI

curl

Verify platform logging for a repository

gcloud CLI

curl

Disable platform logging

Disable platform logging for a project

gcloud CLI

curl

Disable platform logging for a repository

gcloud CLI

curl

Clear platform logging configuration

Clear platform logging configuration for a project

gcloud CLI

curl

Clear platform logging configuration for a repository

gcloud CLI

curl

View platform logs

Analyze platform logs with Observability Analytics

Example: Top 10 IP addresses by downloaded volume

Example: Requests per repository

Example: Failed requests

Access and use platform logs