存取及使用平台記錄檔

在 Artifact Registry 中設定平台記錄，即可查看對 Artifact Registry 存放區發出的要求 (成功和失敗) 相關資訊。平台記錄是由 Cloud Logging 產生，您可以在Logs Explorer中查看。您可以查看 Artifact Registry 平台記錄，協助排解要求失敗的問題、維護成功要求記錄，以及查看構件的下載次數。

平台記錄的格式為 LogEntry。

總覽

Artifact Registry 會為資料平面 API 呼叫和控制層 API 呼叫產生平台記錄。控制層動作包括存放區管理作業 (例如建立、編輯和刪除存放區)，以及構件管理動作 (例如列出、標記和刪除構件)。資料平面動作包括從 Artifact Registry 存放區推送及提取構件等作業。

這兩種來電的記錄都包含下列資訊：

要求詳細資料
回覆詳細資料
狀態
標籤
- 方法名稱
- 資源名稱
- 資源地區
- 作業 ID (適用於長時間執行的作業)
- 存放區格式 (適用於存放區資源)
- 存放區模式 (適用於存放區資源)

此外，控制層 API 呼叫的記錄檔包含下列資訊：

HTTP 資訊
- 要求方法
- 申請網址
- 要求大小 (以位元組為單位)
- 狀態
- 回應大小 (以位元組為單位)
- 使用者代理程式
- 遠端 IP (發出要求的用戶端 IP)
- 通訊協定
- 參照網址
- 延遲時間

您可以在 Logs Explorer 中查看 Artifact Registry 的平台記錄。

事前準備

啟用 Logging API。

必要的角色

如要取得管理平台記錄所需的權限，請要求管理員在專案中授予您下列 IAM 角色：

Artifact Registry 管理員 (roles/artifactregistry.admin)
記錄檢視器 (roles/logging.viewer)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

啟用平台記錄功能

您可以為整個 Google Cloud 專案或特定存放區啟用平台記錄。

為專案啟用平台記錄功能

如要為 Google Cloud 專案啟用平台記錄，請執行下列指令：

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"

其中：

SEVERITY 會決定觸發 Artifact Registry 平台記錄建立作業的動作類型。您可以輸入 INFO、ERROR 或排除 --severity 欄位，為所有支援的動作建立平台記錄。
LOCATION 是存放區的位置。
PROJECT 是專案 ID。如果省略這個旗標，系統會使用目前或預設專案。

為存放區啟用平台記錄功能

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"

其中：

SEVERITY 會決定觸發 Artifact Registry 平台記錄建立作業的動作類型。您可以輸入 INFO、ERROR 或排除 --severity 欄位，為所有支援的動作建立平台記錄。
REPOSITORY 是 Artifact Registry 中的存放區名稱。
LOCATION 是存放區的位置。
PROJECT 是專案 ID。如果省略這個旗標，系統會使用目前或預設專案。

驗證平台記錄設定

您可以確認專案或特定存放區是否已啟用 Artifact Registry 平台記錄。

驗證專案的平台記錄

如要確認專案是否已啟用 Artifact Registry 平台記錄，請執行下列指令：

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"

其中：

LOCATION 是存放區的位置。
PROJECT 是專案 ID。如果省略這個旗標，系統會使用目前或預設專案。

輸出結果會與下列內容相似：

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

驗證存放區的平台記錄

如要確認是否已在存放區中啟用 Artifact Registry 平台記錄，請執行下列指令：

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"

其中：

REPOSITORY 是存放區的名稱。
LOCATION 是存放區的位置。
PROJECT 是專案 ID。如果省略這個旗標，系統會使用目前或預設專案。

輸出結果會與下列內容相似：

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

停用平台記錄功能

您可以為整個 Google Cloud 專案或特定存放區停用平台記錄功能。

停用專案的平台記錄功能

如要為 Google Cloud 專案停用平台記錄，請執行下列指令：

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"

其中：

LOCATION 是存放區的位置。
PROJECT 是專案 ID。如果省略這個旗標，系統會使用目前或預設專案。

停用存放區的平台記錄功能

如要停用存放區的平台記錄功能，請執行下列指令：

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"

其中：

REPOSITORY 是 Artifact Registry 中的存放區名稱。
LOCATION 是存放區的位置。
PROJECT 是專案 ID。如果省略這個旗標，系統會使用目前或預設專案。

清除平台記錄設定

您可以清除專案或存放區的平台記錄設定。執行清除指令時，專案或存放區的 loggingState 和 severityLevel 會設為空值。

如果清除專案的設定，只有已啟用平台記錄的存放區會產生平台記錄。如果清除存放區的設定，該存放區會從專案繼承平台記錄設定。

清除專案的平台記錄設定

如要清除 Google Cloud 專案的平台記錄設定，請執行下列指令：

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"

其中：

LOCATION 是存放區的位置。
PROJECT 是專案 ID。如果省略這個旗標，系統會使用目前或預設專案。

清除存放區的平台記錄設定

如要清除存放區的平台記錄設定，請執行下列指令：

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"

其中：

REPOSITORY 是 Artifact Registry 中的存放區名稱。
LOCATION 是存放區的位置。
PROJECT 是專案 ID。如果省略這個旗標，系統會使用目前或預設專案。

查看平台記錄

如要查看平台記錄，請按照下列步驟操作：

在 Google Cloud 控制台中開啟「Logs Explorer」頁面。

開啟「Logs Explorer」頁面
在查詢窗格中，按一下「記錄檔名稱」下拉式選單。
輸入「requests」，然後勾選「Artifact Registry」標題下方的「requests」核取方塊。
按一下「套用」。

記錄檔會在「Query results」(查詢結果) 窗格中，顯示資料層和控制層 API 呼叫的記錄。
如要查看記錄內容，請按一下查詢結果中列出的任一記錄旁的箭頭。

如要進一步瞭解如何解讀 Logs Explorer 中的查詢結果，請參閱「查看查詢結果」。

使用 Observability Analytics 分析平台記錄

您可以使用 Observability Analytics 對 Artifact Registry 記錄執行 SQL 查詢，進一步分析記錄。本節包含常見用途的幾個範例查詢。您可以根據 LogEntry 結構中的不同欄位進行篩選，調整這些查詢來分析 Artifact Registry 使用情況的其他層面。

開始使用 Observability Analytics 前，請先完成下列步驟：

設定記錄檔 bucket，即可使用 Observability Analytics。
設定 Identity and Access Management 角色和權限，即可使用可觀測性分析。

接著，請按照步驟輸入及執行自訂查詢。在 SQL「查詢」窗格中，您可以輸入下列其中一個查詢範例：

範例：依下載量排序的前 10 個 IP 位址

這項查詢會評估 Artifact Registry 平台記錄，並傳回過去七天內從存放區下載最多資料的前 10 個 IP 位址：

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;

範例：每個存放區的要求數

這項查詢會評估 Artifact Registry 平台記錄，並傳回過去 24 小時內對每個存放區提出的要求數：

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;

例如：失敗的要求

這項查詢會評估 Artifact Registry 平台記錄，並列出過去一小時內最近 10 項失敗要求的詳細資料：

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;

存取及使用平台記錄檔 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

總覽

事前準備

必要的角色

啟用平台記錄功能

為專案啟用平台記錄功能

gcloud CLI

curl

為存放區啟用平台記錄功能

gcloud CLI

curl

驗證平台記錄設定

驗證專案的平台記錄

gcloud CLI

curl

驗證存放區的平台記錄

gcloud CLI

curl

停用平台記錄功能

停用專案的平台記錄功能

gcloud CLI

curl

停用存放區的平台記錄功能

gcloud CLI

curl

清除平台記錄設定

清除專案的平台記錄設定

gcloud CLI

curl

清除存放區的平台記錄設定

gcloud CLI

curl

查看平台記錄

使用 Observability Analytics 分析平台記錄

範例：依下載量排序的前 10 個 IP 位址

範例：每個存放區的要求數

例如：失敗的要求

存取及使用平台記錄檔