Class: Google::Cloud::Logging::Sink

Inherits:
Object
  • Object
show all
Defined in:
lib/google/cloud/logging/sink.rb,
lib/google/cloud/logging/sink/list.rb

Overview

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. Sinks can have a start time and an end time; these can be used to place log entries from an exact time range into a particular destination. If both start_at and end_at are present, then start_at must be less than end_at.

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.

You can retrieve an existing sink with Project#sink.

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

See Also:

Defined Under Namespace

Classes: List

Instance Method Summary collapse

Instance Method Details

#delete ⇒ Boolean

Permanently deletes the logs-based sink.

Examples:

require "google/cloud/logging"

logging = Google::Cloud::Logging.new
sink = logging.sink "severe_errors"
sink.delete

Returns:

  • (Boolean) —

    Returns true if the sink was deleted.



253
254
255
256
257
 
# File 'lib/google/cloud/logging/sink.rb', line 253

def delete
  ensure_service!
  service.delete_sink name
  true
end

#destination ⇒ Object

The export destination. See Exporting Logs With Sinks.



91
92
93
 
# File 'lib/google/cloud/logging/sink.rb', line 91

def destination
  @grpc.destination
end

#destination=(destination) ⇒ Object

Updates the export destination. See Exporting Logs With Sinks.



98
99
100
 
# File 'lib/google/cloud/logging/sink.rb', line 98

def destination= destination
  @grpc.destination = destination
end

#end_at ⇒ Object Also known as: end_time

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.



182
183
184
 
# File 'lib/google/cloud/logging/sink.rb', line 182

def end_at
  timestamp_to_time @grpc.end_time
end

#end_at=(new_end_at) ⇒ Object Also known as: end_time=

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.



191
192
193
 
# File 'lib/google/cloud/logging/sink.rb', line 191

def end_at= new_end_at
  @grpc.end_time = time_to_timestamp new_end_at
end

#filter ⇒ Object

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.



109
110
111
 
# File 'lib/google/cloud/logging/sink.rb', line 109

def filter
  @grpc.filter
end

#filter=(filter) ⇒ Object

Updates the 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.



120
121
122
 
# File 'lib/google/cloud/logging/sink.rb', line 120

def filter= filter
  @grpc.filter = filter
end

#name ⇒ Object

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



84
85
86
 
# File 'lib/google/cloud/logging/sink.rb', line 84

def name
  @grpc.name
end

#reload! ⇒ Object Also known as: refresh!

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



235
236
237
238
 
# File 'lib/google/cloud/logging/sink.rb', line 235

def reload!
  ensure_service!
  @grpc = service.get_sink name
end

#save(unique_writer_identity: nil) ⇒ Object

Updates the logs-based sink.

Examples:

require "google/cloud/logging"

logging = Google::Cloud::Logging.new
sink = logging.sink "severe_errors"
sink.filter = "logName:syslog AND severity>=ERROR"
sink.save

Parameters:

  • unique_writer_identity (Boolean) —

    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.



224
225
226
227
228
229
230
 
# File 'lib/google/cloud/logging/sink.rb', line 224

def save unique_writer_identity: nil
  ensure_service!
  @grpc = service.update_sink \
    name, destination, filter, version,
    start_time: start_at, end_time: end_at,
    unique_writer_identity: unique_writer_identity
end

#start_at ⇒ Object Also known as: start_time

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.



164
165
166
 
# File 'lib/google/cloud/logging/sink.rb', line 164

def start_at
  timestamp_to_time @grpc.start_time
end

#start_at=(new_start_at) ⇒ Object Also known as: start_time=

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.



173
174
175
 
# File 'lib/google/cloud/logging/sink.rb', line 173

def start_at= new_start_at
  @grpc.start_time = time_to_timestamp new_start_at
end

#unspecified? ⇒ Boolean

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

Returns:

  • (Boolean) 


144
145
146
 
# File 'lib/google/cloud/logging/sink.rb', line 144

def unspecified?
  !(v1? || v2?)
end

#v1? ⇒ Boolean

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

Returns:

  • (Boolean) 


156
157
158
 
# File 'lib/google/cloud/logging/sink.rb', line 156

def v1?
  version == :V1
end

#v2? ⇒ Boolean

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

Returns:

  • (Boolean) 


150
151
152
 
# File 'lib/google/cloud/logging/sink.rb', line 150

def v2?
  version == :V2
end

#version ⇒ Object

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.



128
129
130
 
# File 'lib/google/cloud/logging/sink.rb', line 128

def version
  @grpc.output_version_format
end

#version=(version) ⇒ Object

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.



137
138
139
 
# File 'lib/google/cloud/logging/sink.rb', line 137

def version= version
  @grpc.output_version_format = self.class.resolve_version(version)
end

#writer_identity ⇒ Object

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.



202
203
204
 
# File 'lib/google/cloud/logging/sink.rb', line 202

def writer_identity
  @grpc.writer_identity
end