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 correctas y fallidas realizadas a tus repositorios de Artifact Registry. Cloud Logging genera los registros de la plataforma , y 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 correctas y ver la cantidad de descargas de un artefacto.

Un registro de la plataforma tiene el formato de LogEntry.

Descripción general

Artifact Registry genera registros de la 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.

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 recursos del repositorio)
  • Modo del repositorio (para recursos del 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 Logging (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 el Cloud de Confiance proyecto o para un repositorio específico.

Habilita el registro de la plataforma para un proyecto

Para habilitar el registro de la plataforma para tu Cloud de Confiance proyecto, 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, entonces el proyecto actual o predeterminado se usa.

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, entonces el proyecto actual o predeterminado se usa.

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, entonces el proyecto actual o predeterminado se usa.

El resultado es similar a este:

{
  "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 de tu repositorio.
• LOCATION es la ubicación de tu repositorio.
• PROJECT es el ID del proyecto. Si se omite esta marca, entonces el proyecto actual o predeterminado se usa.

El resultado es similar a este:

{
  "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 en todo el proyecto o para un repositorio específico. Cloud de Confiance

Inhabilita el registro de la plataforma para un proyecto

Para inhabilitar el registro de la plataforma para tu Cloud de Confiance proyecto, 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, entonces el proyecto actual o predeterminado se usa.

Inhabilita el registro de la plataforma para un repositorio

Para inhabilitar el registro de la plataforma para 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, entonces el proyecto actual o predeterminado se usa.

Borra la configuración del registro de la plataforma

Puedes borrar la configuración del registro de la plataforma para un proyecto o para un repositorio. Cuando ejecutas el comando de borrado, loggingState y 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 del registro de la plataforma para un proyecto

Para borrar la configuración del registro de la plataforma de tu Cloud de Confiance proyecto, 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, entonces el proyecto actual o predeterminado se usa.

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

Para borrar la configuración del 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, entonces el proyecto actual o predeterminado se usa.

Visualiza los registros de la plataforma

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

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

   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.

   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 que aparece junto a cualquier registro que se muestre en los resultados de la consulta.

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

Analiza los registros de la plataforma con el Análisis de observabilidad

Puedes usar el Análisis de observabilidad para ejecutar consultas en SQL en tus registros de Artifact Registry, lo que te permite analizar tus registros con mayor detalle. En esta sección, se incluyen varias consultas de muestra para casos de uso comunes. Puedes adaptar estas consultas para analizar otros aspectos del uso de Artifact Registry si filtras en diferentes campos dentro de la LogEntry LogEntry.

Antes de comenzar a usar el Análisis de observabilidad, haz lo siguiente:

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

2. Configura los roles y permisos de Identity and Access Management para usar el Análisis de observabilidad.

A continuación, 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 muestra:

Ejemplo: Las 10 principales direcciones IP por volumen descargado

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 durante 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 fallidas

Esta consulta evalúa los registros de la plataforma de Artifact Registry y muestra detalles de las 10 solicitudes fallidas más recientes durante 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;