Basic concepts

Cloud Logging is part of the Google Cloud's operations suite of products in Google Cloud. It includes storage for logs, a user interface called the Logs Explorer, and an API to manage logs programmatically. Logging lets you read and write log entries, query your logs, and control how you route and use your logs.

Google Cloud projects and other resources

Logs are associated primarily with Google Cloud projects, although other Google Cloud resources, such as organizations, folders, and billing accounts, can also have logs.

Log entries

A log entry records status or describes specific events that take place in computer systems. Log entries are written by your own code, Google Cloud services the code is running on, third-party applications, and the infrastructure that the platform depends on.

Because logs in modern systems descend from text files written to disk, a log entry is analogous to a line in a log file and can be considered the quantum unit of logging.

Your Google Cloud project receives log entries when you begin to use the services that produce log entries, like Compute Engine or BigQuery. You also get log entries when you connect Cloud Monitoring to AWS, when you install the Logging agent on your VM instances, and when you call the entries.write method in the Logging API.

A log entry minimally consists of the following:

  • A timestamp that indicates either when the event took place or when it was ingested into the logging system.
  • A text payload, also known as a message, either as unstructured textual data or structured textual data, most commonly in JSON.
  • The name of the log to which it belongs.

For more information on log entry data formats, see the LogEntry type.

Logs

A log is a named collection of log entries within a Google Cloud resource, such as a project. Logs exist only if they contain log entries.

A log's name can be a simple identifier, like syslog, or a structured name that includes the log's writer, like compute.googleapis.com/activity. Each log entry includes the name of its log.

Logs can also carry associated metadata, especially when they're ingested into Cloud Logging. Such metadata might include the log name, the resource that's writing the log, and a severity for each associated log entry.

Logs usually describe events or transactions:

  • Event logs describe specific events that take place within the system. You can use event logs to output messages that assure users that things are working well or to provide information when things fail.
  • Transaction logs describe the details of transactions processed by a system or component. For example, a load balancer logs every request that it receives, whether the request is successfully completed or not, and records additional information like the requested URL, HTTP response code, and possibly information like which backend was used to serve the request.

Log types

To learn about the types of logs available in Cloud Logging, see Available logs.

Retention period

Log entries are held in Cloud Logging for a limited time known as the retention period. After that, the entries are deleted. The retention periods for different types of logs are listed in Logging Quotas and limits.

You can configure the retention periods of some of your logs. For details, see Storing logs: Custom retention.

If you also want to back up your logs, export them outside of Cloud Logging.

Monitored resources

Each log entry indicates where it came from by including the name of a monitored resource. Examples include individual Compute Engine VM instances, Google Kubernetes Engine containers, database instances, and so on.

For a complete listing of monitored resource types, see Monitored resources and services.

Queries

A query is a filter expression in the Logging query language. It is used in the Logs Explorer and the Logging API to select log entries, such as those from a particular VM instance or those arriving in a particular time period with a particular severity level.

Logs Router

All logs, including audit logs, platform logs, and user logs, are sent to the Cloud Logging API where they pass through the Logs Router. The Logs Router checks each log entry against existing rules to determine which log entries to ingest (store), which log entries to include in exports, and which log entries to discard.

For more details, see Logs Router overview.

Exporting logs using sinks

Log entries received by Logging can be exported to Cloud Storage buckets, BigQuery datasets, and Pub/Sub topics.

You export logs by configuring log sinks, which then continue to export log entries as they arrive in Logging. A sink includes a destination and a query that selects the log entries to export.

For details, see Overview of logs exports.

Logs-based metrics

Metrics are a feature of Cloud Monitoring. A logs-based metric is a metric whose value is the number of log entries that match a query that you specify.

For details, see Overview of logs-based metrics

Access control

The ability to access Logging logs is controlled by granting Identity and Access Management permissions to members.

Most logs can be read by any member with the IAM Viewer role. To read Data Access audit logs or Access Transparency logs, the member requires either the IAM Owner role or a custom role with special permissions.

For more information on required permissions, see Access control.