Accede a los registros de la plataforma y úsalos

Configura los registros de la plataforma en Artifact Registry para que puedas ver información sobre las solicitudes exitosas y fallidas que se realizaron a tus repositorios de Artifact Registry. Cloud Logging genera los registros de la plataforma, que se pueden ver en el Explorador de registros. Puedes revisar los registros de la plataforma de Artifact Registry para solucionar problemas relacionados con solicitudes fallidas, mantener registros de solicitudes exitosas y ver la cantidad de descargas de un artefacto.

Un registro de la plataforma tiene el formato de un LogEntry.

Descripción general

Artifact Registry genera registros de la plataforma para las llamadas a la API del plano de datos y del plano de control. Las acciones del plano de control incluyen operaciones de administración de repositorios, como crear, editar y borrar repositorios, y acciones de administración de artefactos, como enumerar, etiquetar y borrar artefactos. Las acciones del plano de datos incluyen operaciones como la transferencia de artefactos a los repositorios de Artifact Registry y la recuperación de estos.

Los registros de ambos tipos de llamadas contienen la siguiente información:

• Detalles de la solicitud
• Detalles de la respuesta
• Estado
• Etiquetas
  • Nombre del método
  • Nombre del recurso
  • Ubicación del recurso
  • ID de operación (para operaciones de larga duración)
  • Formato del repositorio (para los recursos del repositorio)
  • Modo de repositorio (para recursos de repositorio)

Además, los registros de las llamadas a la API del plano de control contienen la siguiente información:

• Información de HTTP
  • Método de solicitud
  • Solicitar URL
  • Tamaño de la solicitud (en bytes)
  • Estado
  • Tamaño de la respuesta (en bytes)
  • Usuario-agente
  • IP remota (IP del cliente que emitió la solicitud)
  • Protocolo
  • Referencia
  • Latencia

Puedes ver los registros de la plataforma de Artifact Registry en el Explorador de registros.

Antes de comenzar

Habilita la API de Logging.

Roles obligatorios

Para obtener los permisos que necesitas para administrar los registros de la plataforma, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto:

• Administrador de Artifact Registry (roles/artifactregistry.admin)
• Visor de registro (roles/logging.viewer)

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Habilitar el registro de la plataforma

Puedes habilitar el registro de la plataforma en todo tu proyecto Google Cloud o para un repositorio específico.

Habilita el registro de la plataforma para un proyecto

Para habilitar el registro de la plataforma en tu proyecto de Google Cloud , ejecuta el siguiente comando:

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

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"

Aquí:

• SEVERITY determina el tipo de acciones que activan la creación de registros de la plataforma de Artifact Registry. Puedes ingresar INFO, ERROR o excluir el campo --severity para crear registros de la plataforma para todas las acciones admitidas.
• LOCATION es la ubicación de tu repositorio.
• PROJECT es el ID del proyecto. Si se omite esta marca, se usa el proyecto predeterminado o actual.

Habilita el registro de la plataforma para un repositorio

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

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"

Aquí:

• SEVERITY determina el tipo de acciones que activan la creación de registros de la plataforma de Artifact Registry. Puedes ingresar INFO, ERROR o excluir el campo --severity para crear registros de la plataforma para todas las acciones admitidas.
• REPOSITORY es el nombre de tu repositorio en Artifact Registry.
• LOCATION es la ubicación de tu repositorio.
• PROJECT es el ID del proyecto. Si se omite esta marca, se usa el proyecto predeterminado o actual.

Verifica la configuración del registro de la plataforma

Puedes verificar si el registro de la plataforma de Artifact Registry está habilitado en tu proyecto o para un repositorio específico.

Verifica el registro de la plataforma para un proyecto

Para verificar si el registro de la plataforma de Artifact Registry está habilitado en tu proyecto, ejecuta el siguiente comando:

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

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

Aquí:

• LOCATION es la ubicación de tu repositorio.
• PROJECT es el ID del proyecto. Si se omite esta marca, se usa el proyecto predeterminado o actual.

El resultado es similar a lo siguiente:

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

Verifica el registro de la plataforma para un repositorio

Para verificar si el registro de la plataforma de Artifact Registry está habilitado en un repositorio, ejecuta el siguiente comando:

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

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

Aquí:

• REPOSITORY es el nombre del repositorio.
• LOCATION es la ubicación de tu repositorio.
• PROJECT es el ID del proyecto. Si se omite esta marca, se usa el proyecto predeterminado o actual.

El resultado es similar a lo siguiente:

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

Inhabilita el registro de la plataforma

Puedes inhabilitar el registro de la plataforma para todo tu proyecto Google Cloud o para un repositorio específico.

Inhabilita el registro de la plataforma para un proyecto

Para inhabilitar el registro de la plataforma en tu proyecto Google Cloud , ejecuta el siguiente comando:

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

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"

Aquí:

• LOCATION es la ubicación de tu repositorio.
• PROJECT es el ID del proyecto. Si se omite esta marca, se usa el proyecto predeterminado o actual.

Inhabilita el registro de la plataforma para un repositorio

Para inhabilitar el registro de la plataforma en un repositorio, ejecuta el siguiente comando:

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

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"

Aquí:

• REPOSITORY es el nombre de tu repositorio en Artifact Registry.
• LOCATION es la ubicación de tu repositorio.
• PROJECT es el ID del proyecto. Si se omite esta marca, se usa el proyecto predeterminado o actual.

Borra la configuración de registro de la plataforma

Puedes borrar la configuración de registro de la plataforma para un proyecto o un repositorio. Cuando ejecutas el comando de borrado, los valores loggingState y severityLevel de tu proyecto o repositorio se establecen como nulos.

Si borras la configuración de tu proyecto, solo los repositorios en los que ya se habilitó el registro de la plataforma producirán registros de la plataforma. Si borras la configuración de un repositorio, este heredará la configuración de registros de la plataforma de tu proyecto.

Borra la configuración del registro de la plataforma para un proyecto

Para borrar la configuración de registro de la plataforma de tu proyecto Google Cloud , ejecuta el siguiente comando:

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

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"

Aquí:

• LOCATION es la ubicación de tu repositorio.
• PROJECT es el ID del proyecto. Si se omite esta marca, se usa el proyecto predeterminado o actual.

Borra la configuración del registro de la plataforma para un repositorio

Para borrar la configuración de registro de la plataforma de un repositorio, ejecuta el siguiente comando:

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

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"

Aquí:

• REPOSITORY es el nombre de tu repositorio en Artifact Registry.
• LOCATION es la ubicación de tu repositorio.
• PROJECT es el ID del proyecto. Si se omite esta marca, se usa el proyecto predeterminado o actual.

Cómo ver los registros de la plataforma

Para ver los registros de tu plataforma, haz lo siguiente:

1. Abre la página del Explorador de registros en la consola de Google Cloud .

   Abre la página Explorador de registros

2. En el panel de consultas, haz clic en el menú desplegable Nombre del registro.

3. Ingresa requests y, luego, selecciona la casilla de verificación requests en el encabezado Artifact Registry.

4. Haz clic en Aplicar.

   En el panel Resultados de la consulta, Logging muestra los registros de las llamadas a la API del plano de datos y del plano de control.

5. Para ver el contenido de un registro, haz clic en la flecha que aparece junto a cualquier registro que se muestre en los resultados de la búsqueda.

Para obtener más información sobre cómo comprender los resultados de las consultas en el Explorador de registros, consulta Cómo ver los resultados de tus consultas.

Analiza los registros de la plataforma con Observability Analytics

Puedes usar Observability Analytics para ejecutar consultas en SQL en tus registros de Artifact Registry, lo que te permite analizarlos con mayor detalle. En esta sección, se incluyen varias consultas de ejemplo para casos de uso comunes. Puedes adaptar estas consultas para analizar otros aspectos de tu uso de Artifact Registry filtrando diferentes campos dentro de la estructura LogEntry.

Antes de comenzar a usar Observability Analytics, haz lo siguiente:

1. Configura tus buckets de registros para usar Análisis de observabilidad.

2. Configura los roles y permisos de Identity and Access Management para usar Observability Analytics.

A continuación, sigue los pasos para ingresar y ejecutar una consulta personalizada. Cuando llegues al panel de Consulta en SQL, puedes ingresar una de las siguientes consultas de muestra:

Ejemplo: Las 10 direcciones IP principales según el volumen de descargas

Esta consulta evalúa los registros de la plataforma de Artifact Registry y muestra las 10 principales direcciones IP que descargaron la mayor cantidad de datos de tus repositorios en los últimos siete días:

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;

Ejemplo: Solicitudes por repositorio

Esta consulta evalúa los registros de la plataforma de Artifact Registry y muestra la cantidad de solicitudes realizadas a cada repositorio en las últimas 24 horas:

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;

Ejemplo: Solicitudes con errores

Esta consulta evalúa los registros de la plataforma de Artifact Registry y muestra los detalles de las 10 solicitudes fallidas más recientes de la última hora:

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;