You can export copies of some or all of your logs outside of Stackdriver Logging.
Exporting involves writing a filter that selects the log entries you want to export, and choosing a destination in Cloud Storage, BigQuery, or Cloud Pub/Sub. The filter and destination are held in an object called a sink. Sinks can be created in projects, organizations, folders, and billing accounts.
There are no costs or limitations in Stackdriver Logging for exporting logs, but the export destinations charge for storing or transmitting the log data.
Why export logs?
You might want to export logs for the following reasons:
- To store logs for extended periods. Stackdriver Logging typically holds logs for weeks, not years. For more information, see the Quota Policy.
- To use big data analysis tools on your logs.
- To stream your logs to other applications, other repositories, or third parties.
Sink properties and terminology
Sinks have the following properties:
Sink identifier: A name for the sink. For example,
Parent resource: The resource in which you create the sink. The parent is most often a project, but it can be any of the following:
"projects/[PROJECT_ID]" "folders/[FOLDER_ID]" "billingAccounts/[BILLINGACCOUNT_ID]" "organizations/ORGANIZATION_ID]"
The sink can only export logs that belong to its parent resource. For the one exception to this rule, see the following Aggregated Export property.
The full resource name of a sink includes its parent resource and sink identifier. For example:
Logs filter: Selects which log entries to export through this sink. For more details, see Advanced Logs Filters. For example, the following filter selects all log entries with severity ERROR or higher from a specified Google Compute Engine VM instance:
resource.type = gce_instance AND resource.labels.instance_id = "[INSTANCE_ID]" AND severity >= ERROR
Destination: A single place to send the log entries matching your filter. There are three supported destinations:
Cloud Storage buckets provide inexpensive, long-term storage:
BigQuery datasets provide big data analysis capabilities:
Cloud Pub/Sub topics stream your log entries to other applications or repositories.
You can export logs to destinations in any project, so long as the destination authorizes the sink's service account as a writer.
Writer identity: A service account name. The destination's owner must give this service account permission to write to the destination. When exporting logs, Stackdriver Logging adopts this identity for authorization. For increased security, new sinks get a unique service account:
For more information, see Destination permissions.
Start time and end time (optional). The sink only exports log entries that are time-stamped between these times. Both times are specified in the GMT time zone. For example:
Aggregated export. The
includeChildrenproperty is described in Aggregated Export. It is only relevant to sinks created for organizations.
Output format. The
outputVersionproperty is only relevant to migrating from the v1 API to the v2 API. See the LogSink type.
How sinks work
Every time a log entry arrives in a project, folder, billing account, or organization resource, Stackdriver Logging compares the log entry to the sinks in that resource. Each sink whose filter matches the log entry writes a copy of the log entry to the sink's destination.
Since exporting happens for new log entries only, you cannot export log entries that Stackdriver Logging received before your sink was created.
To create or modify a sink, you must have the IAM roles Owner or Logging/Logs Configuration Writer in the sink's parent resource. To view existing sinks, you must have the IAM roles Viewer or Logging/Logs Viewer in the sink's parent resource. For more information, see Access Control.
To export logs to a destination, the sink's writer service account must be permitted to write to the destination. For more information about writer identities, see the preceding section, Sink properties.
To secure exported logs from unauthorized access, you must use the access control features of your destination. Sinks can export any log entries, including private Data Access audit logs.
Here are some common problems with exports and what to do about them:
Errors from the destination: Check the specification of the destination in the sink. Use projects.sinks.get to find the writer identity for your sink, and be sure that identity is permitted to write to your destination. Your sink begins exporting logs when the errors are corrected.
No logs are being exported: Here are some possible reasons:
- The start or end times in the sink are incorrect. Check that they are formatted correctly. Times are in GMT, not your local time zone. Try removing the start and end times entirely to test the sink.
- No matching log entries have been received since you created your sink. Only new log entries are exported.
- Your filter is incorrect. A misspelled word in the filter might prevent any log entries from matching. Try the same filter in the Logs Viewer's advanced filter interface to see if it matches any log entries.
- There is a delay before you can see your exported logs in the destination. This is especially true of Cloud Storage destinations. See Exported logs availability.
V1 sink migration
The preceding information on this page describes the concepts of logs export provided by the Stackdriver Logging API v2. That version has new sink features and has dropped support for some v1 API sink features. In addition, the output format for exported log entries is different. For details about migrating your sinks to v2, see Migration to Stackdriver Logging API v2.
To learn how to export logs, see the following:
- To use the Logs Viewer, see Exporting Logs.
- To use the Stackdriver Logging API, see Exporting Logs in the API.
- To use the command-line tool, see gcloud logging.
To learn about the format of exported log entries and how the exported logs are organized in destinations, see Using Exported Logs.