Guía de inicio rápido para el uso de herramientas de Logging

En esta guía de inicio rápido, se presentan algunas de las funciones de Cloud Logging y se explica cómo hacer lo siguiente:

• Escribir entradas de registro mediante la herramienta de línea de comandos de gcloud
• Mostrar las entradas del registro con la herramienta de línea de comandos de gcloud
• Mostrar una lista de entradas de registro con la API de Logging
• Ver y consultar las entradas del registro mediante el explorador de registros

Antes de comenzar

Debes tener un proyecto de Google Cloud con la facturación habilitada para completar esta guía de inicio rápido. Si no tienes un proyecto de Cloud o si no tienes habilitada la facturación para tu proyecto de Cloud, haz lo siguiente:

1. Accede a tu cuenta de Google Cloud. Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

2. En la página del selector de proyectos de Google Cloud Console, selecciona o crea un proyecto de Google Cloud.

   Nota: Si no planeas conservar los recursos que creaste durante este procedimiento, crea un proyecto en lugar de seleccionar uno existente. Cuando termines, puedes borrar el proyecto y quitar todos los recursos asociados con él.

   Ir al selector de proyectos

3. Asegúrate de que la facturación esté habilitada para tu proyecto de Cloud. Descubre cómo confirmar que tienes habilitada la facturación en un proyecto.

4. En la página del selector de proyectos de Google Cloud Console, selecciona o crea un proyecto de Google Cloud.

   Nota: Si no planeas conservar los recursos que creaste durante este procedimiento, crea un proyecto en lugar de seleccionar uno existente. Cuando termines, puedes borrar el proyecto y quitar todos los recursos asociados con él.

   Ir al selector de proyectos

5. Asegúrate de que la facturación esté habilitada para tu proyecto de Cloud. Descubre cómo confirmar que tienes habilitada la facturación en un proyecto.

Comenzar

El SDK de Cloud tiene un grupo de comandos, gcloud logging, que proporciona una interfaz de línea de comandos para la API de Cloud Logging.

Puedes usar el entorno de Cloud Shell o una instancia de máquina virtual (VM) de Compute Engine para los comandos de la herramienta de línea de comandos de gcloud en esta guía de inicio rápido. El SDK de Cloud está preinstalado en el entorno de Cloud Shell.

Cloud Shell

Verifica que el SDK de Cloud esté configurado para usar el proyecto de Cloud correcto:

1. En Cloud Console, haz clic en Activar Cloud Shell:

   

   Cloud Shell se abrirá en una ventana y mostrará un mensaje de bienvenida. El mensaje de bienvenida repite el ID del proyecto configurado:

   

2. Si deseas usar un proyecto de Cloud distinto del que se muestra en el mensaje de bienvenida, ejecuta el siguiente comando después de reemplazar PROJECT_ID por el ID del proyecto:

       gcloud config set project PROJECT_ID
   

   Para obtener el ID del proyecto, consulta la sección sobre cómo crear y administrar proyectos.

Instancia de VM

Para crear una instancia de VM de Compute Engine en Cloud Console, sigue estos pasos:

1. En Cloud Console, selecciona Compute Engine y, luego, Instancias de VM.

2. Selecciona Crear instancia.

3. En Identidad y acceso a la API, selecciona Configurar acceso para cada API en Permisos de acceso.

4. Desplácese por las API hasta que encuentre la API de Stackdriver Logging. Cambia el acceso a Full.

5. Deja el resto de la configuración con los valores predeterminados y haz clic en Crear (Create). Tu instancia de VM está lista para usarse.

6. Haga clic en SSH para conectarse a la shell de su instancia de VM. Después de un momento, se abrirá una shell de Debian GNU/Linux en una ventana y mostrará un mensaje de bienvenida.

7. Ejecuta el siguiente comando a fin de verificar que el SDK de Cloud, que viene preinstalado, esté configurado para tu proyecto de Compute Engine:

   gcloud config list
   

8. Si el proyecto de Cloud indicado no es el que deseas usar, ejecuta el siguiente comando y reemplaza PROJECT_ID por tu ID del proyecto:

      gcloud config set project PROJECT_ID
   

   Para obtener el ID del proyecto, consulta la sección sobre cómo crear y administrar proyectos.

Escribe entradas de registro con la herramienta de gcloud

Logging admite entradas de registro con datos estructurados y no estructurados. Los datos estructurados constan de una estructura de datos JSON, por ejemplo, {"weather": "partly cloudy"}. Los datos no estructurados son una string de caracteres, por ejemplo, "A simple entry". En los pasos siguientes, usarás la herramienta de gcloud para escribir una entrada de registro con datos no estructurados y una entrada de registro con datos estructurados:

1. Escribe una entrada de registro con datos no estructurados en el registro my-test-log:

   gcloud logging write my-test-log "A simple entry."
   

   Cuando el comando finalice, verás el mensaje: Created log entry.

2. Escribe una entrada de registro con datos estructurados en el registro my-test-log:

   gcloud logging write --payload-type=json my-test-log '{ "message": "My second entry", "weather": "partly cloudy"}'
   

   Cuando escribes una entrada de registro con datos estructurados, debes incluir --payload-type=json. Si omites este campo, Logging interpretará la carga útil como texto no estructurado.

Si el registro my-test-log no existe, Logging creará el registro cuando se reciba la entrada de registro.

Enumera las entradas del registro con la herramienta gcloud

Puedes recuperar entradas de registro de Logging y mostrarlas mediante la herramienta de gcloud. Por ejemplo, para recuperar y mostrar las entradas de registro con un tipo de recurso global, ejecuta el siguiente comando:

gcloud logging read "resource.type=global"

El comando mostrará un resultado similar al siguiente:

---
insertId: jpj9zjf73t1mn
jsonPayload:
  message: My second entry
  weather: partly cloudy
logName: projects/myloggingproject/logs/my-test-log
receiveTimestamp: '2018-11-01T18:39:31.114507977Z'
resource:
  labels:
    project_id: myloggingproject
  type: global
timestamp: '2018-11-01T18:39:31.114507977Z'
---
insertId: vd4m1if7h7u1a
logName: projects/myloggingproject/logs/my-test-log
receiveTimestamp: '2018-11-01T18:39:19.718100792Z'
resource:
  labels:
    project_id: myloggingproject
  type: global
textPayload: A simple entry
timestamp: '2018-11-01T18:39:19.718100792Z'

Enumerar entradas de registro con el Explorador de API

Para ejecutar los métodos de la API de Logging sin escribir ningún código, usa el Explorador de API. Para leer una lista de entradas de registro de Logging, haz lo siguiente:

1. Ve a la página de referencia de la API para obtener el método de la API de entries.list:

   Ir a la página de la API de entries.list

2. Configura y ejecuta el comando de API:

   1. Reemplaza PROJECT_ID en el siguiente texto:

        "resourceNames": [
          "projects/PROJECT_ID"
        ],
        "filter": "resource.type=global",
        "orderBy": "timestamp desc"
      

   2. Copia el texto actualizado del paso anterior y pégalo en el campo Cuerpo de la solicitud del Explorador de API.

   3. Haz clic en Ejecutar.

   El método muestra una respuesta similar a la siguiente:

   {
     "entries": [
       {
         "textPayload": "A simple entry",
         "insertId": "vd4m1if7h7u1a",
         "resource": {
           "type": "global",
           "labels": {
             "project_id": "myloggingproject"
           }
         },
         "timestamp": "2018-11-01T18:39:19.718100792Z",
         "logName": "projects/myloggingproject/logs/my-test-log",
         "receiveTimestamp": "2018-11-01T18:39:19.718100792Z"
       },
       {
         "insertId": "jpj9zjf73t1mn",
         "jsonPayload": {
           "message": "My second entry",
           "weather": "partly cloudy"
         },
         "resource": {
           "type": "global",
           "labels": {
             "project_id": "myloggingproject"
           }
         },
         "timestamp": "2018-11-01T18:39:31.114507977Z",
         "logName": "projects/myloggingproject/logs/my-test-log",
         "receiveTimestamp": "2018-11-01T18:39:31.114507977Z"
       }
     ]
   }
   

Visualiza entradas de registro en el Explorador de registros

Para ver las entradas de registro, puedes usar el Explorador de registros. La mayoría de los proyectos de Cloud almacenan una gran cantidad de registros, por lo que puedes ver ciertas entradas de registro si agregas filtros o escribes una consulta.

Para ver las entradas de registro que escribiste mediante el Explorador de registros, haz lo siguiente:

1. Ve al Explorador de registros en Google Cloud Console.

   Ir al Explorador de registros

   Asegúrate de que tu proyecto de Cloud esté seleccionado en la barra de navegación de Google Cloud. Si es necesario, usa la lista desplegable del proyecto de Cloud para seleccionar tu proyecto de Cloud.

2. En el menú Recurso, selecciona Global.

   Si no ves la opción del menú Global o si no ves tus entradas de registro, espera unos minutos y actualiza la página. Es posible que Logging tarde unos minutos en recibir las entradas de registro.

3. Para ver los detalles de una entrada de registro, haz clic en su menú .

   La primera entrada de registro tiene los datos almacenados en textPayload. La segunda entrada de registro contiene datos estructurados que se almacenan en jsonPayload. La carga útil estructurada contiene las claves message y weather.

   Nota: Cuando message es una clave para una entrada de registro estructurada, Logging la usa como resumen de la entrada de registro cuando esta no está expandida.

Para obtener información sobre los formatos de datos de las entradas de registro, consulta el tipo LogEntry.

Consulta entradas de registro en el explorador de registros

Puedes consultar entradas de registro mediante un campo de texto y con registros estructurados, por clave y valor. Por ejemplo, para mostrar todas las entradas de registro que contienen el texto simple, haz lo siguiente:

1. Ve al Explorador de registros en Google Cloud Console.

   Ir al Explorador de registros

2. En el menú Recurso, selecciona Global.

3. En el cuadro de búsqueda, ingresa la string simple. La pantalla de registros solo muestra la entrada de registro A simple entry.

4. Después de ver el registro, quita la cadena de consulta que agregaste y haz clic en Actualizar (). Ambas entradas de registro volverán a aparecer en la pantalla.

Para mostrar todas las entradas de registro con datos estructurados que tienen una clave de weather en la que el campo value contiene partly, haz lo siguiente:

1. Para cambiar al modo de consulta avanzada, haz clic en el menú desplegable  en el cuadro de consulta y selecciona Convertir en filtro avanzado.

2. El cuadro de consulta contiene la línea resource.type="global". Ingrese el siguiente comando:

   jsonPayload.weather:partly
   

3. Haz clic en Enviar filtro. El resultado es la única entrada de registro My second entry.

El Explorador de registros también ofrece consultas guardadas, sugeridas y recientes. Para obtener más información sobre las consultas, visita Compila consultas en el Explorador de registros.

Para ver consultas de muestra, consulta Consultas de muestra con el Explorador de registros.

Soluciona problemas

• Los errores tipográficos y los nombres de campos desconocidos hacen que los comandos de la herramienta gcloud den el mensaje argumento no válido cuando se completan. Por ejemplo, si olvidas el período en resource.type, se produce el siguiente error:

   ERROR: (gcloud.logging.read) INVALID_ARGUMENT: Field not found: 'resourcetype'.
  

• Cuando Cloud Logging no recibe los permisos de acceso necesarios, la herramienta de gcloud completa con mensajes de permiso denegado. Por ejemplo, si una instancia de VM de Compute Engine está configurada con la opción predeterminada de la API, el comando list se completa con un error de permiso denegado:

   ERROR: (gcloud.logging.read) PERMISSION_DENIED: Request had insufficient authentication scopes.
  

  A fin de resolver este estado, modifica los permisos de la instancia de VM de Compute Engine para otorgarle a Cloud Logging el permiso de lectura, de la siguiente manera:

  1. Ve a la página Detalles de instancia de VM de tu instancia de VM. Haz clic en Detener. Esta acción podría tardar uno o dos minutos en completarse.
  2. Para modificar la configuración, haz clic en Editar.
  3. Busca el encabezado Permiso de acceso a la API de Cloud y haz clic en Detalles para mostrar la configuración de cada API. Cambia la entrada de la API de Cloud Logging a Completo. Haz clic en Guardar.
  4. Para reiniciar las instancias de VM, haz clic en Comenzar. Tras unos instantes, tu VM estará lista para que la uses.

• Cuando el Explorador de API no puede completar tu comando o requiere autorización adicional, muestra un mensaje o código de error:

  • Código de respuesta 200 y ninguna entrada: si se muestra el mensaje nextPageToken, indica que el Explorador de API no tuvo tiempo para completar la búsqueda. Agrega un pageToken a tu solicitud, establece el valor para que sea el mismo que se ingresó con la clave nextPageToken y vuelve a intentar ejecutar el comando.
  • Código de respuesta 400: el valor de la consulta no es válido. Por ejemplo, si escribes mal global como gloobal, el mensaje será Unsupported resource type: gloobal.
  • Código de respuesta 404: el ID del proyecto no es válido. Controla la ortografía del identificador de tu proyecto.
  • Es posible que se te solicite acceder a tu Cuenta de Google y otorgarle acceso a tu cuenta al Explorador de API.

Limpia

Sigue estos pasos para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos que usaste en esta página.

1. (Opcional) Para borrar las entradas de registro que creaste, ejecuta el siguiente comando gcloud:

   gcloud logging logs delete my-test-log
   

   Si no borras tus entradas de registro, expiran y se eliminan. Para obtener información sobre la retención, consulta Cuotas y límites.

¿Qué sigue?

• Para obtener detalles sobre la interfaz de línea de comandos de Logging, lee las páginas de referencia del grupo de comandos gcloud logging.
• Para obtener documentación sobre la API de Logging, consulta API de Cloud Logging.
• Para obtener más información sobre el Explorador de registros, consulta Explorador de registros.
• Para obtener información sobre cómo recopilar entradas de registro de tus instancias de VM en Logging, consulta Acerca del agente de Logging.
• Lee nuestros recursos sobre DevOps y explora nuestro programa de investigación.