Class: Google::Cloud::Logging::Project

Inherits:
Object
  • Object
show all
Defined in:
lib/google/cloud/logging/project.rb

Overview

Project

Projects are top-level containers in Google Cloud Platform. They store information about billing and authorized users, and they control access to Stackdriver Logging resources. Each project has a friendly name and a unique ID. Projects can be created only in the Google Developers Console. See Google::Cloud#logging.

See Google::Cloud#logging

Examples:

require "google/cloud/logging"

logging = Google::Cloud::Logging.new
entries = logging.entries

Instance Method Summary collapse

Instance Method Details

#async_writer(max_batch_count: 10_000, max_batch_bytes: 10_000_000, max_queue_size: 100, interval: 5, threads: 10, partial_success: false) ⇒ Google::Cloud::Logging::AsyncWriter

Creates an object that buffers, batches, and transmits log entries efficiently. Writing log entries to this object is asynchronous and will not block.

Batches that cannot be delivered immediately are queued. When the queue is full new batch requests will raise errors that can be consumed using the AsyncWriter#on_error callback. This provides back pressure in case the writer cannot keep up with requests.

This object is thread-safe; it may accept write requests from multiple threads simultaneously, and will serialize them when executing in the background thread.

Examples:

require "google/cloud/logging"

logging = Google::Cloud::Logging.new

async = logging.async_writer

entry1 = logging.entry payload: "Job started."
entry2 = logging.entry payload: "Job completed."

labels = { job_size: "large", job_code: "red" }
resource = logging.resource "gae_app",
                            "module_id" => "1",
                            "version_id" => "20150925t173233"

async.write_entries [entry1, entry2],
                    log_name: "my_app_log",
                    resource: resource,
                    labels: labels

Parameters:

  • max_batch_count (Integer) (defaults to: 10_000) —

    The maximum number of log entries that may be buffered and sent in a batch.

  • max_batch_bytes (Integer) (defaults to: 10_000_000) —

    The maximum byte size of log entries that may be buffered and sent in a batch.

  • max_queue_size (Integer) (defaults to: 100) —

    The maximum number of pending write_entries requests that may be queued.

  • interval (Numeric) (defaults to: 5) —

    The number of seconds to buffer log entries before a batch is written. Default is 5.

  • threads (Integer) (defaults to: 10) —

    The number of threads used to make batched write_entries requests. Default is 10.

  • partial_success (Boolean) (defaults to: false) —

    Whether valid entries should be written even if some other entries fail due to INVALID_ARGUMENT or PERMISSION_DENIED errors when communicating to the Stackdriver Logging API.

Returns:



360
361
362
363
364
365
366
367
368
369
 
# File 'lib/google/cloud/logging/project.rb', line 360

def async_writer max_batch_count: 10_000, max_batch_bytes: 10_000_000,
                 max_queue_size: 100, interval: 5, threads: 10,
                 partial_success: false

  AsyncWriter.new self, max_count: max_batch_count,
                        max_bytes: max_batch_bytes,
                        max_queue: max_queue_size,
                        interval: interval, threads: threads,
                        partial_success: partial_success
end

#create_metric(name, filter, description: nil) ⇒ Google::Cloud::Logging::Metric Also known as: new_metric

Creates a new logs-based metric for Google Cloud Monitoring.

Examples:

require "google/cloud/logging"

logging = Google::Cloud::Logging.new
metric = logging.create_metric "errors", "severity>=ERROR"

Parameters:

  • name (String) —

    The client-assigned metric identifier. Metric identifiers are limited to 1000 characters and can include only the following characters: A-Z, a-z, 0-9, and the special characters _-.,+!*',()%/\. The forward-slash character (/) denotes a hierarchy of name pieces, and it cannot be the first character of the name.

  • filter (String) —

    An advanced logs filter.

  • description (String, nil) (defaults to: nil) —

    A description of this metric, which is used in documentation.

Returns:

See Also:



790
791
792
793
794
 
# File 'lib/google/cloud/logging/project.rb', line 790

def create_metric name, filter, description: nil
  ensure_service!
  grpc = service.create_metric name, filter, description
  Metric.from_grpc grpc, service
end

#create_sink(name, destination, filter: nil, unique_writer_identity: nil) ⇒ Google::Cloud::Logging::Sink Also known as: new_sink

Creates a new project sink. When you create a sink, only new log entries that match the sink's filter are exported. Stackdriver Logging does not send previously-ingested log entries to the sink's destination.

Before creating the sink, ensure that you have granted the sink's unique writer identity permission to write logs to the destination. See Destination permissions.

Examples:

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

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

require "google/cloud/logging"

logging = Google::Cloud::Logging.new

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

Parameters:

  • name (String) —

    The client-assigned sink identifier. Sink identifiers are limited to 1000 characters and can include only the following characters: A-Z, a-z, 0-9, and the special characters _-..

  • destination (String) —

    The resource name of the export destination. See About sinks for examples.

  • filter (String, nil) (defaults to: nil) —

    An advanced logs filter that defines the log entries to be exported. The filter must be consistent with the log entry format designed by the version parameter, regardless of the format of the log entry that was originally written to Stackdriver Logging.

  • unique_writer_identity (Boolean) (defaults to: nil) —

    Whether the sink will have a dedicated service account returned in the sink's writer_identity. Set this field to be true to export logs from one project to a different project. This field is ignored for non-project sinks (e.g. organization sinks) because those sinks are required to have dedicated service accounts. Optional.

Returns:

See Also:



676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
 
# File 'lib/google/cloud/logging/project.rb', line 676

def create_sink name, destination, filter: nil,
                unique_writer_identity: nil,
                start_at: nil, end_at: nil, version: nil
  ensure_service!

  if start_at
    warn "[DEPRECATION] start_at is deprecated and will be ignored."
  end
  if end_at
    warn "[DEPRECATION] end_at is deprecated and will be ignored."
  end
  if version
    warn "[DEPRECATION] version is deprecated and will be ignored."
  end

  grpc = service.create_sink \
    name, destination, filter,
    unique_writer_identity: unique_writer_identity
  Sink.from_grpc grpc, service
end

#delete_log(name) ⇒ Boolean

Deletes a log and all its log entries. The log will reappear if it receives new entries.

Examples:

require "google/cloud/logging"

logging = Google::Cloud::Logging.new
logging.delete_log "my_app_log"

Parameters:

  • name (String) —

    The name of the log, which may be the full path including the project ID (projects/<project-id>/logs/<log-id>), or just the short name (<log-id>), in which case the beginning of the path will be automatically prepended, using the ID of the current project.

Returns:

  • (Boolean) —

    Returns true if the log and all its log entries were deleted.



508
509
510
511
512
 
# File 'lib/google/cloud/logging/project.rb', line 508

def delete_log name
  ensure_service!
  service.delete_log name
  true
end

#entries(resources: nil, filter: nil, order: nil, token: nil, max: nil, projects: nil) ⇒ Array<Google::Cloud::Logging::Entry> Also known as: find_entries

Lists log entries. Use this method to retrieve log entries from Cloud Logging.

Examples:

require "google/cloud/logging"

logging = Google::Cloud::Logging.new
entries = logging.entries
entries.each do |e|
  puts "[#{e.timestamp}] #{e.log_name} #{e.payload.inspect}"
end

You can use a filter to narrow results to a single log.

require "google/cloud/logging"

logging = Google::Cloud::Logging.new
entries = logging.entries filter: "logName:syslog"
entries.each do |e|
  puts "[#{e.timestamp}] #{e.payload.inspect}"
end

You can also order the results by timestamp.

require "google/cloud/logging"

logging = Google::Cloud::Logging.new
entries = logging.entries order: "timestamp desc"
entries.each do |e|
  puts "[#{e.timestamp}] #{e.log_name} #{e.payload.inspect}"
end

Retrieve all log entries: (See Entry::List#all)

require "google/cloud/logging"

logging = Google::Cloud::Logging.new
entries = logging.entries

entries.all do |e|
  puts "[#{e.timestamp}] #{e.log_name} #{e.payload.inspect}"
end

Parameters:

  • resources (String, Array<String>) (defaults to: nil) —

    One or more cloud resources from which to retrieve log entries. If both resources and projects are nil, the ID of the receiving project instance will be used. Examples: "projects/my-project-1A", "projects/1234567890".

  • filter (String) (defaults to: nil) —

    An advanced logs filter. The filter is compared against all log entries in the projects specified by projects. Only entries that match the filter are retrieved. An empty filter matches all log entries.

  • order (String) (defaults to: nil) —

    How the results should be sorted. Presently, the only permitted values are "timestamp" (default) and "timestamp desc".

  • token (String) (defaults to: nil) —

    A previously-returned page token representing part of the larger set of results to view.

  • max (Integer) (defaults to: nil) —

    Maximum number of entries to return.

  • projects (String, Array<String>) (defaults to: nil) —

    One or more project IDs or project numbers from which to retrieve log entries. Each value will be formatted as a project resource name and added to any values passed to resources. If both resources and projects are nil, the ID of the receiving project instance will be used. This is deprecated in favor of resources.

Returns:



146
147
148
149
150
151
152
153
154
155
156
 
# File 'lib/google/cloud/logging/project.rb', line 146

def entries resources: nil, filter: nil, order: nil, token: nil,
            max: nil, projects: nil
  ensure_service!
  list_grpc = service.list_entries resources: resources, filter: filter,
                                   order: order, token: token, max: max,
                                   projects: projects
  Entry::List.from_grpc list_grpc, service,
                        resources: resources, max: max,
                        filter: filter, order: order,
                        projects: projects
end

#entry(log_name: nil, resource: nil, timestamp: nil, severity: nil, insert_id: nil, labels: nil, payload: nil) ⇒ Google::Cloud::Logging::Entry Also known as: new_entry

Creates an new Entry instance that may be populated and written to the Stackdriver Logging service. The Entry#resource attribute is pre-populated with a new Resource instance. Equivalent to calling Google::Cloud::Logging::Entry.new.

Examples:

require "google/cloud/logging"

logging = Google::Cloud::Logging.new

entry = logging.entry severity: :INFO, payload: "Job started."

logging.write_entries entry

Provide a hash to write a JSON payload to the log:

require "google/cloud/logging"

logging = Google::Cloud::Logging.new

payload = { "stats" => { "a" => 8, "b" => 12.5} }
entry = logging.entry severity: :INFO, payload: payload

logging.write_entries entry

Parameters:

  • log_name (String) (defaults to: nil) —

    The resource name of the log to which this log entry belongs. See also Entry#log_name=.

  • resource (Resource) (defaults to: nil) —

    The monitored resource associated with this log entry. See also Entry#resource.

  • timestamp (Time) (defaults to: nil) —

    The time the event described by the log entry occurred. If omitted, Stackdriver Logging will use the time the log entry is written. See also Entry#timestamp.

  • severity (Symbol) (defaults to: nil) —

    The severity level of the log entry. The default value is DEFAULT. See also Entry#severity.

  • insert_id (String) (defaults to: nil) —

    A unique ID for the log entry. If you provide this field, the logging service considers other log entries in the same log with the same ID as duplicates which can be removed. If omitted, Stackdriver Logging will generate a unique ID for this log entry. See also Entry#insert_id.

  • labels (Hash{Symbol,String => String}) (defaults to: nil) —

    A hash of user-defined key:value pairs that provide additional information about the log entry. See also Entry#labels=.

  • payload (String, Hash) (defaults to: nil) —

    The log entry payload, represented as either a string, a hash (JSON), or a hash (protocol buffer). See also Entry#payload.

Returns:



207
208
209
210
211
212
213
214
215
216
217
218
219
220
 
# File 'lib/google/cloud/logging/project.rb', line 207

def entry log_name: nil, resource: nil, timestamp: nil, severity: nil,
          insert_id: nil, labels: nil, payload: nil
  ensure_service!

  e = Entry.new
  e.log_name = service.log_path log_name if log_name
  e.resource = resource if resource
  e.timestamp = timestamp if timestamp
  e.severity = severity if severity
  e.insert_id = insert_id if insert_id
  e.labels = labels if labels
  e.payload = payload if payload
  e
end

#logger(log_name, resource, labels = {}) ⇒ Google::Cloud::Logging::Logger

Creates a logger instance that is API-compatible with Ruby's standard library Logger.

The logger will create a new AsyncWriter object to transmit log entries on a background thread.

Examples:

require "google/cloud/logging"

logging = Google::Cloud::Logging.new

resource = logging.resource "gae_app",
                            module_id: "1",
                            version_id: "20150925t173233"

logger = logging.logger "my_app_log", resource, env: :production
logger.info "Job started."

Provide a hash to write a JSON payload to the log:

require "google/cloud/logging"

logging = Google::Cloud::Logging.new

resource = logging.resource "gae_app",
                            module_id: "1",
                            version_id: "20150925t173233"

logger = logging.logger "my_app_log", resource, env: :production

payload = { "stats" => { "a" => 8, "b" => 12.5} }
logger.info payload

Parameters:

  • log_name (String) —

    A log resource name to be associated with the written log entries.

  • resource (Google::Cloud::Logging::Resource) —

    The monitored resource to be associated with written log entries.

  • labels (Hash) (defaults to: {}) —

    A set of user-defined data to be associated with written log entries. Values can be strings or Procs which are functions of the request environment.

Returns:



443
444
445
 
# File 'lib/google/cloud/logging/project.rb', line 443

def logger log_name, resource, labels = {}
  Logger.new shared_async_writer, log_name, resource, labels
end

#logs(resource: nil, token: nil, max: nil) ⇒ Array<String> Also known as: find_logs, log_names, find_log_names

Lists log names. Use this method to retrieve log names from Cloud Logging.

Examples:

require "google/cloud/logging"

logging = Google::Cloud::Logging.new
logs = logging.logs
logs.each { |l| puts l }

Retrieve all log names: (See Log::List#all)

require "google/cloud/logging"

logging = Google::Cloud::Logging.new
logs = logging.logs

logs.all { |l| puts l }

Parameters:

  • resource (String) (defaults to: nil) —

    The cloud resource from which to retrieve log names. Optional. If nil, the ID of the receiving project instance will be used. Examples: "projects/my-project-1A", "projects/1234567890".

  • token (String) (defaults to: nil) —

    A previously-returned page token representing part of the larger set of results to view.

  • max (Integer) (defaults to: nil) —

    Maximum number of log names to return.

Returns:

  • (Array<String>) —

    A list of log names. For example, projects/my-project/syslog or organizations/123/cloudresourcemanager.googleapis.com%2Factivity. (See Log::List)



479
480
481
482
483
484
 
# File 'lib/google/cloud/logging/project.rb', line 479

def logs resource: nil, token: nil, max: nil
  ensure_service!
  list_grpc = service.list_logs resource: resource, token: token,
                                max: max
  Log::List.from_grpc list_grpc, service, resource: resource, max: max
end

#metric(name) ⇒ Google::Cloud::Logging::Metric? Also known as: get_metric, find_metric

Retrieves metric by name.

Examples:

require "google/cloud/logging"

logging = Google::Cloud::Logging.new
metric = logging.metric "existing_metric"

By default nil will be returned if metric does not exist.

require "google/cloud/logging"

logging = Google::Cloud::Logging.new
metric = logging.metric "non_existing_metric" # nil

Parameters:

  • name (String) —

    Name of a metric.

Returns:



817
818
819
820
821
822
823
 
# File 'lib/google/cloud/logging/project.rb', line 817

def metric name
  ensure_service!
  grpc = service.get_metric name
  Metric.from_grpc grpc, service
rescue Google::Cloud::NotFoundError
  nil
end

#metrics(token: nil, max: nil) ⇒ Array<Google::Cloud::Logging::Metric> Also known as: find_metrics

Retrieves the list of metrics belonging to the project.

Examples:

require "google/cloud/logging"

logging = Google::Cloud::Logging.new
metrics = logging.metrics
metrics.each do |m|
  puts "#{m.name}: #{m.filter}"
end

Retrieve all metrics: (See Metric::List#all)

require "google/cloud/logging"

logging = Google::Cloud::Logging.new
metrics = logging.metrics

metrics.all do |m|
  puts "#{m.name}: #{m.filter}"
end

Parameters:

  • token (String) (defaults to: nil) —

    A previously-returned page token representing part of the larger set of results to view.

  • max (Integer) (defaults to: nil) —

    Maximum number of metrics to return.

Returns:



757
758
759
760
761
 
# File 'lib/google/cloud/logging/project.rb', line 757

def metrics token: nil, max: nil
  ensure_service!
  grpc = service.list_metrics token: token, max: max
  Metric::List.from_grpc grpc, service, max
end

#project_id ⇒ String Also known as: project

The ID of the current project.

Examples:

require "google/cloud/logging"

logging = Google::Cloud::Logging.new(
  project_id: "my-project",
  credentials: "/path/to/keyfile.json"
)

logging.project_id #=> "my-project"

Returns:

  • (String) —

    the Google Cloud project ID



74
75
76
 
# File 'lib/google/cloud/logging/project.rb', line 74

def project_id
  service.project
end

#resource(type, labels = {}) ⇒ Google::Cloud::Logging::Resource Also known as: new_resource

Creates a new monitored resource instance.

Examples:

require "google/cloud/logging"

logging = Google::Cloud::Logging.new

resource = logging.resource "gae_app",
                            "module_id" => "1",
                            "version_id" => "20150925t173233"

Parameters:

  • type (String) —

    The type of resource, as represented by a ResourceDescriptor.

  • labels (Hash) (defaults to: {}) —

    A set of labels that can be used to describe instances of this monitored resource type.

Returns:



574
575
576
577
578
579
 
# File 'lib/google/cloud/logging/project.rb', line 574

def resource type, labels = {}
  Resource.new.tap do |r|
    r.type = type
    r.labels = labels
  end
end

#resource_descriptors(token: nil, max: nil) ⇒ Array<Google::Cloud::Logging::ResourceDescriptor> Also known as: find_resource_descriptors

Retrieves the list of monitored resource descriptors that are used by Stackdriver Logging.

Examples:

require "google/cloud/logging"

logging = Google::Cloud::Logging.new
resource_descriptors = logging.resource_descriptors
resource_descriptors.each do |rd|
  label_keys = rd.labels.map(&:key).join(", ")
  puts "#{rd.type} (#{label_keys})"
end

Pagination:

require "google/cloud/logging"

logging = Google::Cloud::Logging.new
resource_descriptors = logging.resource_descriptors

resource_descriptors.all do |rd|
  puts rd.type
end

Parameters:

  • token (String) (defaults to: nil) —

    A previously-returned page token representing part of the larger set of results to view.

  • max (Integer) (defaults to: nil) —

    Maximum number of resource descriptors to return.

Returns:

See Also:



548
549
550
551
552
 
# File 'lib/google/cloud/logging/project.rb', line 548

def resource_descriptors token: nil, max: nil
  ensure_service!
  list_grpc = service.list_resource_descriptors token: token, max: max
  ResourceDescriptor::List.from_grpc list_grpc, service, max
end

#shared_async_writer ⇒ Object

Returns a shared AsyncWriter for this Project. If this method is called multiple times, it will return the same object.

Examples:

require "google/cloud/logging"

logging = Google::Cloud::Logging.new

async = logging.shared_async_writer

entry1 = logging.entry payload: "Job started."
entry2 = logging.entry payload: "Job completed."

labels = { job_size: "large", job_code: "red" }
resource = logging.resource "gae_app",
                            "module_id" => "1",
                            "version_id" => "20150925t173233"

async.write_entries [entry1, entry2],
                    log_name: "my_app_log",
                    resource: resource,
                    labels: labels


395
396
397
 
# File 'lib/google/cloud/logging/project.rb', line 395

def shared_async_writer
  @shared_async_writer ||= async_writer
end

#sink(sink_name) ⇒ Google::Cloud::Logging::Sink? Also known as: get_sink, find_sink

Retrieves a sink by name.

Examples:

require "google/cloud/logging"

logging = Google::Cloud::Logging.new
sink = logging.sink "existing-sink"

By default nil will be returned if the sink does not exist.

require "google/cloud/logging"

logging = Google::Cloud::Logging.new
sink = logging.sink "non-existing-sink" # nil

Parameters:

  • sink_name (String) —

    Name of a sink.

Returns:



718
719
720
721
722
723
724
 
# File 'lib/google/cloud/logging/project.rb', line 718

def sink sink_name
  ensure_service!
  grpc = service.get_sink sink_name
  Sink.from_grpc grpc, service
rescue Google::Cloud::NotFoundError
  nil
end

#sinks(token: nil, max: nil) ⇒ Array<Google::Cloud::Logging::Sink> Also known as: find_sinks

Retrieves the list of sinks belonging to the project.

Examples:

require "google/cloud/logging"

logging = Google::Cloud::Logging.new
sinks = logging.sinks
sinks.each do |s|
  puts "#{s.name}: #{s.filter} -> #{s.destination}"
end

Retrieve all sinks: (See Sink::List#all)

require "google/cloud/logging"

logging = Google::Cloud::Logging.new
sinks = logging.sinks

sinks.all do |s|
  puts "#{s.name}: #{s.filter} -> #{s.destination}"
end

Parameters:

  • token (String) (defaults to: nil) —

    A previously-returned page token representing part of the larger set of results to view.

  • max (Integer) (defaults to: nil) —

    Maximum number of sinks to return.

Returns:



611
612
613
614
615
 
# File 'lib/google/cloud/logging/project.rb', line 611

def sinks token: nil, max: nil
  ensure_service!
  list_grpc = service.list_sinks token: token, max: max
  Sink::List.from_grpc list_grpc, service, max
end

#write_entries(entries, log_name: nil, resource: nil, labels: nil, partial_success: nil) ⇒ Boolean

Writes log entries to the Stackdriver Logging service.

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.

Examples:

require "google/cloud/logging"

logging = Google::Cloud::Logging.new

entry = logging.entry payload: "Job started.",
                      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

Provide a hash to write a JSON payload to the log:

require "google/cloud/logging"

logging = Google::Cloud::Logging.new

payload = { "stats" => { "a" => 8, "b" => 12.5} }

entry = logging.entry payload: payload,
                      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

Optionally pass log name, resource, and labels for entries.

require "google/cloud/logging"

logging = Google::Cloud::Logging.new

entry1 = logging.entry payload: "Job started."
entry2 = logging.entry 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,
                      partial_success: true

Parameters:

  • entries (Google::Cloud::Logging::Entry, Array<Google::Cloud::Logging::Entry>) —

    One or more entry objects to write. The log entries must have values for all required fields.

  • log_name (String) (defaults to: nil) —

    A default log ID for those log entries in entries that do not specify their own log_name. See also Entry#log_name=.

  • resource (Resource) (defaults to: nil) —

    A default monitored resource for those log entries in entries that do not specify their own resource. See also Entry#resource.

  • labels (Hash{Symbol,String => String}) (defaults to: nil) —

    User-defined key:value items that are added to the labels field of each log entry in entries, except when a log entry specifies its own key:value item with the same key. See also Entry#labels=.

  • partial_success (Boolean) (defaults to: nil) —

    Whether valid entries should be written even if some other entries fail due to INVALID_ARGUMENT or PERMISSION_DENIED errors when communicating to the Stackdriver Logging API.

Returns:

  • (Boolean) —

    Returns true if the entries were written.



299
300
301
302
303
304
305
306
 
# File 'lib/google/cloud/logging/project.rb', line 299

def write_entries entries, log_name: nil, resource: nil, labels: nil,
                  partial_success: nil
  ensure_service!
  service.write_entries Array(entries).map(&:to_grpc),
                        log_name: log_name, resource: resource,
                        labels: labels, partial_success: partial_success
  true
end