[Platform logs](https://docs.cloud.google.com/logging/docs/api/platform-logs) in
Artifact Registry provide information about successful and failed requests
to Artifact Registry repositories. Reviewing these logs helps you to
troubleshoot failed requests, maintain records of successful requests,
and view the number of downloads for an artifact.

## 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.

Cloud Logging generates platform logs. You can view them in the
[Logs Explorer](https://docs.cloud.google.com/logging/docs/view/logs-explorer-interface).
A platform log is formatted as a
[LogEntry](https://docs.cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry).

> [!IMPORTANT]
> **Important:** Log storage in Logging may incur charges. For more information, see [Logging pricing](https://cloud.google.com/logging#pricing).

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

## Before you begin

[Enable the Logging API](https://docs.cloud.google.com/logging/docs/api/enable-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](https://docs.cloud.google.com/iam/docs/roles-permissions/artifactregistry#artifactregistry.admin) (`roles/artifactregistry.admin`)
- [Logging Viewer](https://docs.cloud.google.com/iam/docs/roles-permissions/logging#logging.viewer) (`roles/logging.viewer`)


For more information about granting roles, see [Manage access to projects, folders, and organizations](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access).


You might also be able to get
the required permissions through [custom
roles](https://docs.cloud.google.com/iam/docs/creating-custom-roles) or other [predefined
roles](https://docs.cloud.google.com/iam/docs/roles-overview#predefined).

## 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:

- <var translate="no">SEVERITY</var> 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.
- <var translate="no">LOCATION</var> is the location of your repository.
- <var translate="no">PROJECT</var> is the project ID. If this flag is omitted, then the current or [default project](https://docs.cloud.google.com/artifact-registry/docs/gcloud-defaults#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:

- <var translate="no">SEVERITY</var> 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.
- <var translate="no">REPOSITORY</var> is the name of your repository in Artifact Registry.
- <var translate="no">LOCATION</var> is the location of your repository.
- <var translate="no">PROJECT</var> is the project ID. If this flag is omitted, then the current or [default project](https://docs.cloud.google.com/artifact-registry/docs/gcloud-defaults#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:

- <var translate="no">LOCATION</var> is the location of your repository.
- <var translate="no">PROJECT</var> is the project ID. If this flag is omitted, then the current or [default project](https://docs.cloud.google.com/artifact-registry/docs/gcloud-defaults#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:

- <var translate="no">REPOSITORY</var> is the name of your repository.
- <var translate="no">LOCATION</var> is the location of your repository.
- <var translate="no">PROJECT</var> is the project ID. If this flag is omitted, then the current or [default project](https://docs.cloud.google.com/artifact-registry/docs/gcloud-defaults#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:

- <var translate="no">LOCATION</var> is the location of your repository.
- <var translate="no">PROJECT</var> is the project ID. If this flag is omitted, then the current or [default project](https://docs.cloud.google.com/artifact-registry/docs/gcloud-defaults#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:

- <var translate="no">REPOSITORY</var> is the name of your repository in Artifact Registry.
- <var translate="no">LOCATION</var> is the location of your repository.
- <var translate="no">PROJECT</var> is the project ID. If this flag is omitted, then the current or [default project](https://docs.cloud.google.com/artifact-registry/docs/gcloud-defaults#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:

- <var translate="no">LOCATION</var> is the location of your repository.
- <var translate="no">PROJECT</var> is the project ID. If this flag is omitted, then the current or [default project](https://docs.cloud.google.com/artifact-registry/docs/gcloud-defaults#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:

- <var translate="no">REPOSITORY</var> is the name of your repository in Artifact Registry.
- <var translate="no">LOCATION</var> is the location of your repository.
- <var translate="no">PROJECT</var> is the project ID. If this flag is omitted, then the current or [default project](https://docs.cloud.google.com/artifact-registry/docs/gcloud-defaults#project) is used.

## View platform logs

To view your platform logs, do the following:

1. Open the Logs Explorer page in the Google Cloud console.

   [Open the Logs Explorer page](https://console.cloud.google.com/logs)
2. In the [query pane](https://docs.cloud.google.com/logging/docs/view/logs-explorer-interface#query-builder),
   click the **Log name** drop-down.

3. Enter **requests** , and then select the **requests** checkbox under the
   **Artifact Registry** header.

4. Click **Apply**.

   Logging shows logs from data plane and control plane API calls
   in the **Query results** pane.
5. 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](https://docs.cloud.google.com/logging/docs/view/logs-explorer-interface#query-results).

## Analyze platform logs with Observability Analytics

You can use [Observability Analytics](https://docs.cloud.google.com/logging/docs/analyze/query-and-view)
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](https://docs.cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry)
structure.

Before you begin using Observability Analytics, do the following:

1. [Configure your log buckets](https://docs.cloud.google.com/logging/docs/analyze/query-and-view) to
   use Observability Analytics.

2. [Configure Identity and Access Management roles and permissions](https://docs.cloud.google.com/logging/docs/analyze/query-and-view#roles-perms)
   to use Observability Analytics.

Next, follow the steps to
[Enter and run a custom query](https://docs.cloud.google.com/logging/docs/analyze/query-and-view#sql-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;