Accede a los registros de la plataforma y úsalos

Los registros de plataforma en Artifact Registry proporcionan información sobre las solicitudes exitosas y con errores a los repositorios de Artifact Registry. Revisar estos registros te ayuda a solucionar problemas de solicitudes con errores, mantener registros de solicitudes exitosas y ver la cantidad de descargas de un artefacto.

Descripción general

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

Cloud Logging genera registros de plataforma. Puedes verlos en el Explorador de registros. Un registro de plataforma tiene el formato de una LogEntry.

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

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:

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 de 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 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"

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 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 actual o el predeterminado.

Habilita el registro de la plataforma para un repositorio

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"

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 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 actual o el predeterminado.

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 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"

Aquí:

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

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 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"

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 actual o el predeterminado.

El resultado es similar a lo siguiente:

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

Inhabilitar el registro de la plataforma

Puedes inhabilitar el registro de la plataforma para todo tu proyecto de 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 de Google Cloud , ejecuta el siguiente comando:

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"

Aquí:

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

Inhabilita el registro de la plataforma para un repositorio

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

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"

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 actual o el predeterminado.

Borra la configuración de registro de la plataforma

Puedes borrar la configuración de los registros de la plataforma de un proyecto o un repositorio. Cuando ejecutas el comando de borrado, el loggingState y el severityLevel de tu proyecto o repositorio se establecen en nulo.

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, ese repositorio hereda su configuración de registro de la plataforma de tu proyecto.

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

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

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"

Aquí:

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

Borra la configuración de los registros de la plataforma de un repositorio

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

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"

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 actual o el predeterminado.

Visualiza los registros de la plataforma

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

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

    Abre la página Explorador de registros

  2. En el panel de consulta, 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.

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

  5. Para ver el contenido de un registro, haz clic en la flecha junto a cualquier registro que aparezca en los resultados de la consulta.

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

Analiza los registros de la plataforma con Estadísticas de observabilidad

Puedes usar las Estadísticas de observabilidad para ejecutar consultas en SQL en tus registros de Artifact Registry, lo que te permite analizar tus registros con más 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 de LogEntry.

Antes de comenzar a usar las Estadísticas de observabilidad, haz lo siguiente:

  1. Configura tus buckets de registros para usar las Estadísticas de observabilidad.

  2. Configura los roles y permisos de Identity and Access Management para usar las Estadísticas de observabilidad.

Luego, sigue los pasos para ingresar y ejecutar una consulta personalizada. Cuando llegues al panel Consulta de SQL, puedes ingresar una de las siguientes consultas de ejemplo:

Ejemplo: Las 10 direcciones IP principales por volumen descargado

En esta consulta, se evalúan los registros de la plataforma de Artifact Registry y se devuelven las 10 direcciones IP principales 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 devuelve 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;