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
@private The Google
API Client object.
@private The gRPC Service
object.
Public Class Methods
@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
@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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
@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
@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
@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