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 visor 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 Google Cloud o no tienes la facturación habilitada para tu proyecto, sigue estos pasos:

Accede a tu Cuenta de Google.
Si todavía no tienes una cuenta, regístrate para obtener una nueva.

En la página de selección de proyectos de Cloud Console, selecciona o crea un proyecto de 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 a la página Selector de proyectos

Asegúrate de que la facturación esté habilitada para tu proyecto de Google Cloud. Obtén información sobre cómo confirmar que tienes habilitada la facturación para tu proyecto.

Comienza ahora

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.

Cloud Shell

El SDK de Cloud está preinstalado en el entorno de Cloud Shell. No hace falta que instales o configures ningún otro software.
Abre Cloud Shell y verifica la configuración de tu proyecto:
1. En Cloud Console, haz clic en Activar Cloud Shell:
  
  Se abre Cloud Shell en una ventana y muestra un mensaje de bienvenida:
2. El mensaje de bienvenida muestra el ID del proyecto configurado. Si no es el proyecto que deseas usar, ejecuta el siguiente comando después de reemplazar [PROJECT_ID] por el ID de tu proyecto:
```
 gcloud config set project [PROJECT_ID]
```

Instancia de VM

Crea una instancia de VM de Compute Engine:
1. En Cloud Console, selecciona Compute Engine > Instancias de VM (VM instances). Selecciona Crear (Create). Si ves el mensaje que aparece a continuación, espera hasta que Compute Engine esté listo antes de continuar:
2. En Identity and API access (Identidad y acceso a la API), selecciona Set access for each API (Configurar el acceso para cada API). Desplázate por las listas hasta que encuentres la API de Cloud Logging. Cambia el acceso de Solo escritura a Completo:
3. Deja el resto de la configuración con los valores predeterminados y haz clic en Crear (Create). Tras unos instantes, tu instancia de VM estará lista para que la uses.
Para conectarte a la shell de tu instancia de VM, ve a SSH > Abrir en la ventana del navegador. Tras unos instantes, se abre un shell de Debian GNU/Linux en una ventana y muestra un mensaje de bienvenida:
El SDK de Cloud está preinstalado en tu instancia de VM de GCM. Si quieres verificar que el SDK de Cloud está configurado para tu proyecto de Compute Engine, ejecuta este comando:
```
 gcloud config list
```
Si el proyecto detallado no es el que quieres usar, ejecuta el siguiente comando tras reemplazar [PROJECT_ID] con el ID de tu proyecto:
```
 gcloud config set project [PROJECT_ID]
```

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:

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.
Escribe una entrada de registro con datos estructurados en 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 las entradas de registro de Logging y mostrarlas con 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'

Muestra una lista de entradas de registro con el Explorador de API

Puedes utilizar el Explorador de API para ejecutar métodos de la API de Logging sin escribir ningún código. Para leer desde una lista de entradas de registro de Logging, sigue estos pasos:

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
Se muestra el widget Explorador de API. Tiene un encabezado que dice Prueba esta API. Copia el siguiente texto y pégalo en el Cuerpo de la solicitud. Antes de hacer clic en Ejecutar, reemplaza el [PROJECT_ID].
```
  "resourceNames": [
    "projects/[PROJECT_ID]"
  ],
  "filter": "resource.type=global",
  "orderBy": "timestamp desc"
```
A continuación, se muestra un ejemplo de un Cuerpo de solicitud completo con esta configuración:

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 registros en el visor de registros

El visor de registros es una herramienta para ver, consultar y descargar entradas de registro. Para ver los registros en el visor de registros, sigue estos pasos:

Ve al Visor de registros en Google Cloud Console:

Ir al Visor de registros

Verás la página del visor de registros:

Revisa la barra de navegación de Google Cloud y asegúrate de que tu proyecto esté seleccionado. Usa la lista desplegable del proyecto para seleccionar tu proyecto, si es necesario.
En la lista desplegable de tipos de recurso, selecciona Global para ver las entradas de registro que escribiste:

Si no ves la opción del menú Global, o si no ves las entradas de registro, espera unos minutos y actualiza la página. Es posible que Logging tarde unos minutos en recibir las entradas de registro.
Para expandir 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 más información sobre los formatos de datos de entradas de registros, consulta el tipo LogEntry.

Consulta entradas de registro en el visor 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:

En el cuadro de búsqueda, ingresa la string simple. La pantalla de registros solo muestra la entrada de registro A simple entry.
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:

Para cambiar al modo de consulta avanzada, haz clic en el menú desplegable en el cuadro de consulta y selecciona Convertir en filtro avanzado.
El cuadro de consulta contiene la línea resource.type="global". Debajo de esa línea, ingresa esta:
```
jsonPayload.weather:partly
```
Haz clic en Enviar filtro. El resultado es la entrada de registro única My second entry:

Para obtener más información sobre las consultas, ve a la sección de consultas avanzadas 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.

Realiza una limpieza

Sigue estos pasos para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos que usaste en esta guía de inicio rápido.

(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, expirarán y serán eliminadas. Para obtener información sobre la retención, ve a Cuotas y límites.

Próximos pasos

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 más información sobre la API de Logging, consulta API de Cloud Logging.
Para obtener detalles sobre el visor de registros, ve a Visor de registros.
Para obtener información sobre cómo recopilar entradas de registro de tus instancias de VM en Logging, ve a la página Acerca del agente de Logging.