Soluciona problemas de la API de Pipelines

La API de Google Genomics Pipelines facilita la ejecución de tareas de procesamiento por lotes en las máquinas virtuales de Google Compute Engine (VM). En este documento, se describe dónde puedes buscar información para solucionar problemas en caso de errores en la canalización, incluidos los siguientes recursos:

Recurso de operación de canalización

Cuando se llama a la API de pipelines.run(), se crea un recurso de operación a fin de mantener un estado importante sobre la canalización. El nombre de la operación se muestra para que puedas hacer un seguimiento del proceso.

Los campos clave en la operación para hacer un seguimiento del progreso son los que figuran a continuación:

done

Cuando se crea la operación, el valor done se establece como false. Cuando se completa la operación (de forma correcta o con un error), done se establece como true.

error

Si surge un error en la operación, la propiedad done se establece como true y se brindará un código y un message de error. A continuación, se incluyen algunos ejemplos:

Operación cancelada

Texto de error

error:
  code: 1
  message: Operation canceled at 2017-02-01T13:46:07-08:00

Descripción

La operación la canceló el usuario mediante la API operations.cancel.

No se encontró el archivo

Archivo de entrada

Texto de error

error:
  code: 5
  message: '9: Failed to localize files: failed to copy the following files: "gs://my-bucket/my-path/input.txt
    -> /mnt/data/input.txt (cp failed: gsutil -q -m cp gs://my-bucket/my-path/input.txt
    /mnt/data/input.txt, command failed: CommandException: No URLs matched: gs://my-bucket/my-path/input.txt\nCommandException:
    1 file/object could not be transferred.\n)"'

Descripción

La canalización tenía un parámetro de entrada con el siguiente:

localCopy: /mnt/data/input.txt
value: gs://my-bucket/my-path/input.txt

No se encontró ningún objeto en la ruta de Cloud Storage, gs://my-bucket/my-path/input.txt.

Archivo de salida

Texto de error

error:
  code: 5
  message: '10: Failed to delocalize files: failed to copy the following files: "/mnt/data/output.txt
    -> gs://my-bucket/my-path/
    (cp failed: gsutil -q -m cp -L /var/log/google-genomics/out.log /mnt/data/output.txt
    gs://my-bucket/my-path/,
    command failed: CommandException: No URLs matched: /mnt/data/output.txt\nCommandException:
    1 file/object could not be transferred.\n)"'

Descripción

La canalización tenía un parámetro de salida con el siguiente fragmento:

localCopy: /mnt/data/output.txt
value: gs://my-bucket/my-path

Cuando se completó la ejecución de Docker, no se encontró ningún archivo en /mnt/data/output.txt en la VM de Compute Engine de la operación.

Imagen de Docker

Texto de error

error:
  code: 5
  message: |
    8: Failed to pull image gcr.io/my-project-id/my-non-existent-image: "gcloud docker -- pull gcr.io/my-project-id/my-non-existent-image" failed: exit status 1: Using default tag: latest
    Pulling repository gcr.io/my-project-id/my-non-existent-image
    Tag latest not found in repository gcr.io/my-project-id/my-non-existent-image

Descripción

La canalización tenía una imagen de Docker especificada como gcr.io/my-project-id/my-non-existent-image. La imagen no se pudo descargar en la VM de Compute Engine, ya que no existía.

Puedes encontrar información con asistencia para subir imágenes de Docker en Cómo enviar a Container Registry.

Cierre de la VM

Texto de error

error:
  code: 10
  message: '13: VM ggp-3407728597191315463 shut down unexpectedly.'

error:
  code: 10
  message: '14: VM ggp-3630732807397428672 stopped unexpectedly.'

Descripción

La VM de Compute Engine de la operación dejó de funcionar inesperadamente. Por lo general, esto se debe a los siguientes motivos:

  • Se interrumpió una VM interrumpible. Para determinar si se interrumpió una VM, sigue estas instrucciones.
  • Un usuario detuvo o quitó explícitamente la instancia de VM.

Comando de Docker con error

error:
  code: 10
  message: |-
    11: Docker run failed: command failed: [STDERR]
    . See logs at gs://my-bucket/my-path/logging

Descripción

El comando de Docker se ejecutó, pero finalizó con un código de salida que no fue de cero.

Se puede encontrar información suficiente en el bloque [STDERR] en la operación.

Puedes encontrar información más detallada en los archivos de registros de la operación.

metadata.events

Como procesos de ejecución para la canalización, los eventos se publicarán, junto con las marcas de tiempo en el arreglo metadata.events de la operación. Un ejemplo típico de los eventos de una canalización se verá de la siguiente manera:

metadata:
  events:
  - description: start
    startTime: '2016-06-21T22:11:19.033492348Z'
  - description: pulling-image
    startTime: '2016-06-21T22:11:19.033538217Z'
  - description: localizing-files
    startTime: '2016-06-21T22:11:41.986968591Z'
  - description: running-docker
    startTime: '2016-06-21T22:11:44.414132377Z'
  - description: delocalizing-files
    startTime: '2016-06-21T22:11:44.867186386Z'
  - description: ok
    startTime: '2016-06-21T22:11:48.363039120Z'

o si ocurre un error cuando se ejecuta el comando de Docker de la canalización:

metadata:
  events:
  - description: start
    startTime: '2016-06-22T17:26:19.774419593Z'
  - description: pulling-image
    startTime: '2016-06-22T17:26:19.774797917Z'
  - description: localizing-files
    startTime: '2016-06-22T17:27:51.700833219Z'
  - description: running-docker
    startTime: '2016-06-22T17:27:51.700872247Z'
  - description: fail
    startTime: '2016-06-22T17:27:54.305925814Z'

Si tu operación parece estar colgada, podría deberse a que no tiene una cuota suficiente para iniciar tu VM. Las advertencias de cuotas se agregan a la lista events mientras la operación está en progreso:

metadata:
  events:
  - description: 'Warning: Quota ''CPUS'' exceeded. Limit: 24.0. Region: us-east1, will try again'
    startTime: '2017-02-11T07:51:45.984778139Z'
  - description: 'Warning: Creating VM and disk(s) would exceed "CPUS" in region us-east1, will try again'
    startTime: '2017-02-11T09:43:35.768859933Z'

Archivos de registro de operación de canalización

Una operación de canalización incluye una ruta de Cloud Storage en donde se escriben los registros. Tres archivos de registros se escriben desde la VM de la canalización. Como los archivos se escriben desde la VM, no habrá archivos de registros si la VM nunca se inicia.

Los tres archivos que se escriben son los siguientes:

  • Registro de canalización: El registro escrito por el software de la canalización que extrae la imagen de Docker, localiza los archivos, ejecuta el comando de Docker y deslocaliza los archivos.
  • Registro stderr: El registro stderr del comando de Docker
  • Registro stdout: El registro stdout del comando de Docker

Para recuperar la ruta de registro de una operación existente, ejecuta en la línea de comandos:

gcloud alpha genomics operations describe <operation-id> \
  --format='value(metadata.request.pipelineArgs.logging)'

Una ruta de Cloud Storage puede ser una de las que se indican a continuación:

  • Una ruta de acceso simple de Cloud Storage
  • Una ruta de acceso de Cloud Storage que termine en ".log"

Una ruta de acceso simple de Cloud Storage

Cuando se proporciona una ruta de acceso simple de Cloud Storage, se la trata como una carpeta del sistema de archivos. Por ejemplo, si especificas gs://my-bucket/my-path/my-pipeline, los nombres de los archivos de registro que se generan serán los siguientes:

  • gs://my-bucket/my-path/my-pipeline/<operation-id>.log
  • gs://my-bucket/my-path/my-pipeline/<operation-id>-stderr.log
  • gs://my-bucket/my-path/my-pipeline/<operation-id>-stdout.log

Una ruta de acceso de Cloud Storage que termine en ".log"

Puedes especificar una ruta de acceso de Cloud Storage que termine en ".log". Por ejemplo, si especificas gs://my-bucket/my-path/my-pipeline.log, entonces los nombres del archivo de registro que se generan serán los siguientes:

  • gs://my-bucket/my-path/my-pipeline.log
  • gs://my-bucket/my-path/my-pipeline-stderr.log
  • gs://my-bucket/my-path/my-pipeline-stdout.log

VM de la canalización

El nombre y la zona de la VM de Compute Engine que ejecuta una canalización se puede encontrar en la operación en el elemento metadata.runtimeMetadata.computeEngine. Mientras la instancia se ejecuta, se lo puede inspeccionar.

Para recuperar zone/instanceName de una operación existente, ejecuta en la línea de comandos:

gcloud alpha genomics operations describe <operation-id> \
   --format='value[separator=/]
                 (metadata.runtimeMetadata.computeEngine.zone,
                  metadata.runtimeMetadata.computeEngine.instanceName)'

Registros de la VM

Entre los registros de la VM se incluyen los siguientes:

  • Registro del sistema Linux.
  • Registro de localización y deslocalización de archivos.
  • Registros del Docker de la canalización.

Existen diferentes formas de ver los registros de la VM:

  • En el visor de registros de Google Cloud Console:

    • Selecciona Instancia de VM en GCE en el primer menú desplegable.
    • Ingresa el nombre de la VM en el cuadro de búsqueda.
    • En el menú desplegable Todos los registros, selecciona syslog.
  • En la página de detalles de la instancia de Google Cloud Console, haz clic en el botón Ver puerto en serie.

  • Ejecuta gcloud compute instances get-serial-port-output zone/instanceName

Todos los métodos antes mencionados funcionan si la VM está activa. Si la VM se detuvo, los registros solo serán accesibles mediante el visor de registros de Google Cloud Console.

Conexión SSH a la VM de una canalización

Es posible que desees abrir una sesión de SSH en la VM de una canalización para examinar el sistema de archivos (espacio de disco disponible) o incluso conectarte al contenedor de Docker que se está ejecutando.

La zone/instanceName del comando de gcloud antes mencionado se puede pasar directamente al comando gcloud compute ssh:

gcloud compute ssh zone/instanceName

Si ocurre un error en la ejecución del comando de Docker o en los archivos de salida de deslocalización, la VM se borra automáticamente. Si necesitas que la VM se ejecute por más tiempo para poder agregar una SSH en ella, utiliza keepVmAliveOnFailureDuration.

De modo similar, si necesitas tiempo para agregar la conexión SSH a la VM antes de que se ejecute el comando de Docker, puedes agregar sleep al comienzo del comando de Docker. Por ejemplo:

sleep $((5*60)); mycommand.sh

te dará 5 minutos extra.

Si el volumen de arranque no tiene espacio, tal vez no puedas agregar SSH a la instancia. Esta puede ser una situación difícil de depurar. Puedes encontrar ideas sobre cómo solucionar este problema en los registros de la VM. Es posible que tengas que cancelar tu operación de canalización existente, recrearla y agregar SSH a la instancia al comienzo del proceso para poder realizar la depuración.

Inspecciona el espacio de disco disponible del sistema de archivos

Una causa simple de errores en la canalización puede ser quedarse sin espacio en disco. Para consultar el espacio de disco disponible, haz lo siguiente:

df -k -h

Verifica la columna Mounted on correspondiente a los volúmenes que te interesan. El volumen de arranque se activará en /.

Todo recurso de disco adicional que se agregue en la canalización se "activará" con el valor mountPoint especificado en la definición de la canalización.

Conéctate con el contenedor de Docker que se está ejecutando

Puedes conectarte con el contenedor de Docker que se está ejecutando mediante el comando Docker exec. Primero, debes obtener el ID o nombre del contenedor.

El comando Docker ps mostrará una lista de los contenedores que se están ejecutando. En una instancia de VM de la canalización, solo hará uno. Por ejemplo:

$ sudo docker ps
CONTAINER ID        IMAGE                COMMAND                CREATED             STATUS              PORTS               NAMES
24e6a7c1e573        java:openjdk-8-jre   "/tmp/ggp-532475336"   10 minutes ago      Up 10 minutes                           clever_chandrasekhar

Para obtener solo el ID del contenedor, utiliza la marca --format:

$ sudo docker ps --format '{{.ID}}'
24e6a7c1e573

Para conectarte a un contenedor que se está ejecutando a fin de ejecutar un shell Bash, haz lo siguiente:

sudo docker exec -t -i <container-id> /bin/bash

Por ejemplo:

$ sudo docker exec -t -i $(sudo docker ps --format '{{.ID}}') /bin/bash
root@24e6a7c1e573:/#

Supervisa la VM

Todas las VM de la canalización tienen el agente de Stackdriver Monitoring instalado, por lo que puedes configurar la supervisión y las alertas de Stackdriver.

Mis canalizaciones no se ejecutan o no detienen la ejecución

No podrás comenzar a ejecutar ni cancelar una canalización que ya se está ejecutando.

En la página IAM en Google Cloud Platform Console, verifica que la función Agente de servicio de Genomics aparece en la lista Miembros para la cuenta de servicio del proyecto correspondiente. (Busca la cuenta de servicio del proyecto que termina en @genomics-api.google.com.iam.gserviceaccount.com).

Si la función Agente de servicio de Genomics no aparece en la lista Miembros utiliza gcloud para agregar la función genomics.serviceAgent a la cuenta de servicio del proyecto correspondiente. Esta función incluye permisos para iniciar y detener instancias de Compute Engine dentro de tu proyecto.

A fin de encontrar PROJECT_ID y PROJECT_NUMBER, consulta Cómo identificar los proyectos.

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:service-PROJECT_NUMBER@genomics-api.google.com.iam.gserviceaccount.com \
    --role=roles/genomics.serviceAgent
¿Te ha resultado útil esta página? Enviar comentarios:

Enviar comentarios sobre...