Guía de inicio rápido del uso del SDK de Cloud

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

  • Escribir entradas de registro con el SDK de Cloud
  • Ver y filtrar entradas de registro con el visor de registros
  • Mostrar una lista con entradas de registro con el SDK de Cloud
  • Mostrar una lista de entradas de registro con la API de Logging

Antes de comenzar

Para completar esta guía de inicio rápido, debes tener un proyecto de Google Cloud Platform con la facturación habilitada. Si no tienes un proyecto de GCP, o si no tienes la facturación activada para tu proyecto, sigue estos pasos:
  1. Accede a tu Cuenta de Google.

    Si todavía no tienes una cuenta, regístrate para obtener una nueva.

  2. Selecciona o crea un proyecto de GCP.

    Ir a la página Administrar recursos

  3. Comprueba que la facturación esté habilitada en tu proyecto.

    Descubre cómo puedes habilitar la facturación

Comienza

Puedes utilizar el entorno de Cloud Shell o una instancia de VM de Compute Engine para los comandos del SDK de Cloud en esta guía de inicio rápido.

Cloud Shell

  1. El SDK de Cloud está preinstalado en el entorno de Cloud Shell. No hace falta que instales o configures ningún otro software.

  2. Abre Cloud Shell y verifica la configuración de tu proyecto:

    1. Desde GCP Console, haz clic en el botón Activar Cloud Shell en la esquina superior derecha:

      Activar Cloud Shell

      Cloud Shell se abre en una ventana y muestra un mensaje de bienvenida:

      Welcome to Cloud Shell

    2. El mensaje de bienvenida muestra el ID del proyecto configurado. Si no es el proyecto que querías utilizar, ejecuta el siguiente comando una vez que hayas reemplazado [PROJECT_ID] con el ID de tu proyecto:

       gcloud config set project [PROJECT_ID]
      

Instancia de VM

  1. Crea una instancia de VM de Compute Engine:

    1. Desde GCP 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:

      Compute preparándose

    2. En el panel Identidad y acceso a la API (Identity and API access), selecciona Configurar el acceso para cada API (Set access for each API). Desplázate hacia abajo por las listas en el nuevo panel hasta encontrar la API de Stackdriver Logging. Cambia el acceso de Solo escritura a Completo:

      Compute preparándose

    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.

  2. Para conectar el 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:

  3. El SDK de Cloud está preinstalado en tu instancia de VM de GCM. Verifica que el SDK de Cloud esté configurado para tu proyecto de Compute Engine:

     gcloud config list
    
  4. Si el proyecto detallado no es el que quieres utilizar, 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 el SDK de Cloud

Logging acepta 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 próximos pasos, utilizarás el SDK de Cloud para escribir una entrada de registro con datos no estructurados y una con datos estructurados:

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

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

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

  2. 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, la carga útil se interpreta como texto no estructurado.

Si el registro my-test-log no existe, Logging lo crea cuando recibe la entrada de registro.

Visualiza registros en el visor de registros

El visor de registros es una herramienta para ver, filtrar y descargar entradas de registro:

  1. Ve a la página del visor de registros en Google Cloud Platform Console:

    Ir a la página del visor de registros

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

    Visor de registros

    Verifica la barra de navegación de Google Cloud Platform y asegúrate de que tu proyecto esté seleccionado. Utiliza la lista desplegable del proyecto para seleccionar tu proyecto, si es necesario.

  2. En la lista desplegable de tipos de recurso, selecciona Global para ver las entradas de registro que escribiste:

    Visor de registros global

    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.

  3. Para expandir una entrada de registro, haz clic en el botón Divulgación (arrow_right).

    Visor de registros

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

Para obtener más información sobre formatos de datos de entradas de registro, consulta Tipos de datos comunes a todos los registros.

Filtra entradas de registro

Para filtrar entradas de registro puedes utilizar un campo de texto y registros estructurados por clave y valor. Por ejemplo, para mostrar todas las entradas de registro que contiene el texto simple, sigue estos pasos:

  1. En el cuadro de filtro por encima del selector de registros, ingresa la string simple. La pantalla de registros muestra solamente la entrada de registro A simple entry.

  2. Una vez que hayas visto tu registro, quita la string de filtro que agregas y haz clic en el botón Actualizar (refresh) que se encuentra arriba del selector de registros. Ambas entradas de registro volverán a aparecer en la pantalla.

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

  1. Para cambiar al modo de filtro avanzado, haz clic en el botón Divulgar (arrow_drop_down) en el extremo derecho del cuadro de filtro y, a continuación, selecciona Convertir a filtro avanzado.
  2. El cuadro de filtro contiene resource.type="global". Debajo de esta línea, ingresa lo siguiente:

    jsonPayload.weather:partly
    
  3. Haz clic en Enviar filtro (Submit filter). El resultado es una única entrada de registro My second entry:

    Filtro avanzado para entradas de registro

Para obtener información sobre los filtros, consulta Filtros de registros avanzados.

Muestra una lista con entradas de registro con el SDK de Cloud

Puedes recuperar entradas de registro de Logging y mostrarlas mediante el SDK de Cloud. 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:

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

    [Ve a la página de la API entries.list](/logging/docs/reference/v2/rest/v2/entries/list){:target="_blank" class="button button-primary"}

  2. El widget del Explorador de API está a la derecha o al final de la página. 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"
    

    A continuación, se muestra un ejemplo de un Cuerpo de solicitud completo con esta configuración:

    Prueba esta API

  3. Haz clic en Ejecutar (Execute). 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"
        }
      ]
    }
    

Solución de problemas

  • Los errores tipográficos y los nombres de campos desconocidos producen mensajes de argumento no válido cuando se completan los comandos del SDK de Cloud. Por ejemplo, si te olvidas el punto en resource.type, producirá el siguiente error:

     ERROR: (gcloud.logging.read) INVALID_ARGUMENT: Field not found: 'resourcetype'.
    
  • Cuando Stackdriver Logging no recibe los permisos de acceso necesarios, producen mensajes de permiso denegado cuando se completan los comandos del SDK de Cloud. Por ejemplo, si una instancia de VM de Compute Engine está configurada con la configuración predeterminada de la API de Cloud, 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 Stackdriver Logging permiso de lectura:

    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 Alcance del acceso de la API de Cloud y haz clic en Detalles para mostrar la configuración de cada API. Cambia la entrada de la API de Stackdriver 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 la API no tuvo tiempo de 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 error 400: El valor del filtro no es válido. Por ejemplo, si escribiste 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 al Explorador de API a tu cuenta.

Limpieza

Para evitar que se apliquen cargos a tu cuenta de GCP por los recursos que se utilizan en esta guía de inicio rápido, haz lo siguiente:

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

    gcloud logging logs delete my-test-log
    

    Si no las borras, caducarán y se quitarán. Consulta Política de la cuota.

¿Qué sigue?

  • Consulta Visor de registros para obtener una descripción más detallada sobre este.
  • Consulta Exporta registros para aprender a exportar tus entradas de registro a Cloud Storage, BigQuery y Cloud Pub/Sub.
  • Consulta Agente de registro para aprender a recopilar entradas de registro de las instancias de tu máquina virtual en Logging.
  • Consulta Registros de auditoría para obtener información sobre tus necesidades de auditoría y cumplimiento.
  • Consulta API de Stackdriver Logging para descubrir cómo leer, escribir y configurar registros desde tus aplicaciones.
¿Te ha resultado útil esta página? Enviar comentarios:

Enviar comentarios sobre...

Stackdriver Logging
Si necesitas ayuda, visita nuestra página de asistencia.