Class: Gcloud::Logging::Project

Inherits:
Object
  • Object
show all
Defined in:
lib/gcloud/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 Google Cloud Logging resources. Each project has a friendly name and a unique ID. Projects can be created only in the [Google Developers Console](console.developers.google.com). See Gcloud#logging.

See Gcloud#logging

Examples:

require "gcloud"

gcloud = Gcloud.new
logging = gcloud.logging
entries = logging.entries

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(project, credentials) ⇒ Project

Returns a new instance of Project.



52
53
54
55
56
 
# File 'lib/gcloud/logging/project.rb', line 52

def initialize project, credentials
  project = project.to_s # Always cast to a string
  fail ArgumentError, "project is missing" if project.empty?
  @service = Service.new project, credentials
end

Instance Attribute Details

#service ⇒ Object 



48
49
50
 
# File 'lib/gcloud/logging/project.rb', line 48

def service
  @service
end

Class Method Details

.default_project ⇒ Object 



77
78
79
80
81
82
 
# File 'lib/gcloud/logging/project.rb', line 77

def self.default_project
  ENV["LOGGING_PROJECT"] ||
    ENV["GCLOUD_PROJECT"] ||
    ENV["GOOGLE_CLOUD_PROJECT"] ||
    Gcloud::GCE.project_id
end

Instance Method Details

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

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

Examples:

require "gcloud"

gcloud = Gcloud.new
logging = gcloud.logging
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](cloud.google.com/logging/docs/view/advanced_filters).

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

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

Returns:

See Also:



598
599
600
601
602
603
604
 
# File 'lib/gcloud/logging/project.rb', line 598

def create_metric name, filter, description: nil
  ensure_service!
  grpc = service.create_metric name, filter, description
  Metric.from_grpc grpc, service
rescue GRPC::BadStatus => e
  raise Gcloud::Error.from_error(e)
end

#create_sink(name, destination, filter: nil, version: :unspecified) ⇒ Gcloud::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. Cloud Logging does not send previously-ingested log entries to the sink’s destination.

Before creating the sink, ensure that you have granted ‘[email protected]` 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).

Examples:

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 = "[email protected]"
bucket.acl.add_owner "group-#{email}"

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](cloud.google.com/logging/docs/api/tasks/exporting-logs#about_sinks) for examples.

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

    An [advanced logs filter](cloud.google.com/logging/docs/view/advanced_filters) 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 Cloud Logging.

  • version (Symbol) (defaults to: :unspecified) —

    The log entry version used when exporting log entries from this sink. This version does not have to correspond to the version of the log entry when it was written to Cloud Logging. Accepted values are ‘:unspecified`, `:v2`, and `:v1`. Version 2 is currently the preferred format. An unspecified version format currently defaults to V2 in the service. The default value is `:unspecified`.

Returns:

See Also:



485
486
487
488
489
490
491
492
 
# File 'lib/gcloud/logging/project.rb', line 485

def create_sink name, destination, filter: nil, version: :unspecified
  version = Sink.resolve_version version
  ensure_service!
  grpc = service.create_sink name, destination, filter, version
  Sink.from_grpc grpc, service
rescue GRPC::BadStatus => e
  raise Gcloud::Error.from_error(e)
end

#delete_log(name) ⇒ Boolean

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

Examples:

require "gcloud"

gcloud = Gcloud.new
logging = gcloud.logging
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.



305
306
307
308
309
310
311
 
# File 'lib/gcloud/logging/project.rb', line 305

def delete_log name
  ensure_service!
  service.delete_log name
  return true
rescue GRPC::BadStatus => e
  raise Gcloud::Error.from_error(e)
end

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

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

Examples:

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 use a filter to narrow results to a single log.

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 results by timestamp.

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

With pagination: (See Entry::List)

require "gcloud"

gcloud = Gcloud.new
logging = gcloud.logging
entries = logging.entries
loop do
  entries.each do |e|
    puts "[#{e.timestamp}] #{e.log_name} #{e.payload.inspect}"
  end
  break unless entries.next?
  entries = entries.next
end

Parameters:

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

    One or more project IDs or project numbers from which to retrieve log entries. If ‘nil`, the ID of the receiving project instance will be used.

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

    An [advanced logs filter](cloud.google.com/logging/docs/view/advanced_filters). 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.

Returns:



149
150
151
152
153
154
155
156
157
 
# File 'lib/gcloud/logging/project.rb', line 149

def entries projects: nil, filter: nil, order: nil, token: nil, max: nil
  ensure_service!
  list_grpc = service.list_entries projects: projects, filter: filter,
                                   order: order, token: token, max: max
  Entry::List.from_grpc list_grpc, service, projects: projects, max: max,
                                            filter: filter, order: order
rescue GRPC::BadStatus => e
  raise Gcloud::Error.from_error(e)
end

#entry ⇒ Gcloud::Logging::Entry Also known as: new_entry

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

Examples:

require "gcloud"

gcloud = Gcloud.new
logging = gcloud.logging

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

logging.write_entries entry

Returns:



180
181
182
 
# File 'lib/gcloud/logging/project.rb', line 180

def entry
  Entry.new
end

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

Creates a logger instance that is API-compatible with Ruby’s standard library [Logger](ruby-doc.org/stdlib/libdoc/logger/rdoc).

Examples:

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

Parameters:

  • log_name (String) —

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

  • resource (Gcloud::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.

Returns:

  • (Gcloud::Logging::Logger) —

    a Logger object that can be used in place of a ruby standard library logger object.



281
282
283
 
# File 'lib/gcloud/logging/project.rb', line 281

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

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

Retrieves metric by name.

Examples:

require "gcloud"

gcloud = Gcloud.new
logging = gcloud.logging
metric = logging.metric "existing_metric"

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

require "gcloud"

gcloud = Gcloud.new
logging = gcloud.logging
metric = logging.metric "non_existing_metric" #=> nil

Parameters:

  • name (String) —

    Name of a metric.

Returns:



629
630
631
632
633
634
635
636
 
# File 'lib/gcloud/logging/project.rb', line 629

def metric name
  ensure_service!
  grpc = service.get_metric name
  Metric.from_grpc grpc, service
rescue GRPC::BadStatus => e
  return nil if e.code == 5
  raise Gcloud::Error.from_error(e)
end

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

Retrieves the list of metrics belonging to the project.

Examples:

require "gcloud"

gcloud = Gcloud.new
logging = gcloud.logging
metrics = logging.metrics
metrics.each do |m|
  puts "#{m.name}: #{m.filter}"
end

With pagination: (See Metric::List)

require "gcloud"

gcloud = Gcloud.new
logging = gcloud.logging
metrics = logging.metrics
loop do
  metrics.each do |m|
    puts "#{m.name}: #{m.filter}"
  end
  break unless metrics.next?
  metrics = metrics.next
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:



562
563
564
565
566
567
568
 
# File 'lib/gcloud/logging/project.rb', line 562

def metrics token: nil, max: nil
  ensure_service!
  grpc = service.list_metrics token: token, max: max
  Metric::List.from_grpc grpc, service
rescue GRPC::BadStatus => e
  raise Gcloud::Error.from_error(e)
end

#project ⇒ String

The ID of the current project.

Examples:

require "gcloud"

gcloud = Gcloud.new "my-project", "/path/to/keyfile.json"
logging = gcloud.logging

logging.project #=> "my-project"

Returns:

  • (String) —

    the Google Cloud project ID



71
72
73
 
# File 'lib/gcloud/logging/project.rb', line 71

def project
  service.project
end

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

Creates a new monitored resource instance.

Examples:

require "gcloud"

gcloud = Gcloud.new
logging = gcloud.logging

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

Returns:



376
377
378
379
380
381
 
# File 'lib/gcloud/logging/project.rb', line 376

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

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

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

Examples:

require "gcloud"

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

Pagination: (See ResourceDescriptor::List)

require "gcloud"

gcloud = Gcloud.new
logging = gcloud.logging
resource_descriptors = logging.resource_descriptors
loop do
  resource_descriptors.each do |rd|
    puts rd.type
  end
  break unless resource_descriptors.next?
  resource_descriptors = resource_descriptors.next
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:



352
353
354
355
356
357
358
 
# File 'lib/gcloud/logging/project.rb', line 352

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
rescue GRPC::BadStatus => e
  raise Gcloud::Error.from_error(e)
end

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

Retrieves a sink by name.

Examples:

require "gcloud"

gcloud = Gcloud.new
logging = gcloud.logging
sink = logging.sink "existing-sink"

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

require "gcloud"

gcloud = Gcloud.new
logging = gcloud.logging
sink = logging.sink "non-existing-sink" #=> nil

Parameters:

  • sink_name (String) —

    Name of a sink.

Returns:



517
518
519
520
521
522
523
524
 
# File 'lib/gcloud/logging/project.rb', line 517

def sink sink_name
  ensure_service!
  grpc = service.get_sink sink_name
  Sink.from_grpc grpc, service
rescue GRPC::BadStatus => e
  return nil if e.code == 5
  raise Gcloud::Error.from_error(e)
end

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

Retrieves the list of sinks belonging to the project.

Examples:

require "gcloud"

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

With pagination: (See Sink::List)

require "gcloud"

gcloud = Gcloud.new
logging = gcloud.logging
sinks = logging.sinks
loop do
  sinks.each do |s|
    puts "#{s.name}: #{s.filter} -> #{s.destination}"
  end
  break unless sinks.next?
  sinks = sinks.next
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:



418
419
420
421
422
423
424
 
# File 'lib/gcloud/logging/project.rb', line 418

def sinks token: nil, max: nil
  ensure_service!
  list_grpc = service.list_sinks token: token, max: max
  Sink::List.from_grpc list_grpc, service
rescue GRPC::BadStatus => e
  raise Gcloud::Error.from_error(e)
end

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

Writes log entries to the Cloud 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 "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[:module_id] = "1"
entry.resource.labels[:version_id] = "20150925t173233"

logging.write_entries entry

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

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

Parameters:

  • entries (Gcloud::Logging::Entry, Array<Gcloud::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=.

Returns:

  • (Boolean) —

    Returns ‘true` if the entries were written.



244
245
246
247
248
249
250
251
252
 
# File 'lib/gcloud/logging/project.rb', line 244

def write_entries entries, log_name: nil, resource: nil, labels: nil
  ensure_service!
  service.write_entries Array(entries).map(&:to_grpc),
                        log_name: log_name, resource: resource,
                        labels: labels
  return true
rescue GRPC::BadStatus => e
  raise Gcloud::Error.from_error(e)
end