Escribe y visualiza registros

En esta página, se describen los registros disponibles cuando se usa Cloud Run y cómo ver y escribir registros.

Cloud Run tiene dos tipos de registros que se envían de forma automática a Cloud Logging:

• Registros de solicitudes (solo servicios): registros de solicitudes enviadas a los servicios de Cloud Run. Estos registros se crean de forma automática.
• Registros de contenedores (servicios y trabajos): registros emitidos desde las instancias, en general desde el código propio, escritos en ubicaciones compatibles como se describe en Escribe registros de contenedores.

Visualizar los registros

Puedes ver los registros de tu servicio o trabajo de varias formas:

• Usa la página de Cloud Run en la consola de Google Cloud.
• Usa Google Cloud CLI para ver registros con gcloud (solo servicios)
• Usa el explorador de registros de Cloud Logging en la consola de Google Cloud
• Usa Cloud Code

Ambos métodos de la consola de visualización de registros analizan los mismos registros almacenados en Cloud Logging, pero el explorador de registros de Cloud Logging proporciona más detalles y más capacidades de filtrado.

Visualiza registros en Cloud Run

Puedes ver los registros de servicios y trabajos en las páginas de servicios y trabajos correspondientes.

Visualiza los registros de un servicio

Para ver los registros de servicio en la página de Cloud Run, debes hacer lo siguiente:

1. Ir a Cloud Run

2. Hacer clic en el servicio deseado en la lista que se muestra

3. Hacer clic en la pestaña REGISTROS para obtener los registros de solicitud y contenedor de todas las revisiones de este servicio. Puedes filtrar por nivel de gravedad del registro

Visualiza los registros de un trabajo

Para ver los registros de un trabajo en la página de Cloud Run, debes hacer lo siguiente:

1. Ir a Cloud Run

2. Haz clic en la pestaña TRABAJOS.

3. Ubica el trabajo en la lista de trabajos y haz clic en él.

4. Hacer clic en la pestaña REGISTROS para obtener los registros de contenedor de todas las ejecuciones de este trabajo. Puedes filtrar por nivel de gravedad del registro

5. Como alternativa, si deseas ver los registros filtrados previamente para una ejecución de trabajo específica, haz clic en la ejecución del trabajo y, luego, en la pestaña REGISTROS.

Visualiza registros de servicio mediante Google Cloud CLI

Vista previa — Command-line logging for Cloud Run services

Esta función está sujeta a las "Condiciones de las Ofertas de Fase Previa a la DG" de la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio. Las funciones de fase previa a la DG están disponibles “tal cual” y podrían tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Puedes usar Google Cloud CLI para ver los registros de cola o leer los registros existentes de un servicio de Cloud Run en la línea de comandos. De forma predeterminada, los registros tienen un formato de línea única optimizado para la consola.

Para poner en cola los registros, debes instalar el componente log-streaming en Google Cloud CLI. Si el componente no está instalado, se te pedirá que lo instales cuando sea necesario.

Visualiza registros de cola en la línea de comandos

Para un servicio de Cloud Run, puedes poner en cola los registros en tiempo real desde el servicio de Cloud Run directamente en la línea de comandos:

gcloud beta run services logs tail SERVICE --project PROJECT-ID

Reemplazar

• SERVICE por el nombre del servicio de Cloud Run
• PROJECT-ID por el ID del proyecto de Google Cloud. Para ver el ID del proyecto, ejecuta el comando gcloud config get-value project.

Lee registros en la línea de comandos

En un servicio de Cloud Run, puedes leer los registros existentes de cualquiera de estas dos maneras:

• En un formato optimizado para la consola, haz lo siguiente:

  gcloud beta run services logs read SERVICE --limit=10 --project PROJECT-ID
  

• Directamente desde Cloud Logging:

  gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=SERVICE" --project PROJECT-ID --limit 10

Reemplazar

• SERVICE por el nombre del servicio de Cloud Run
• PROJECT-ID por el ID del proyecto de Google Cloud. Para ver el ID del proyecto, ejecuta el comando gcloud config get-value project.

Ver registros en Cloud Logging

Para ver los registros de Cloud Run en el explorador de registros de Cloud Logging, sigue estos pasos:

1. Ve al Explorador de registros en la consola de Google Cloud.

   Ir a la página Explorador de registros

2. Selecciona un proyecto de Google Cloud existente en la parte superior de la página o crea un proyecto nuevo.

3. Con los menús desplegables, selecciona el recurso Revisión de Cloud Run para un servicio o Trabajo de Cloud Run para un trabajo.

Para obtener más información, consulta Usa el Explorador de registros.

Visualiza registros de servicio en Cloud Code

Para ver tus registros en Cloud Code, lee las guías de IntelliJ y Visual Studio Code.

Lee registros de manera programática

Si deseas leer los registros de manera programática, puedes usar uno de estos métodos:

• Usa un receptor de registros en Pub/Sub y una secuencia de comandos para extraerlos de Pub/Sub.
• Llama a la API de Logging mediante las bibliotecas cliente del lenguaje de programación que uses.
• Llama a los extremos de la API de REST de Logging directamente.

Escribe registros de contenedores

Cuando escribes registros desde el servicio o trabajo, Cloud Logging los selecciona de manera automática, siempre y cuando se escriban en cualquiera de estas ubicaciones:

• Transmisiones de salida estándar (stdout) o de error estándar (stderr)
• Cualquier archivo en el directorio /var/log
• Syslog (/dev/log)
• Registros escritos mediante bibliotecas cliente de Cloud Logging, que están disponibles para muchos lenguajes populares

Se espera que la mayoría de los desarrolladores escriban registros mediante transmisiones de salida estándar y error estándar.

Los registros de contenedores escritos en estas ubicaciones compatibles se asocian de manera automática con el servicio, la revisión y la ubicación de Cloud Run o con el trabajo de Cloud Run. Las excepciones en estos registros se capturan y se informan en Error Reporting.

Comparación entre el uso de texto simple y de JSON estructurado en los registros

Cuando escribes registros, puedes enviar una string de texto simple o una sola línea de JSON serializado, que también se conoce como datos estructurados. Cloud Logging lo recopila y analiza, y se coloca en jsonPayload. En cambio, el mensaje de texto simple se coloca en textPayload.

Escribe registros estructurados

En el siguiente fragmento, se muestra cómo escribir entradas de registro estructuradas. También se muestra cómo correlacionar los mensajes de registro con el registro de solicitud correspondiente.

Node.js

// Uncomment and populate this variable in your code:
// const project = 'The project ID of your function or Cloud Run service';

// Build structured log messages as an object.
const globalLogFields = {};

// Add log correlation to nest all log messages beneath request log in Log Viewer.
// (This only works for HTTP-based invocations where `req` is defined.)
if (typeof req !== 'undefined') {
  const traceHeader = req.header('X-Cloud-Trace-Context');
  if (traceHeader && project) {
    const [trace] = traceHeader.split('/');
    globalLogFields['logging.googleapis.com/trace'] =
      `projects/${project}/traces/${trace}`;
  }
}

// Complete a structured log entry.
const entry = Object.assign(
  {
    severity: 'NOTICE',
    message: 'This is the default display field.',
    // Log viewer accesses 'component' as 'jsonPayload.component'.
    component: 'arbitrary-property',
  },
  globalLogFields
);

// Serialize to a JSON string and output.
console.log(JSON.stringify(entry));

Python

# Uncomment and populate this variable in your code:
# PROJECT = 'The project ID of your Cloud Run service';

# Build structured log messages as an object.
global_log_fields = {}

# Add log correlation to nest all log messages.
# This is only relevant in HTTP-based contexts, and is ignored elsewhere.
# (In particular, non-HTTP-based Cloud Functions.)
request_is_defined = "request" in globals() or "request" in locals()
if request_is_defined and request:
    trace_header = request.headers.get("X-Cloud-Trace-Context")

    if trace_header and PROJECT:
        trace = trace_header.split("/")
        global_log_fields[
            "logging.googleapis.com/trace"
        ] = f"projects/{PROJECT}/traces/{trace[0]}"

# Complete a structured log entry.
entry = dict(
    severity="NOTICE",
    message="This is the default display field.",
    # Log viewer accesses 'component' as jsonPayload.component'.
    component="arbitrary-property",
    **global_log_fields,
)

print(json.dumps(entry))

Go

Un tipo de Entry proporciona la estructura para cada entrada de registro:

// Entry defines a log entry.
type Entry struct {
	Message  string `json:"message"`
	Severity string `json:"severity,omitempty"`
	Trace    string `json:"logging.googleapis.com/trace,omitempty"`

	// Logs Explorer allows filtering and display of this as `jsonPayload.component`.
	Component string `json:"component,omitempty"`
}

// String renders an entry structure to the JSON format expected by Cloud Logging.
func (e Entry) String() string {
	if e.Severity == "" {
		e.Severity = "INFO"
	}
	out, err := json.Marshal(e)
	if err != nil {
		log.Printf("json.Marshal: %v", err)
	}
	return string(out)
}

Cuando se registra una estructura de Entry, se llama al método String para serializarla según el formato JSON que espera Cloud Logging:

func init() {
	// Disable log prefixes such as the default timestamp.
	// Prefix text prevents the message from being parsed as JSON.
	// A timestamp is added when shipping logs to Cloud Logging.
	log.SetFlags(0)
}

func indexHandler(w http.ResponseWriter, r *http.Request) {
	// Uncomment and populate this variable in your code:
	// projectID = "The project ID of your Cloud Run service"

	// Derive the traceID associated with the current request.
	var trace string
	if projectID != "" {
		traceHeader := r.Header.Get("X-Cloud-Trace-Context")
		traceParts := strings.Split(traceHeader, "/")
		if len(traceParts) > 0 && len(traceParts[0]) > 0 {
			trace = fmt.Sprintf("projects/%s/traces/%s", projectID, traceParts[0])
		}
	}

	log.Println(Entry{
		Severity:  "NOTICE",
		Message:   "This is the default display field.",
		Component: "arbitrary-property",
		Trace:     trace,
	})

	fmt.Fprintln(w, "Hello Logger!")
}

Java

Para habilitar el registro JSON con Logback y SLF4J, debes habilitar el codificador de JSON de Logstash en la configuración logback.xml.

// Build structured log messages as an object.
Object globalLogFields = null;

// Add log correlation to nest all log messages beneath request log in Log Viewer.
// TODO(developer): delete this code if you're creating a Cloud
//                  Function and it is *NOT* triggered by HTTP.
String traceHeader = req.headers("x-cloud-trace-context");
if (traceHeader != null && project != null) {
  String trace = traceHeader.split("/")[0];
  globalLogFields =
      kv(
          "logging.googleapis.com/trace",
          String.format("projects/%s/traces/%s", project, trace));
}
// -- End log correlation code --

// Create a structured log entry using key value pairs.
logger.error(
    "This is the default display field.",
    kv("component", "arbitrary-property"),
    kv("severity", "NOTICE"),
    globalLogFields);

Personaliza los nombres de campos estándar para excluir el contenido no deseado de la transferencia en la carga útil de los registros. Para obtener una lista de nombres de campos y los formatos de datos esperados, consulta Usa el agente de Logging.

<configuration>
  <appender name="jsonConsoleAppender" class="ch.qos.logback.core.ConsoleAppender">
    <encoder class="net.logstash.logback.encoder.LogstashEncoder">
      <!-- Ignore default logging fields -->
      <fieldNames>
        <timestamp>[ignore]</timestamp>
        <version>[ignore]</version>
        <logger>[ignore]</logger>
        <thread>[ignore]</thread>
        <level>[ignore]</level>
        <levelValue>[ignore]</levelValue>
      </fieldNames>
    </encoder>
  </appender>
  <root level="INFO">
    <appender-ref ref="jsonConsoleAppender"/>
  </root>
</configuration>

Campos JSON especiales en los mensajes

Cuando proporcionas un registro estructurado como un diccionario JSON, algunos campos especiales se quitan de jsonPayload y se escriben en el campo correspondiente en la LogEntry generada, como se describe en la documentación sobre campos especiales.

Por ejemplo, si el JSON incluye una propiedad severity, se quita de jsonPayload y aparece como la severity de la entrada de registro. La propiedad message se usa como el texto de visualización principal de la entrada de registro si está presente. Para obtener más información sobre las propiedades especiales, lee la sección Recurso de registro.

Correlaciona los registros del contenedor con un registro de solicitud (solo servicios)

En el Explorador de registros, los registros que se correlacionan por el mismo trace se pueden ver en formato de “superior-secundario”. Cuando haces clic en el ícono de triángulo a la izquierda de la entrada de registro de la solicitud, los registros de contenedores relacionados con esa solicitud aparecen anidados en el registro de solicitud.

Los registros de contenedores no se correlacionan de forma automática con los registros de solicitudes, a menos que uses una biblioteca cliente de Cloud Logging. Para correlacionar registros de contenedores con registros de solicitudes sin usar una biblioteca cliente, puedes usar una línea de registro JSON estructurada que contenga un campo logging.googleapis.com/trace con el identificador de seguimiento extraído del encabezado X-Cloud-Trace-Context, como se muestra en el ejemplo anterior de un registro estructurado.

Controla el uso de recursos de registros de solicitudes (solo servicios)

Los registros de solicitudes se crean de forma automática. Aunque no puedes controlar la cantidad de registros de solicitudes directamente desde Cloud Run, puedes usar la función de exclusión de registros de Cloud Logging.

Nota sobre los agentes de registro

Si usaste Cloud Logging con ciertos productos de Google Cloud, como Compute Engine, es posible que hayas usado agentes de registro de Cloud Logging. Cloud Run no usa agentes de registro porque tiene compatibilidad integrada en la recopilación de registros.

Nombres de recursos de registro

Los nombres de los recursos de registro para Cloud Run son los siguientes:

• Revisión de Cloud Run (cloud_run_revision).
• Trabajo de Cloud Run (cloud_run_job).

Recursos de registro

Si haces clic en una entrada de registro en el Explorador de registros, se abre una entrada de registro con formato JSON para que puedas desglosar los detalles que desees.

Todos los campos de una entrada de registro, como las marcas de tiempo, la gravedad y las httpRequest, son estándar y se describen en la documentación sobre una entrada de registro.

Cloud Run agrega metadatos adicionales para que puedas identificar el origen de un registro. Esto incluye las etiquetas que estableces en el servicio de Cloud Run y las etiquetas de recursos específicas de Cloud Run.

Campos de entradas de registro de un servicio

La siguiente es una lista de campos que se pueden encontrar en la entrada de registro de un servicio de Cloud Run:

Campo	Valores y notas
LogEntry.labels.instanceId	La instancia que controló la solicitud.
LogEntry.labels.mylabel, LogEntry.labels.mysecondlabel	Las etiquetas que configuras en el servicio.
LogEntry.logName	Identifica el registro, por ejemplo, registro de solicitud, error estándar, salida estándar, etc.
LogEntry.resource.labels.location	Identifica la ubicación de Google Cloud del servicio.
LogEntry.resource.labels.project_id	El proyecto en el que se implementa el servicio.
LogEntry.resource.labels.revision_name	La revisión que entregó la solicitud.
LogEntry.resource.labels.service_name	El servicio que entregó la solicitud.
LogEntry.resource.type	cloud_run_revision. El tipo de recurso de Cloud Run.

A continuación, se muestra un ejemplo de una entrada de registro de solicitud para un servicio de Cloud Run:

{
 httpRequest: {…}
 insertId:  "5c82b3d1000ece0000000000"
 labels: {
  instanceId:  "00bf4bf00000fb59c906a00000c9e29c2c4e06dce91500000000056008d2b6460f163c0057b97b2345f2725fb2423ee5f0bafd36df887fdb1122371563cf1ff453717282afe000001"
  mylabel: "mylabelvalue"
  mysecondlabel: "mysecondlabelvalue"
 }
 logName:  "projects/my-project/logs/run.googleapis.com%2Frequests"
 receiveTimestamp:  "2019-03-08T18:26:25.981686167Z"
 resource: {
  labels: {
   configuration_name:  "myservice"
   location:  "us-central1"
   project_id:  "my-project"
   revision_name:  "myservice-00002"
   service_name:  "myservice"
  }
  type:  "cloud_run_revision"
 }
 severity:  "INFO"
 timestamp:  "2019-03-08T18:26:25.970397Z"
}

Campos de entradas de registro para trabajos

La siguiente es una lista de campos que se pueden encontrar en la entrada de registro de un trabajo de Cloud Run:

Campo	Valores y notas
LogEntry.labels.instanceId	La instancia.
LogEntry.labels.mylabel, LogEntry.labels.mysecondlabel	Las etiquetas que configuras en el trabajo.
LogEntry.logName	Identifica el registro, por ejemplo, registro de solicitud, error estándar, salida estándar, etcétera.
LogEntry.resource.labels.location	Identifica la ubicación de Google Cloud del servicio.
LogEntry.resource.labels.project_id	El proyecto en el que se implementa el servicio.
LogEntry.resource.labels.job_name	Es el nombre del trabajo.
LogEntry.labels.execution_name	Es el nombre de la ejecución del trabajo.
LogEntry.labels.task_index	El índice de la tarea.
LogEntry.labels.task_attempt	Cuántas veces se intentó esta tarea.
LogEntry.resource.type	cloud_run_job. El tipo de recurso de Cloud Run.