Como gerar registros e visualizar registros no Knative

Nesta página, descrevemos os registros disponíveis ao usar o Knative serving e como visualizá-los e gravar registros.

O Knative serving tem dois tipos de registros:

• Registros de solicitações: registros de solicitações enviados aos serviços do Knative serving. Esses registros são criados automaticamente.
• Registros de contêiner: registros emitidos das instâncias de contêiner, normalmente de seu próprio código, gravados em locais compatíveis, conforme descrito em Como gravar registros de contêiner.

Como ativar registros

Os registros do Google Cloud são enviados automaticamente para o Cloud Logging. Para o Google Distributed Cloud, primeiro é necessário ativar os registros.

Como ver registros

É possível ver os registros do seu serviço de duas maneiras:

• Usar a página do Knative serving no console do Google Cloud
• Usar o Explorador de registros do Cloud Logging no Console do Google Cloud

Esses dois métodos de visualização examinam os mesmos registros armazenados no Cloud Logging, mas o Explorador de registros fornece mais detalhes e mais recursos de filtragem.

Como visualizar registros no Knative serving

Para conferir os registros na página de Knative serving:

1. Acessar o Knative serving

2. Clique no serviço de sua escolha na lista exibida.

3. Clique na guia REGISTROS para receber os registros de solicitação e contêiner para todas as revisões desse serviço. É possível filtrar por nível de gravidade de registro.

Como ver registros no Cloud Logging

Para conferir os registros do Knative serving na Análise de registros do Cloud Logging:

1. Acesse a página "Explorador de registros" no console do Google Cloud:

2. Selecione um projeto atual do Google Cloud na parte superior da página ou crie um novo.

3. Usando os menus suspensos, selecione o recurso: Kubernetes Container.

Para mais informações, consulte Como usar o Explorador de registros.

Como visualizar registros no Cloud Code

Para visualizar registros no Cloud Code, leia os guias do IntelliJ e do Visual Studio Code.

Como ler registros de maneira programática

Se você quiser ler os registros de maneira programática, use um destes métodos:

• Use um coletor de registros para o Pub/Sub e um script para receber do Pub/Sub.
• Chame a API Logging usando as bibliotecas de cliente da linguagem de programação sendo usada.
• Chame diretamente os endpoints da API REST do Logging.

Como gravar registros de contêiner

Quando você grava registros do seu serviço, eles serão coletados automaticamente pelo Cloud Logging, desde que os registros sejam gravados em qualquer um dos seguintes locais:

• Streamings de saída padrão (stdout) ou de erro padrão (stderr)
• syslog (/dev/log)
• Registros gravados usando as bibliotecas de cliente do Cloud Logging, disponíveis para muitas linguagens conhecidas

Espera-se que a maioria dos desenvolvedores grave registros usando a saída e o erro padrão.

Os registros de contêiner gravados nesses locais compatíveis são automaticamente associados ao serviço, à revisão e ao local do Knative serving.

Como usar texto simples ou JSON estruturado nos registros

Ao gravar registros, é possível enviar uma string de texto simples ou uma única linha de JSON serializado, também chamado de dados "estruturados". Ela é selecionada e analisada pelo Cloud Logging e colocada em jsonPayload. Por outro lado, a mensagem de texto simples é colocada em textPayload.

Como gravar registros estruturados

O snippet a seguir mostra como gravar entradas de registro estruturadas. Ele também mostra como correlacionar mensagens de registro com o registro de solicitação correspondente.

// 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));

# 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))

// 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)
}

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!")
}

// 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.
// For instantiating the "logger" variable, see
// https://cloud.google.com/run/docs/logging#run_manual_logging-java
logger.error(
    "This is the default display field.",
    kv("component", "arbitrary-property"),
    kv("severity", "NOTICE"),
    globalLogFields);

<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 especiais nas mensagens

Quando você fornece um registro estruturado como um dicionário JSON, alguns campos especiais são retirados do jsonPayload e gravados no campo correspondente no LogEntry gerado, conforme descrito na documentação sobre campos especiais.

Por exemplo, se o JSON incluir uma propriedade severity, ela será removida do jsonPayload e aparecerá como severity da entrada de registro. A propriedade message é usada como o texto de exibição principal da entrada de registro, se houver. Para mais informações sobre propriedades especiais, leia a seção Recurso de geração de registros abaixo.

Como correlacionar registros de contêiner com um registro de solicitação

No explorador de registros, os registros correlacionados pelos mesmos trace são visíveis no formato “pai-filho”: quando você clicar no ícone de triângulo à esquerda da entrada de registro de solicitação, os registros do contêiner relacionados a essa solicitação aparecerão aninhados no registro da solicitação.

Os registros de contêiner não são correlacionados automaticamente com os registros de solicitação, a menos que você use uma biblioteca de cliente do Cloud Logging. Para correlacionar registros de contêineres com os registros de solicitação sem usar uma biblioteca de cliente, use uma linha de registro JSON estruturado que contenha um campo logging.googleapis.com/trace com o identificador de trace extraído do cabeçalho X-Cloud-Trace-Context, como mostrado na amostra acima para geração de registros estruturados.

Como controlar o uso do recurso de registro de solicitações

Os registros de solicitação são criados automaticamente. Não é possível controlar a quantidade de registros de solicitação diretamente do Knative serving, mas é possível usar o recurso de exclusão de registros do Cloud Logging.

Uma observação sobre agentes do Logging

Se você usou o Cloud Logging com determinados produtos do Google Cloud, como o Compute Engine, é possível que tenha usado agentes do Cloud Logging. O Knative serving não usa agentes do Logging porque tem suporte integrado para a coleta de registros.

Recurso de geração de registros

Clicar em uma entrada de registro no explorador de registros abre uma entrada de registro formatada em JSON para que você possa detalhar o que você quer.

Todos os campos em uma entrada de registro, como carimbos de data/hora, gravidade e httpRequest, são padrão e estão descritos na documentação sobre a entrada de registro.

No entanto, existem alguns rótulos ou rótulos de recursos que são especiais para o Knative serving. Eles estão listados aqui com o conteúdo de exemplo:

{
 httpRequest: {…}
 insertId:  "5c82b3d1000ece0000000000"
 labels: {
  instanceId:  "00bf4bf00000fb59c906a00000c9e29c2c4e06dce91500000000056008d2b6460f163c0057b97b2345f2725fb2423ee5f0bafd36df887fdb1122371563cf1ff453717282afe000001"
 }
 logName:  "projects/my-project/logs/kubernetes-engine/enterprise/knative-serving/.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"
}