Module: Gcloud::Logging

Defined in:

lib/gcloud/logging.rb,
lib/gcloud/logging/sink.rb,
lib/gcloud/logging/entry.rb,
lib/gcloud/logging/logger.rb,
lib/gcloud/logging/metric.rb,
lib/gcloud/logging/project.rb,
lib/gcloud/logging/service.rb,
lib/gcloud/logging/resource.rb,
lib/gcloud/logging/sink/list.rb,
lib/gcloud/logging/entry/list.rb,
lib/gcloud/logging/credentials.rb,
lib/gcloud/logging/metric/list.rb,
lib/gcloud/logging/entry/operation.rb,
lib/gcloud/logging/entry/http_request.rb,
lib/gcloud/logging/resource_descriptor.rb,
lib/gcloud/logging/resource_descriptor/list.rb

Overview

# Google Cloud Logging

The Google Cloud Logging service collects and stores logs from applications and services on the Google Cloud Platform, giving you fine-grained, programmatic control over your projects’ logs. You can use the Cloud Logging API to:

• [Read and filter log entries](#listing-log-entries)

• [Export your log entries](#exporting-log-entries) to Cloud Storage, BigQuery, or Cloud Pub/Sub

• [Create logs-based metrics](#creating-logs-based-metrics) for use in Cloud Monitoring

• [Write log entries](#writing-log-entries)

For general information about Cloud Logging, read [What is Google Cloud Logging?](cloud.google.com/logging/docs/).

Gcloud’s goal is to provide an API that is familiar and comfortable to Rubyists. Authentication is handled by #logging. You can provide the project and credential information to connect to the Cloud Logging service, or if you are running on Google Compute Engine this configuration is taken care of for you. You can read more about the options for connecting in the [Authentication Guide](googlecloudplatform.github.io/gcloud-ruby/#/docs/guides/authentication).

## Listing log entries

Cloud Logging gathers log entries from many services, including Google App Engine and Google Compute Engine. (See the [List of Log Types](cloud.google.com/logging/docs/view/logs_index).) In addition, you can write your own log entries to the service.

Project#entries returns the Entry records belonging to your project:

“‘ruby require “gcloud”

gcloud = Gcloud.new logging = gcloud.logging entries = logging.entries entries.each do |e|

puts "[#{e.timestamp}] #{e.log_name} #{e.payload.inspect}"

end “‘

You can narrow the results to a single log using an [advanced logs filter](cloud.google.com/logging/docs/view/advanced_filters). A log is a named collection of entries. Logs can be produced by Google Cloud Platform services, by third-party services, or by your applications. For example, the log compute.googleapis.com/activity_log is produced by Google Compute Engine. Logs are simply referenced by name in Gcloud. There is no Log type in Gcloud or Log resource in the Cloud Logging API.

“‘ruby require “gcloud”

gcloud = Gcloud.new logging = gcloud.logging entries = logging.entries filter: “log:syslog” entries.each do |e|

puts "[#{e.timestamp}] #{e.payload.inspect}"

end “‘

You can also order the log entries by timestamp.

“‘ruby require “gcloud”

gcloud = Gcloud.new logging = gcloud.logging entries = logging.entries order: “timestamp desc” entries.each do |e|

puts "[#{e.timestamp}] #{e.log_name} #{e.payload.inspect}"

end “‘

## Exporting log entries

Cloud Logging lets you export log entries to destinations including Google Cloud Storage buckets (for long term log storage), Google BigQuery datasets (for log analysis), and Google Pub/Sub (for streaming to other applications).

### Creating sinks

A Sink is an object that lets you to specify a set of log entries to export.

In addition to the name of the sink and the export destination, Project#create_sink accepts an [advanced logs filter](cloud.google.com/logging/docs/view/advanced_filters) to narrow the collection.

Before creating the sink, ensure that you have granted ‘cloud-logs@google.com` permission to write logs to the destination. See [Permissions for writing exported logs](cloud.google.com/logging/docs/export/configure_export#setting_product_name_short_permissions_for_writing_exported_logs).

“‘ruby require “gcloud”

gcloud = Gcloud.new logging = gcloud.logging storage = gcloud.storage

bucket = storage.create_bucket “my-logs-bucket”

# Grant owner permission to Cloud Logging service email = “cloud-logs@google.com” bucket.acl.add_owner “group-#email”

sink = logging.create_sink “my-sink”, “storage.googleapis.com/#bucketbucket.id” “‘

When you create a sink, only new log entries are exported. Cloud Logging does not send previously-ingested log entries to the sink’s destination.

### Listing sinks

You can also list the sinks belonging to your project with Project#sinks.

“‘ruby require “gcloud”

gcloud = Gcloud.new logging = gcloud.logging sinks = logging.sinks sinks.each do |s|

puts "#{s.name}: #{s.filter} -> #{s.destination}"

end “‘

## Creating logs-based metrics

You can use log entries in your project as the basis for [Google Cloud Monitoring](cloud.google.com/monitoring/docs) metrics. These metrics can then be used to produce Cloud Monitoring reports and alerts.

### Creating metrics

A metric is a measured value that can be used to assess a system. Use Project#create_metric to configure a Metric based on a collection of log entries matching an [advanced logs filter](cloud.google.com/logging/docs/view/advanced_filters).

“‘ruby require “gcloud”

gcloud = Gcloud.new logging = gcloud.logging metric = logging.create_metric “errors”, “severity>=ERROR” “‘

### Listing metrics

You can also list the metrics belonging to your project with Project#metrics.

“‘ruby require “gcloud”

gcloud = Gcloud.new logging = gcloud.logging metrics = logging.metrics metrics.each do |m|

puts "#{m.name}: #{m.filter}"

end “‘

## Writing log entries

An Entry is composed of metadata and a payload. The payload is traditionally a message string, but in Cloud Logging it can also be a JSON or protocol buffer object. A single log can have entries with different payload types. In addition to the payload, your argument(s) to Project#write_entries must also contain a log name and a resource.

“‘ruby require “gcloud”

gcloud = Gcloud.new logging = gcloud.logging

entry = logging.entry entry.payload = “Job started.” entry.log_name = “my_app_log” entry.resource.type = “gae_app” entry.resource.labels = “1” entry.resource.labels = “20150925t173233”

logging.write_entries entry “‘

If you write a collection of log entries, you can provide the log name, resource, and/or labels hash to be used for all of the entries, and omit these values from the individual entries.

“‘ruby require “gcloud”

gcloud = Gcloud.new logging = gcloud.logging

entry1 = logging.entry entry1.payload = “Job started.” entry2 = logging.entry entry2.payload = “Job completed.” labels = { job_size: “large”, job_code: “red” }

resource = logging.resource “gae_app”,

"module_id" => "1",
"version_id" => "20150925t173233"

logging.write_entries [entry1, entry2],

log_name: "my_app_log",
resource: resource,
labels: labels

“‘

### Creating a Ruby Logger implementation

If your environment requires a logger instance that is API-compatible with Ruby’s standard library [Logger](ruby-doc.org/stdlib/libdoc/logger/rdoc), you can use Project#logger to create one.

“‘ruby require “gcloud”

gcloud = Gcloud.new logging = gcloud.logging

resource = logging.resource “gae_app”,

module_id: "1",
version_id: "20150925t173233"

logger = logging.logger “my_app_log”, resource, env: :production logger.info “Job started.” “‘

Defined Under Namespace

Classes: Credentials, Entry, Logger, Metric, Project, Resource, ResourceDescriptor, Service, Sink