Module: Google::Cloud::Logging

Defined in:
lib/google/cloud/logging.rb,
lib/google/cloud/logging/sink.rb,
lib/google/cloud/logging/entry.rb,
lib/google/cloud/logging/logger.rb,
lib/google/cloud/logging/metric.rb,
lib/google/cloud/logging/project.rb,
lib/google/cloud/logging/service.rb,
lib/google/cloud/logging/version.rb,
lib/google/cloud/logging/resource.rb,
lib/google/cloud/logging/sink/list.rb,
lib/google/cloud/logging/entry/list.rb,
lib/google/cloud/logging/credentials.rb,
lib/google/cloud/logging/metric/list.rb,
lib/google/cloud/logging/entry/operation.rb,
lib/google/cloud/logging/entry/http_request.rb,
lib/google/cloud/logging/resource_descriptor.rb,
lib/google/cloud/logging/resource_descriptor/list.rb

Overview

Stackdriver Logging

The Stackdriver 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 Stackdriver Logging API to:

For general information about Stackdriver Logging, read Stackdriver Logging Documentation.

The goal of google-cloud is to provide an API that is comfortable to Rubyists. Authentication is handled by #logging. You can provide the project and credential information to connect to the Stackdriver 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.

Listing log entries

Stackdriver Logging gathers log entries from many services, including Google App Engine and Google Compute Engine. (See the List of Log Types.) In addition, you can write your own log entries to the service.

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

require "google/cloud"

gcloud = Google::Cloud.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. 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 google-cloud. There is no Log type in google-cloud or Log resource in the Stackdriver Logging API.

require "google/cloud"

gcloud = Google::Cloud.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.

require "google/cloud"

gcloud = Google::Cloud.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

Stackdriver 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 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.

require "google/cloud"

gcloud = Google::Cloud.new
logging = gcloud.logging
storage = gcloud.storage

bucket = storage.create_bucket "my-logs-bucket"

# Grant owner permission to Stackdriver Logging service
email = "cloud-logs@google.com"
bucket.acl.add_owner "group-#{email}"

sink = logging.create_sink "my-sink",
                           "storage.googleapis.com/#{bucket.id}"

When you create a sink, only new log entries are exported. Stackdriver 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.

require "google/cloud"

gcloud = Google::Cloud.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 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.

require "google/cloud"

gcloud = Google::Cloud.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.

require "google/cloud"

gcloud = Google::Cloud.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 Stackdriver 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.

require "google/cloud"

gcloud = Google::Cloud.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[:module_id] = "1"
entry.resource.labels[:version_id] = "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.

require "google/cloud"

gcloud = Google::Cloud.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, you can use Project#logger to create one.

require "google/cloud"

gcloud = Google::Cloud.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."

Configuring retries and timeout

You can configure how many times API requests may be automatically retried. When an API request fails, the response will be inspected to see if the request meets criteria indicating that it may succeed on retry, such as 500 and 503 status codes or a specific internal error code such as rateLimitExceeded. If it meets the criteria, the request will be retried after a delay. If another error occurs, the delay will be increased before a subsequent attempt, until the retries limit is reached.

You can also set the request timeout value in seconds.

require "google/cloud"

gcloud = Google::Cloud.new
logging = gcloud.logging retries: 10, timeout: 120

Defined Under Namespace

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

Constant Summary collapse

VERSION = 
"0.20.0"