class Google::Cloud::Logging::Sink

# Sink

Used to export log entries outside Stackdriver Logging. When you create a sink, new log entries are exported. Stackdriver Logging does not send previously-ingested log entries to the sink's destination.

A logs filter controls which log entries are exported.

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](cloud.google.com/logging/docs/export/configure_export_v2#dest-auth).

You can retrieve an existing sink with {Project#sink}.

@see cloud.google.com/logging/docs/export

Overview of logs exports

@see cloud.google.com/logging/docs/reference/v2/rpc/google.logging.v2#configservicev2

ConfigService API which includes sink methods

@example

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

Attributes

grpc[RW]

@private The Google API Client object.

service[RW]

@private The gRPC Service object.

Public Class Methods

from_grpc(grpc, service) click to toggle source

@private New Sink from a Google::Cloud::Logging::V2::LogSink object.

# File lib/google/cloud/logging/sink.rb, line 279
def self.from_grpc grpc, service
  new.tap do |f|
    f.grpc = grpc
    f.service = service
  end
end
new() click to toggle source

@private Create an empty Sink object.

# File lib/google/cloud/logging/sink.rb, line 69
def initialize
  @service = nil
  @grpc = Google::Cloud::Logging::V2::LogSink.new
end

Public Instance Methods

delete() click to toggle source

Permanently deletes the logs-based sink.

@return [Boolean] Returns `true` if the sink was deleted.

@example

require "google/cloud/logging"

logging = Google::Cloud::Logging.new
sink = logging.sink "severe_errors"
sink.delete
# File lib/google/cloud/logging/sink.rb, line 271
def delete
  ensure_service!
  service.delete_sink name
  true
end
destination() click to toggle source

The export destination. See [Properties of Sinks](cloud.google.com/logging/docs/export#sink-terms).

# File lib/google/cloud/logging/sink.rb, line 85
def destination
  @grpc.destination
end
destination=(destination) click to toggle source

Updates the export destination. See [Properties of Sinks](cloud.google.com/logging/docs/export#sink-terms).

# File lib/google/cloud/logging/sink.rb, line 92
def destination= destination
  @grpc.destination = destination
end
end_at() click to toggle source

Deprecated. Time at which this sink will stop exporting log entries. If this value is present, then log entries are exported only if the log entry's timestamp is less than `end_at`. Optional.

@deprecated This field is ignored when creating or updating sinks.

# File lib/google/cloud/logging/sink.rb, line 198
def end_at
  warn "[DEPRECATION] end_at is deprecated."
  nil
end
Also aliased as: end_time
end_at=(_new_end_at) click to toggle source

Deprecated. Sets the time at which this sink will stop exporting log entries. If this value is present, then log entries are exported only if the log entry's timestamp is less than `end_at`. Optional.

@deprecated This field is ignored when creating or updating sinks.

# File lib/google/cloud/logging/sink.rb, line 210
def end_at= _new_end_at
  warn "[DEPRECATION] end_at= is deprecated and will be ignored."
end
Also aliased as: end_time=
end_time()
Alias for: end_at
end_time=(_new_end_at)
Alias for: end_at=
filter() click to toggle source

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

# File lib/google/cloud/logging/sink.rb, line 103
def filter
  @grpc.filter
end
filter=(filter) click to toggle source

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

# File lib/google/cloud/logging/sink.rb, line 114
def filter= filter
  @grpc.filter = filter
end
name() click to toggle source

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 `_-.`.

# File lib/google/cloud/logging/sink.rb, line 78
def name
  @grpc.name
end
refresh!()
Alias for: reload!
reload!() click to toggle source

Reloads the logs-based sink with current data from the Logging service.

# File lib/google/cloud/logging/sink.rb, line 253
def reload!
  ensure_service!
  @grpc = service.get_sink name
end
Also aliased as: refresh!
save(unique_writer_identity: nil) click to toggle source

Updates the logs-based sink.

@param [Boolean] unique_writer_identity 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.

@example

require "google/cloud/logging"

logging = Google::Cloud::Logging.new
sink = logging.sink "severe_errors"
sink.filter = "logName:syslog AND severity>=ERROR"
sink.save
# File lib/google/cloud/logging/sink.rb, line 243
def save unique_writer_identity: nil
  ensure_service!
  @grpc = service.update_sink \
    name, destination, filter,
    unique_writer_identity: unique_writer_identity
end
start_at() click to toggle source

Deprecated. The time at which this sink will begin exporting log entries. If this value is present, then log entries are exported only if `start_at` is less than the log entry's timestamp. Optional.

@deprecated This field is ignored when creating or updating sinks.

# File lib/google/cloud/logging/sink.rb, line 175
def start_at
  warn "[DEPRECATION] start_at is deprecated."
  nil
end
Also aliased as: start_time
start_at=(_new_start_at) click to toggle source

Deprecated. Sets the time at which this sink will begin exporting log entries. If this value is present, then log entries are exported only if `start_at` is less than the log entry's timestamp. Optional.

@deprecated This field is ignored when creating or updating sinks.

# File lib/google/cloud/logging/sink.rb, line 187
def start_at= _new_start_at
  warn "[DEPRECATION] start_at= is deprecated and will be ignored."
end
Also aliased as: start_time=
start_time()
Alias for: start_at
start_time=(_new_start_at)
Alias for: start_at=
unspecified?() click to toggle source

Helper to determine if the sink's version is `VERSION_FORMAT_UNSPECIFIED`.

@deprecated The v2 format is used by default and cannot be changed.

# File lib/google/cloud/logging/sink.rb, line 146
def unspecified?
  warn "[DEPRECATION] unspecified? is deprecated."
  false
end
v1?() click to toggle source

Helper to determine if the sink's version is `V1`.

@deprecated The v2 format is used by default and cannot be changed.

# File lib/google/cloud/logging/sink.rb, line 164
def v1?
  warn "[DEPRECATION] v1? is deprecated."
  false
end
v2?() click to toggle source

Helper to determine if the sink's version is `V2`.

@deprecated The v2 format is used by default and cannot be changed.

# File lib/google/cloud/logging/sink.rb, line 155
def v2?
  warn "[DEPRECATION] v2? is deprecated."
  true
end
version() click to toggle source

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

@deprecated The v2 format is used by default and cannot be changed.

# File lib/google/cloud/logging/sink.rb, line 124
def version
  warn "[DEPRECATION] version is deprecated."
  :V2
end
version=(_version) click to toggle source

Deprecated. Updates 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 Stackdriver Logging. Accepted values are `:VERSION_FORMAT_UNSPECIFIED`, `:V2`, and `:V1`.

@deprecated The v2 format is used by default and cannot be changed.

# File lib/google/cloud/logging/sink.rb, line 137
def version= _version
  warn "[DEPRECATION] version= is deprecated and will be ignored."
end
writer_identity() click to toggle source

An IAM identity (a service account or group) that will write exported log entries to the destination on behalf of Stackdriver Logging. You must grant this identity write-access to the destination. Consult the destination service's documentation to determine the exact role that must be granted.

# File lib/google/cloud/logging/sink.rb, line 221
def writer_identity
  @grpc.writer_identity
end

Protected Instance Methods

ensure_service!() click to toggle source

@private Raise an error unless an active connection to the service is available.

# File lib/google/cloud/logging/sink.rb, line 291
def ensure_service!
  raise "Must have active connection to service" unless service
end
time_to_timestamp(time) click to toggle source

@private Get a Google::Protobuf::Timestamp object from a Time object.

# File lib/google/cloud/logging/sink.rb, line 297
def time_to_timestamp time
  return nil if time.nil?
  # Make sure we have a Time object
  return nil unless time.respond_to? :to_time
  time = time.to_time
  Google::Protobuf::Timestamp.new seconds: time.to_i, nanos: time.nsec
end
timestamp_to_time(timestamp) click to toggle source

@private Get a Time object from a Google::Protobuf::Timestamp object.

# File lib/google/cloud/logging/sink.rb, line 307
def timestamp_to_time timestamp
  return nil if timestamp.nil?
  # Time.at takes microseconds, so convert nano seconds to microseconds
  Time.at timestamp.seconds, Rational(timestamp.nanos, 1000)
end