google-cloud-logging 2.0.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +7 -0
- data/.yardopts +18 -0
- data/AUTHENTICATION.md +178 -0
- data/CHANGELOG.md +407 -0
- data/CODE_OF_CONDUCT.md +40 -0
- data/CONTRIBUTING.md +188 -0
- data/INSTRUMENTATION.md +71 -0
- data/LICENSE +201 -0
- data/LOGGING.md +32 -0
- data/OVERVIEW.md +321 -0
- data/TROUBLESHOOTING.md +31 -0
- data/lib/google-cloud-logging.rb +161 -0
- data/lib/google/cloud/logging.rb +188 -0
- data/lib/google/cloud/logging/async_writer.rb +513 -0
- data/lib/google/cloud/logging/convert.rb +70 -0
- data/lib/google/cloud/logging/credentials.rb +44 -0
- data/lib/google/cloud/logging/entry.rb +528 -0
- data/lib/google/cloud/logging/entry/http_request.rb +167 -0
- data/lib/google/cloud/logging/entry/list.rb +178 -0
- data/lib/google/cloud/logging/entry/operation.rb +91 -0
- data/lib/google/cloud/logging/entry/source_location.rb +85 -0
- data/lib/google/cloud/logging/errors.rb +101 -0
- data/lib/google/cloud/logging/log/list.rb +156 -0
- data/lib/google/cloud/logging/logger.rb +633 -0
- data/lib/google/cloud/logging/metric.rb +168 -0
- data/lib/google/cloud/logging/metric/list.rb +170 -0
- data/lib/google/cloud/logging/middleware.rb +307 -0
- data/lib/google/cloud/logging/project.rb +838 -0
- data/lib/google/cloud/logging/rails.rb +232 -0
- data/lib/google/cloud/logging/resource.rb +85 -0
- data/lib/google/cloud/logging/resource_descriptor.rb +137 -0
- data/lib/google/cloud/logging/resource_descriptor/list.rb +175 -0
- data/lib/google/cloud/logging/service.rb +239 -0
- data/lib/google/cloud/logging/sink.rb +315 -0
- data/lib/google/cloud/logging/sink/list.rb +168 -0
- data/lib/google/cloud/logging/version.rb +22 -0
- metadata +304 -0
@@ -0,0 +1,838 @@
|
|
1
|
+
# Copyright 2016 Google LLC
|
2
|
+
#
|
3
|
+
# Licensed under the Apache License, Version 2.0 (the "License");
|
4
|
+
# you may not use this file except in compliance with the License.
|
5
|
+
# You may obtain a copy of the License at
|
6
|
+
#
|
7
|
+
# https://www.apache.org/licenses/LICENSE-2.0
|
8
|
+
#
|
9
|
+
# Unless required by applicable law or agreed to in writing, software
|
10
|
+
# distributed under the License is distributed on an "AS IS" BASIS,
|
11
|
+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
12
|
+
# See the License for the specific language governing permissions and
|
13
|
+
# limitations under the License.
|
14
|
+
|
15
|
+
|
16
|
+
require "google/cloud/errors"
|
17
|
+
require "google/cloud/logging/service"
|
18
|
+
require "google/cloud/logging/credentials"
|
19
|
+
require "google/cloud/logging/log/list"
|
20
|
+
require "google/cloud/logging/entry"
|
21
|
+
require "google/cloud/logging/resource_descriptor"
|
22
|
+
require "google/cloud/logging/sink"
|
23
|
+
require "google/cloud/logging/metric"
|
24
|
+
require "google/cloud/logging/async_writer"
|
25
|
+
require "google/cloud/logging/logger"
|
26
|
+
require "google/cloud/logging/middleware"
|
27
|
+
|
28
|
+
module Google
|
29
|
+
module Cloud
|
30
|
+
module Logging
|
31
|
+
##
|
32
|
+
# # Project
|
33
|
+
#
|
34
|
+
# Projects are top-level containers in Google Cloud Platform. They store
|
35
|
+
# information about billing and authorized users, and they control access
|
36
|
+
# to Stackdriver Logging resources. Each project has a friendly name and a
|
37
|
+
# unique ID. Projects can be created only in the [Google Developers
|
38
|
+
# Console](https://console.developers.google.com). See
|
39
|
+
# {Google::Cloud#logging}.
|
40
|
+
#
|
41
|
+
# @example
|
42
|
+
# require "google/cloud/logging"
|
43
|
+
#
|
44
|
+
# logging = Google::Cloud::Logging.new
|
45
|
+
# entries = logging.entries
|
46
|
+
#
|
47
|
+
# See Google::Cloud#logging
|
48
|
+
class Project
|
49
|
+
##
|
50
|
+
# @private The gRPC Service object.
|
51
|
+
attr_accessor :service
|
52
|
+
|
53
|
+
##
|
54
|
+
# @private Creates a new Connection instance.
|
55
|
+
def initialize service
|
56
|
+
@service = service
|
57
|
+
end
|
58
|
+
|
59
|
+
##
|
60
|
+
# The ID of the current project.
|
61
|
+
#
|
62
|
+
# @return [String] the Google Cloud project ID
|
63
|
+
#
|
64
|
+
# @example
|
65
|
+
# require "google/cloud/logging"
|
66
|
+
#
|
67
|
+
# logging = Google::Cloud::Logging.new(
|
68
|
+
# project_id: "my-project",
|
69
|
+
# credentials: "/path/to/keyfile.json"
|
70
|
+
# )
|
71
|
+
#
|
72
|
+
# logging.project_id #=> "my-project"
|
73
|
+
#
|
74
|
+
def project_id
|
75
|
+
service.project
|
76
|
+
end
|
77
|
+
alias project project_id
|
78
|
+
|
79
|
+
##
|
80
|
+
# Lists log entries. Use this method to retrieve log entries from Cloud
|
81
|
+
# Logging.
|
82
|
+
#
|
83
|
+
# @param [String, Array<String>] resources One or more cloud resources
|
84
|
+
# from which to retrieve log entries. If both `resources` and
|
85
|
+
# `projects` are `nil`, the ID of the receiving project instance will
|
86
|
+
# be used. Examples: `"projects/my-project-1A"`,
|
87
|
+
# `"projects/1234567890"`.
|
88
|
+
# @param [String] filter An [advanced logs
|
89
|
+
# filter](https://cloud.google.com/logging/docs/view/advanced_filters).
|
90
|
+
# The filter is compared against all log entries in the projects
|
91
|
+
# specified by `projects`. Only entries that match the filter are
|
92
|
+
# retrieved. An empty filter matches all log entries.
|
93
|
+
# @param [String] order How the results should be sorted. Presently, the
|
94
|
+
# only permitted values are "timestamp" (default) and "timestamp
|
95
|
+
# desc".
|
96
|
+
# @param [String] token A previously-returned page token representing
|
97
|
+
# part of the larger set of results to view.
|
98
|
+
# @param [Integer] max Maximum number of entries to return.
|
99
|
+
# @param [String, Array<String>] projects One or more project IDs or
|
100
|
+
# project numbers from which to retrieve log entries. Each value will
|
101
|
+
# be formatted as a project resource name and added to any values
|
102
|
+
# passed to `resources`. If both `resources` and `projects` are `nil`,
|
103
|
+
# the ID of the receiving project instance will be used. This is
|
104
|
+
# deprecated in favor of `resources`.
|
105
|
+
#
|
106
|
+
# @return [Array<Google::Cloud::Logging::Entry>] (See
|
107
|
+
# {Google::Cloud::Logging::Entry::List})
|
108
|
+
#
|
109
|
+
# @example
|
110
|
+
# require "google/cloud/logging"
|
111
|
+
#
|
112
|
+
# logging = Google::Cloud::Logging.new
|
113
|
+
# entries = logging.entries
|
114
|
+
# entries.each do |e|
|
115
|
+
# puts "[#{e.timestamp}] #{e.log_name} #{e.payload.inspect}"
|
116
|
+
# end
|
117
|
+
#
|
118
|
+
# @example You can use a filter to narrow results to a single log.
|
119
|
+
# require "google/cloud/logging"
|
120
|
+
#
|
121
|
+
# logging = Google::Cloud::Logging.new
|
122
|
+
# entries = logging.entries filter: "logName:syslog"
|
123
|
+
# entries.each do |e|
|
124
|
+
# puts "[#{e.timestamp}] #{e.payload.inspect}"
|
125
|
+
# end
|
126
|
+
#
|
127
|
+
# @example You can also order the results by timestamp.
|
128
|
+
# require "google/cloud/logging"
|
129
|
+
#
|
130
|
+
# logging = Google::Cloud::Logging.new
|
131
|
+
# entries = logging.entries order: "timestamp desc"
|
132
|
+
# entries.each do |e|
|
133
|
+
# puts "[#{e.timestamp}] #{e.log_name} #{e.payload.inspect}"
|
134
|
+
# end
|
135
|
+
#
|
136
|
+
# @example Retrieve all log entries: (See {Entry::List#all})
|
137
|
+
# require "google/cloud/logging"
|
138
|
+
#
|
139
|
+
# logging = Google::Cloud::Logging.new
|
140
|
+
# entries = logging.entries
|
141
|
+
#
|
142
|
+
# entries.all do |e|
|
143
|
+
# puts "[#{e.timestamp}] #{e.log_name} #{e.payload.inspect}"
|
144
|
+
# end
|
145
|
+
#
|
146
|
+
def entries resources: nil, filter: nil, order: nil, token: nil,
|
147
|
+
max: nil, projects: nil
|
148
|
+
ensure_service!
|
149
|
+
list_grpc = service.list_entries resources: resources, filter: filter,
|
150
|
+
order: order, token: token, max: max,
|
151
|
+
projects: projects
|
152
|
+
Entry::List.from_grpc list_grpc, service,
|
153
|
+
resources: resources, max: max,
|
154
|
+
filter: filter, order: order,
|
155
|
+
projects: projects
|
156
|
+
end
|
157
|
+
alias find_entries entries
|
158
|
+
|
159
|
+
##
|
160
|
+
# Creates an new Entry instance that may be populated and written to the
|
161
|
+
# Stackdriver Logging service. The {Entry#resource} attribute is
|
162
|
+
# pre-populated with a new {Google::Cloud::Logging::Resource} instance.
|
163
|
+
# Equivalent to calling `Google::Cloud::Logging::Entry.new`.
|
164
|
+
#
|
165
|
+
# @param [String] log_name The resource name of the log to which this
|
166
|
+
# log entry belongs. See also {Entry#log_name=}.
|
167
|
+
# @param [Resource] resource The monitored resource associated with this
|
168
|
+
# log entry. See also {Entry#resource}.
|
169
|
+
# @param [Time] timestamp The time the event described by the log entry
|
170
|
+
# occurred. If omitted, Stackdriver Logging will use the time the log
|
171
|
+
# entry is written. See also {Entry#timestamp}.
|
172
|
+
# @param [Symbol] severity The severity level of the log entry. The
|
173
|
+
# default value is `DEFAULT`. See also {Entry#severity}.
|
174
|
+
# @param [String] insert_id A unique ID for the log entry. If you
|
175
|
+
# provide this field, the logging service considers other log entries
|
176
|
+
# in the same log with the same ID as duplicates which can be removed.
|
177
|
+
# If omitted, Stackdriver Logging will generate a unique ID for this
|
178
|
+
# log entry. See also {Entry#insert_id}.
|
179
|
+
# @param [Hash{Symbol,String => String}] labels A hash of user-defined
|
180
|
+
# `key:value` pairs that provide additional information about the log
|
181
|
+
# entry. See also {Entry#labels=}.
|
182
|
+
# @param [String, Hash] payload The log entry payload, represented as
|
183
|
+
# either a string, a hash (JSON), or a hash (protocol buffer). See
|
184
|
+
# also {Entry#payload}.
|
185
|
+
#
|
186
|
+
# @return [Google::Cloud::Logging::Entry] a new Entry instance
|
187
|
+
#
|
188
|
+
# @example
|
189
|
+
# require "google/cloud/logging"
|
190
|
+
#
|
191
|
+
# logging = Google::Cloud::Logging.new
|
192
|
+
#
|
193
|
+
# entry = logging.entry severity: :INFO, payload: "Job started."
|
194
|
+
#
|
195
|
+
# logging.write_entries entry
|
196
|
+
#
|
197
|
+
# @example Provide a hash to write a JSON payload to the log:
|
198
|
+
# require "google/cloud/logging"
|
199
|
+
#
|
200
|
+
# logging = Google::Cloud::Logging.new
|
201
|
+
#
|
202
|
+
# payload = { "stats" => { "a" => 8, "b" => 12.5} }
|
203
|
+
# entry = logging.entry severity: :INFO, payload: payload
|
204
|
+
#
|
205
|
+
# logging.write_entries entry
|
206
|
+
#
|
207
|
+
def entry log_name: nil, resource: nil, timestamp: nil, severity: nil,
|
208
|
+
insert_id: nil, labels: nil, payload: nil
|
209
|
+
ensure_service!
|
210
|
+
|
211
|
+
e = Entry.new
|
212
|
+
e.log_name = service.log_path log_name if log_name
|
213
|
+
e.resource = resource if resource
|
214
|
+
e.timestamp = timestamp if timestamp
|
215
|
+
e.severity = severity if severity
|
216
|
+
e.insert_id = insert_id if insert_id
|
217
|
+
e.labels = labels if labels
|
218
|
+
e.payload = payload if payload
|
219
|
+
e
|
220
|
+
end
|
221
|
+
alias new_entry entry
|
222
|
+
|
223
|
+
##
|
224
|
+
# Writes log entries to the Stackdriver Logging service.
|
225
|
+
#
|
226
|
+
# If you write a collection of log entries, you can provide the log
|
227
|
+
# name, resource, and/or labels hash to be used for all of the entries,
|
228
|
+
# and omit these values from the individual entries.
|
229
|
+
#
|
230
|
+
# @param [Google::Cloud::Logging::Entry,
|
231
|
+
# Array<Google::Cloud::Logging::Entry>] entries One or more entry
|
232
|
+
# objects to write. The log entries must have values for all required
|
233
|
+
# fields.
|
234
|
+
# @param [String] log_name A default log ID for those log entries in
|
235
|
+
# `entries` that do not specify their own `log_name`. See also
|
236
|
+
# {Entry#log_name=}.
|
237
|
+
# @param [Resource] resource A default monitored resource for those log
|
238
|
+
# entries in entries that do not specify their own resource. See also
|
239
|
+
# {Entry#resource}.
|
240
|
+
# @param [Hash{Symbol,String => String}] labels User-defined `key:value`
|
241
|
+
# items that are added to the `labels` field of each log entry in
|
242
|
+
# `entries`, except when a log entry specifies its own `key:value`
|
243
|
+
# item with the same key. See also {Entry#labels=}.
|
244
|
+
# @param [Boolean] partial_success Whether valid entries should be
|
245
|
+
# written even if some other entries fail due to `INVALID_ARGUMENT` or
|
246
|
+
# `PERMISSION_DENIED` errors when communicating to the Stackdriver
|
247
|
+
# Logging API.
|
248
|
+
#
|
249
|
+
# @return [Boolean] Returns `true` if the entries were written.
|
250
|
+
#
|
251
|
+
# @example
|
252
|
+
# require "google/cloud/logging"
|
253
|
+
#
|
254
|
+
# logging = Google::Cloud::Logging.new
|
255
|
+
#
|
256
|
+
# entry = logging.entry payload: "Job started.",
|
257
|
+
# log_name: "my_app_log"
|
258
|
+
# entry.resource.type = "gae_app"
|
259
|
+
# entry.resource.labels[:module_id] = "1"
|
260
|
+
# entry.resource.labels[:version_id] = "20150925t173233"
|
261
|
+
#
|
262
|
+
# logging.write_entries entry
|
263
|
+
#
|
264
|
+
# @example Provide a hash to write a JSON payload to the log:
|
265
|
+
# require "google/cloud/logging"
|
266
|
+
#
|
267
|
+
# logging = Google::Cloud::Logging.new
|
268
|
+
#
|
269
|
+
# payload = { "stats" => { "a" => 8, "b" => 12.5} }
|
270
|
+
#
|
271
|
+
# entry = logging.entry payload: payload,
|
272
|
+
# log_name: "my_app_log"
|
273
|
+
# entry.resource.type = "gae_app"
|
274
|
+
# entry.resource.labels[:module_id] = "1"
|
275
|
+
# entry.resource.labels[:version_id] = "20150925t173233"
|
276
|
+
#
|
277
|
+
# logging.write_entries entry
|
278
|
+
#
|
279
|
+
#
|
280
|
+
# @example Optionally pass log name, resource, and labels for entries.
|
281
|
+
# require "google/cloud/logging"
|
282
|
+
#
|
283
|
+
# logging = Google::Cloud::Logging.new
|
284
|
+
#
|
285
|
+
# entry1 = logging.entry payload: "Job started."
|
286
|
+
# entry2 = logging.entry payload: "Job completed."
|
287
|
+
#
|
288
|
+
# labels = { job_size: "large", job_code: "red" }
|
289
|
+
# resource = logging.resource "gae_app",
|
290
|
+
# "module_id" => "1",
|
291
|
+
# "version_id" => "20150925t173233"
|
292
|
+
#
|
293
|
+
# logging.write_entries [entry1, entry2],
|
294
|
+
# log_name: "my_app_log",
|
295
|
+
# resource: resource,
|
296
|
+
# labels: labels,
|
297
|
+
# partial_success: true
|
298
|
+
#
|
299
|
+
def write_entries entries, log_name: nil, resource: nil, labels: nil,
|
300
|
+
partial_success: nil
|
301
|
+
ensure_service!
|
302
|
+
service.write_entries Array(entries).map(&:to_grpc),
|
303
|
+
log_name: log_name, resource: resource,
|
304
|
+
labels: labels, partial_success: partial_success
|
305
|
+
true
|
306
|
+
end
|
307
|
+
|
308
|
+
##
|
309
|
+
# Creates an object that buffers, batches, and transmits log entries
|
310
|
+
# efficiently. Writing log entries to this object is asynchronous and
|
311
|
+
# will not block.
|
312
|
+
#
|
313
|
+
# Batches that cannot be delivered immediately are queued. When the
|
314
|
+
# queue is full new batch requests will raise errors that can be
|
315
|
+
# consumed using the {AsyncWriter#on_error} callback. This provides back
|
316
|
+
# pressure in case the writer cannot keep up with requests.
|
317
|
+
#
|
318
|
+
# This object is thread-safe; it may accept write requests from
|
319
|
+
# multiple threads simultaneously, and will serialize them when
|
320
|
+
# executing in the background thread.
|
321
|
+
#
|
322
|
+
# @param [Integer] max_batch_count The maximum number of log entries
|
323
|
+
# that may be buffered and sent in a batch.
|
324
|
+
# @param [Integer] max_batch_bytes The maximum byte size of log entries
|
325
|
+
# that may be buffered and sent in a batch.
|
326
|
+
# @param [Integer] max_queue_size The maximum number of pending
|
327
|
+
# write_entries requests that may be queued.
|
328
|
+
# @param [Numeric] interval The number of seconds to buffer log entries
|
329
|
+
# before a batch is written. Default is 5.
|
330
|
+
# @param [Integer] threads The number of threads used to make
|
331
|
+
# batched write_entries requests. Default is 10.
|
332
|
+
# @param [Boolean] partial_success Whether valid entries should be
|
333
|
+
# written even if some other entries fail due to `INVALID_ARGUMENT` or
|
334
|
+
# `PERMISSION_DENIED` errors when communicating to the Stackdriver
|
335
|
+
# Logging API.
|
336
|
+
#
|
337
|
+
# @return [Google::Cloud::Logging::AsyncWriter] an AsyncWriter object
|
338
|
+
# that buffers, batches, and transmits log entries efficiently.
|
339
|
+
#
|
340
|
+
# @example
|
341
|
+
# require "google/cloud/logging"
|
342
|
+
#
|
343
|
+
# logging = Google::Cloud::Logging.new
|
344
|
+
#
|
345
|
+
# async = logging.async_writer
|
346
|
+
#
|
347
|
+
# entry1 = logging.entry payload: "Job started."
|
348
|
+
# entry2 = logging.entry payload: "Job completed."
|
349
|
+
#
|
350
|
+
# labels = { job_size: "large", job_code: "red" }
|
351
|
+
# resource = logging.resource "gae_app",
|
352
|
+
# "module_id" => "1",
|
353
|
+
# "version_id" => "20150925t173233"
|
354
|
+
#
|
355
|
+
# async.write_entries [entry1, entry2],
|
356
|
+
# log_name: "my_app_log",
|
357
|
+
# resource: resource,
|
358
|
+
# labels: labels
|
359
|
+
#
|
360
|
+
def async_writer max_batch_count: 10000, max_batch_bytes: 10000000,
|
361
|
+
max_queue_size: 100, interval: 5, threads: 10,
|
362
|
+
partial_success: false
|
363
|
+
|
364
|
+
AsyncWriter.new self, max_count: max_batch_count,
|
365
|
+
max_bytes: max_batch_bytes,
|
366
|
+
max_queue: max_queue_size,
|
367
|
+
interval: interval, threads: threads,
|
368
|
+
partial_success: partial_success
|
369
|
+
end
|
370
|
+
|
371
|
+
##
|
372
|
+
# Returns a shared AsyncWriter for this Project. If this method is
|
373
|
+
# called multiple times, it will return the same object.
|
374
|
+
#
|
375
|
+
# @example
|
376
|
+
# require "google/cloud/logging"
|
377
|
+
#
|
378
|
+
# logging = Google::Cloud::Logging.new
|
379
|
+
#
|
380
|
+
# async = logging.shared_async_writer
|
381
|
+
#
|
382
|
+
# entry1 = logging.entry payload: "Job started."
|
383
|
+
# entry2 = logging.entry payload: "Job completed."
|
384
|
+
#
|
385
|
+
# labels = { job_size: "large", job_code: "red" }
|
386
|
+
# resource = logging.resource "gae_app",
|
387
|
+
# "module_id" => "1",
|
388
|
+
# "version_id" => "20150925t173233"
|
389
|
+
#
|
390
|
+
# async.write_entries [entry1, entry2],
|
391
|
+
# log_name: "my_app_log",
|
392
|
+
# resource: resource,
|
393
|
+
# labels: labels
|
394
|
+
#
|
395
|
+
def shared_async_writer
|
396
|
+
@shared_async_writer ||= async_writer
|
397
|
+
end
|
398
|
+
|
399
|
+
##
|
400
|
+
# Creates a logger instance that is API-compatible with Ruby's standard
|
401
|
+
# library [Logger](http://ruby-doc.org/stdlib/libdoc/logger/rdoc).
|
402
|
+
#
|
403
|
+
# The logger will create a new AsyncWriter object to transmit log
|
404
|
+
# entries on a background thread.
|
405
|
+
#
|
406
|
+
# @param [String] log_name A log resource name to be associated with the
|
407
|
+
# written log entries.
|
408
|
+
# @param [Google::Cloud::Logging::Resource] resource The monitored
|
409
|
+
# resource to be associated with written log entries.
|
410
|
+
# @param [Hash] labels A set of user-defined data to be associated with
|
411
|
+
# written log entries. Values can be strings or Procs which are
|
412
|
+
# functions of the request environment.
|
413
|
+
#
|
414
|
+
# @return [Google::Cloud::Logging::Logger] a Logger object that can be
|
415
|
+
# used in place of a ruby standard library logger object.
|
416
|
+
#
|
417
|
+
# @example
|
418
|
+
# require "google/cloud/logging"
|
419
|
+
#
|
420
|
+
# logging = Google::Cloud::Logging.new
|
421
|
+
#
|
422
|
+
# resource = logging.resource "gae_app",
|
423
|
+
# module_id: "1",
|
424
|
+
# version_id: "20150925t173233"
|
425
|
+
#
|
426
|
+
# logger = logging.logger "my_app_log", resource, env: :production
|
427
|
+
# logger.info "Job started."
|
428
|
+
#
|
429
|
+
# @example Provide a hash to write a JSON payload to the log:
|
430
|
+
# require "google/cloud/logging"
|
431
|
+
#
|
432
|
+
# logging = Google::Cloud::Logging.new
|
433
|
+
#
|
434
|
+
# resource = logging.resource "gae_app",
|
435
|
+
# module_id: "1",
|
436
|
+
# version_id: "20150925t173233"
|
437
|
+
#
|
438
|
+
# logger = logging.logger "my_app_log", resource, env: :production
|
439
|
+
#
|
440
|
+
# payload = { "stats" => { "a" => 8, "b" => 12.5} }
|
441
|
+
# logger.info payload
|
442
|
+
#
|
443
|
+
def logger log_name, resource, labels = {}
|
444
|
+
Logger.new shared_async_writer, log_name, resource, labels
|
445
|
+
end
|
446
|
+
|
447
|
+
##
|
448
|
+
# Lists log names. Use this method to retrieve log names from Cloud
|
449
|
+
# Logging.
|
450
|
+
#
|
451
|
+
# @param [String] resource The cloud resource from which to retrieve log
|
452
|
+
# names. Optional. If `nil`, the ID of the receiving project instance
|
453
|
+
# will be used. Examples: `"projects/my-project-1A"`,
|
454
|
+
# `"projects/1234567890"`.
|
455
|
+
# @param [String] token A previously-returned page token representing
|
456
|
+
# part of the larger set of results to view.
|
457
|
+
# @param [Integer] max Maximum number of log names to return.
|
458
|
+
#
|
459
|
+
# @return [Array<String>] A list of log names. For example,
|
460
|
+
# `projects/my-project/syslog` or
|
461
|
+
# `organizations/123/cloudresourcemanager.googleapis.com%2Factivity`.
|
462
|
+
# (See {Google::Cloud::Logging::Log::List})
|
463
|
+
#
|
464
|
+
# @example
|
465
|
+
# require "google/cloud/logging"
|
466
|
+
#
|
467
|
+
# logging = Google::Cloud::Logging.new
|
468
|
+
# logs = logging.logs
|
469
|
+
# logs.each { |l| puts l }
|
470
|
+
#
|
471
|
+
# @example Retrieve all log names: (See {Log::List#all})
|
472
|
+
# require "google/cloud/logging"
|
473
|
+
#
|
474
|
+
# logging = Google::Cloud::Logging.new
|
475
|
+
# logs = logging.logs
|
476
|
+
#
|
477
|
+
# logs.all { |l| puts l }
|
478
|
+
#
|
479
|
+
def logs resource: nil, token: nil, max: nil
|
480
|
+
ensure_service!
|
481
|
+
list_grpc = service.list_logs resource: resource, token: token,
|
482
|
+
max: max
|
483
|
+
Log::List.from_grpc list_grpc, service, resource: resource, max: max
|
484
|
+
end
|
485
|
+
alias find_logs logs
|
486
|
+
alias log_names logs
|
487
|
+
alias find_log_names logs
|
488
|
+
|
489
|
+
##
|
490
|
+
# Deletes a log and all its log entries. The log will reappear if it
|
491
|
+
# receives new entries.
|
492
|
+
#
|
493
|
+
# @param [String] name The name of the log, which may be the full path
|
494
|
+
# including the project ID (`projects/<project-id>/logs/<log-id>`), or
|
495
|
+
# just the short name (`<log-id>`), in which case the beginning of the
|
496
|
+
# path will be automatically prepended, using the ID of the current
|
497
|
+
# project.
|
498
|
+
#
|
499
|
+
# @return [Boolean] Returns `true` if the log and all its log entries
|
500
|
+
# were deleted.
|
501
|
+
#
|
502
|
+
# @example
|
503
|
+
# require "google/cloud/logging"
|
504
|
+
#
|
505
|
+
# logging = Google::Cloud::Logging.new
|
506
|
+
# logging.delete_log "my_app_log"
|
507
|
+
#
|
508
|
+
def delete_log name
|
509
|
+
ensure_service!
|
510
|
+
service.delete_log name
|
511
|
+
true
|
512
|
+
end
|
513
|
+
|
514
|
+
##
|
515
|
+
# Retrieves the list of monitored resource descriptors that are used by
|
516
|
+
# Stackdriver Logging.
|
517
|
+
#
|
518
|
+
# @see https://cloud.google.com/logging/docs/api/v2/resource-list
|
519
|
+
# Monitored Resources
|
520
|
+
#
|
521
|
+
# @param [String] token A previously-returned page token representing
|
522
|
+
# part of the larger set of results to view.
|
523
|
+
# @param [Integer] max Maximum number of resource descriptors to return.
|
524
|
+
#
|
525
|
+
# @return [Array<Google::Cloud::Logging::ResourceDescriptor>] (See
|
526
|
+
# {Google::Cloud::Logging::ResourceDescriptor::List})
|
527
|
+
#
|
528
|
+
# @example
|
529
|
+
# require "google/cloud/logging"
|
530
|
+
#
|
531
|
+
# logging = Google::Cloud::Logging.new
|
532
|
+
# resource_descriptors = logging.resource_descriptors
|
533
|
+
# resource_descriptors.each do |rd|
|
534
|
+
# label_keys = rd.labels.map(&:key).join(", ")
|
535
|
+
# puts "#{rd.type} (#{label_keys})"
|
536
|
+
# end
|
537
|
+
#
|
538
|
+
# @example Pagination:
|
539
|
+
# require "google/cloud/logging"
|
540
|
+
#
|
541
|
+
# logging = Google::Cloud::Logging.new
|
542
|
+
# resource_descriptors = logging.resource_descriptors
|
543
|
+
#
|
544
|
+
# resource_descriptors.all do |rd|
|
545
|
+
# puts rd.type
|
546
|
+
# end
|
547
|
+
#
|
548
|
+
def resource_descriptors token: nil, max: nil
|
549
|
+
ensure_service!
|
550
|
+
list_grpc = service.list_resource_descriptors token: token, max: max
|
551
|
+
ResourceDescriptor::List.from_grpc list_grpc, service, max
|
552
|
+
end
|
553
|
+
alias find_resource_descriptors resource_descriptors
|
554
|
+
|
555
|
+
##
|
556
|
+
# Creates a new monitored resource instance.
|
557
|
+
#
|
558
|
+
# @param [String] type The type of resource, as represented by a
|
559
|
+
# {ResourceDescriptor}.
|
560
|
+
# @param [Hash] labels A set of labels that can be used to describe
|
561
|
+
# instances of this monitored resource type.
|
562
|
+
#
|
563
|
+
# @return [Google::Cloud::Logging::Resource]
|
564
|
+
#
|
565
|
+
# @example
|
566
|
+
# require "google/cloud/logging"
|
567
|
+
#
|
568
|
+
# logging = Google::Cloud::Logging.new
|
569
|
+
#
|
570
|
+
# resource = logging.resource "gae_app",
|
571
|
+
# "module_id" => "1",
|
572
|
+
# "version_id" => "20150925t173233"
|
573
|
+
#
|
574
|
+
def resource type, labels = {}
|
575
|
+
Resource.new.tap do |r|
|
576
|
+
r.type = type
|
577
|
+
r.labels = labels
|
578
|
+
end
|
579
|
+
end
|
580
|
+
alias new_resource resource
|
581
|
+
|
582
|
+
##
|
583
|
+
# Retrieves the list of sinks belonging to the project.
|
584
|
+
#
|
585
|
+
# @param [String] token A previously-returned page token representing
|
586
|
+
# part of the larger set of results to view.
|
587
|
+
# @param [Integer] max Maximum number of sinks to return.
|
588
|
+
#
|
589
|
+
# @return [Array<Google::Cloud::Logging::Sink>] (See
|
590
|
+
# {Google::Cloud::Logging::Sink::List})
|
591
|
+
#
|
592
|
+
# @example
|
593
|
+
# require "google/cloud/logging"
|
594
|
+
#
|
595
|
+
# logging = Google::Cloud::Logging.new
|
596
|
+
# sinks = logging.sinks
|
597
|
+
# sinks.each do |s|
|
598
|
+
# puts "#{s.name}: #{s.filter} -> #{s.destination}"
|
599
|
+
# end
|
600
|
+
#
|
601
|
+
# @example Retrieve all sinks: (See {Sink::List#all})
|
602
|
+
# require "google/cloud/logging"
|
603
|
+
#
|
604
|
+
# logging = Google::Cloud::Logging.new
|
605
|
+
# sinks = logging.sinks
|
606
|
+
#
|
607
|
+
# sinks.all do |s|
|
608
|
+
# puts "#{s.name}: #{s.filter} -> #{s.destination}"
|
609
|
+
# end
|
610
|
+
#
|
611
|
+
def sinks token: nil, max: nil
|
612
|
+
ensure_service!
|
613
|
+
list_grpc = service.list_sinks token: token, max: max
|
614
|
+
Sink::List.from_grpc list_grpc, service, max
|
615
|
+
end
|
616
|
+
alias find_sinks sinks
|
617
|
+
|
618
|
+
##
|
619
|
+
# Creates a new project sink. When you create a sink, only new log
|
620
|
+
# entries that match the sink's filter are exported. Stackdriver Logging
|
621
|
+
# does not send previously-ingested log entries to the sink's
|
622
|
+
# destination.
|
623
|
+
#
|
624
|
+
# Before creating the sink, ensure that you have granted the sink's
|
625
|
+
# _unique writer identity_ permission to write logs to the destination.
|
626
|
+
# See [Destination
|
627
|
+
# permissions](https://cloud.google.com/logging/docs/export/configure_export_v2#dest-auth).
|
628
|
+
#
|
629
|
+
# @see https://cloud.google.com/logging/docs/export
|
630
|
+
# Overview of logs exports
|
631
|
+
# @see https://cloud.google.com/logging/docs/reference/v2/rpc/google.logging.v2#configservicev2
|
632
|
+
# ConfigService API which includes sink methods
|
633
|
+
#
|
634
|
+
# @overload create_sink(name, destination, filter: nil, unique_writer_identity: nil)
|
635
|
+
# @param [String] name The client-assigned sink identifier. Sink
|
636
|
+
# identifiers are limited to 1000 characters and can include only
|
637
|
+
# the following characters: `A-Z`, `a-z`, `0-9`, and the special
|
638
|
+
# characters `_-.`.
|
639
|
+
# @param [String] destination The resource name of the export
|
640
|
+
# destination. See [About
|
641
|
+
# sinks](https://cloud.google.com/logging/docs/api/tasks/exporting-logs#about_sinks)
|
642
|
+
# for examples.
|
643
|
+
# @param [String, nil] filter An [advanced logs
|
644
|
+
# filter](https://cloud.google.com/logging/docs/view/advanced_filters)
|
645
|
+
# that defines the log entries to be exported. The filter must be
|
646
|
+
# consistent with the log entry format designed by the `version`
|
647
|
+
# parameter, regardless of the format of the log entry that was
|
648
|
+
# originally written to Stackdriver Logging.
|
649
|
+
# @param [Boolean] unique_writer_identity Whether the sink will have a
|
650
|
+
# dedicated service account returned in the sink's
|
651
|
+
# `writer_identity`. Set this field to be true to export logs from
|
652
|
+
# one project to a different project. This field is ignored for
|
653
|
+
# non-project sinks (e.g. organization sinks) because those sinks
|
654
|
+
# are required to have dedicated service accounts. Optional.
|
655
|
+
#
|
656
|
+
# @return [Google::Cloud::Logging::Sink] a project sink
|
657
|
+
#
|
658
|
+
# @example
|
659
|
+
# require "google/cloud/storage"
|
660
|
+
#
|
661
|
+
# storage = Google::Cloud::Storage.new
|
662
|
+
#
|
663
|
+
# bucket = storage.create_bucket "my-logs-bucket"
|
664
|
+
#
|
665
|
+
# # Grant owner permission to Stackdriver Logging service
|
666
|
+
# email = "cloud-logs@google.com"
|
667
|
+
# bucket.acl.add_owner "group-#{email}"
|
668
|
+
#
|
669
|
+
# require "google/cloud/logging"
|
670
|
+
#
|
671
|
+
# logging = Google::Cloud::Logging.new
|
672
|
+
#
|
673
|
+
# sink = logging.create_sink "my-sink",
|
674
|
+
# "storage.googleapis.com/#{bucket.id}"
|
675
|
+
#
|
676
|
+
def create_sink name, destination, filter: nil,
|
677
|
+
unique_writer_identity: nil,
|
678
|
+
start_at: nil, end_at: nil, version: nil
|
679
|
+
ensure_service!
|
680
|
+
|
681
|
+
if start_at
|
682
|
+
warn "[DEPRECATION] start_at is deprecated and will be ignored."
|
683
|
+
end
|
684
|
+
if end_at
|
685
|
+
warn "[DEPRECATION] end_at is deprecated and will be ignored."
|
686
|
+
end
|
687
|
+
if version
|
688
|
+
warn "[DEPRECATION] version is deprecated and will be ignored."
|
689
|
+
end
|
690
|
+
|
691
|
+
grpc = service.create_sink \
|
692
|
+
name, destination, filter,
|
693
|
+
unique_writer_identity: unique_writer_identity
|
694
|
+
Sink.from_grpc grpc, service
|
695
|
+
end
|
696
|
+
alias new_sink create_sink
|
697
|
+
|
698
|
+
##
|
699
|
+
# Retrieves a sink by name.
|
700
|
+
#
|
701
|
+
# @param [String] sink_name Name of a sink.
|
702
|
+
#
|
703
|
+
# @return [Google::Cloud::Logging::Sink, nil] Returns `nil` if the sink
|
704
|
+
# does not exist.
|
705
|
+
#
|
706
|
+
# @example
|
707
|
+
# require "google/cloud/logging"
|
708
|
+
#
|
709
|
+
# logging = Google::Cloud::Logging.new
|
710
|
+
# sink = logging.sink "existing-sink"
|
711
|
+
#
|
712
|
+
# @example By default `nil` will be returned if the sink does not exist.
|
713
|
+
# require "google/cloud/logging"
|
714
|
+
#
|
715
|
+
# logging = Google::Cloud::Logging.new
|
716
|
+
# sink = logging.sink "non-existing-sink" # nil
|
717
|
+
#
|
718
|
+
def sink sink_name
|
719
|
+
ensure_service!
|
720
|
+
grpc = service.get_sink sink_name
|
721
|
+
Sink.from_grpc grpc, service
|
722
|
+
rescue Google::Cloud::NotFoundError
|
723
|
+
nil
|
724
|
+
end
|
725
|
+
alias get_sink sink
|
726
|
+
alias find_sink sink
|
727
|
+
|
728
|
+
##
|
729
|
+
# Retrieves the list of metrics belonging to the project.
|
730
|
+
#
|
731
|
+
# @param [String] token A previously-returned page token representing
|
732
|
+
# part of the larger set of results to view.
|
733
|
+
# @param [Integer] max Maximum number of metrics to return.
|
734
|
+
#
|
735
|
+
# @return [Array<Google::Cloud::Logging::Metric>] (See
|
736
|
+
# {Google::Cloud::Logging::Metric::List})
|
737
|
+
#
|
738
|
+
# @example
|
739
|
+
# require "google/cloud/logging"
|
740
|
+
#
|
741
|
+
# logging = Google::Cloud::Logging.new
|
742
|
+
# metrics = logging.metrics
|
743
|
+
# metrics.each do |m|
|
744
|
+
# puts "#{m.name}: #{m.filter}"
|
745
|
+
# end
|
746
|
+
#
|
747
|
+
# @example Retrieve all metrics: (See {Metric::List#all})
|
748
|
+
# require "google/cloud/logging"
|
749
|
+
#
|
750
|
+
# logging = Google::Cloud::Logging.new
|
751
|
+
# metrics = logging.metrics
|
752
|
+
#
|
753
|
+
# metrics.all do |m|
|
754
|
+
# puts "#{m.name}: #{m.filter}"
|
755
|
+
# end
|
756
|
+
#
|
757
|
+
def metrics token: nil, max: nil
|
758
|
+
ensure_service!
|
759
|
+
grpc = service.list_metrics token: token, max: max
|
760
|
+
Metric::List.from_grpc grpc, service, max
|
761
|
+
end
|
762
|
+
alias find_metrics metrics
|
763
|
+
|
764
|
+
##
|
765
|
+
# Creates a new logs-based metric for Google Cloud Monitoring.
|
766
|
+
#
|
767
|
+
# @see https://cloud.google.com/logging/docs/view/logs_based_metrics
|
768
|
+
# Logs-based Metrics
|
769
|
+
# @see https://cloud.google.com/monitoring/docs Google Cloud Monitoring
|
770
|
+
#
|
771
|
+
# @param [String] name The client-assigned metric identifier. Metric
|
772
|
+
# identifiers are limited to 1000 characters and can include only the
|
773
|
+
# following characters: `A-Z`, `a-z`, `0-9`, and the special
|
774
|
+
# characters `_-.,+!*',()%/\`. The forward-slash character (`/`)
|
775
|
+
# denotes a hierarchy of name pieces, and it cannot be the first
|
776
|
+
# character of the name.
|
777
|
+
# @param [String] filter An [advanced logs
|
778
|
+
# filter](https://cloud.google.com/logging/docs/view/advanced_filters).
|
779
|
+
# @param [String, nil] description A description of this metric, which
|
780
|
+
# is used in documentation.
|
781
|
+
#
|
782
|
+
# @return [Google::Cloud::Logging::Metric]
|
783
|
+
#
|
784
|
+
# @example
|
785
|
+
# require "google/cloud/logging"
|
786
|
+
#
|
787
|
+
# logging = Google::Cloud::Logging.new
|
788
|
+
# metric = logging.create_metric "errors", "severity>=ERROR"
|
789
|
+
#
|
790
|
+
def create_metric name, filter, description: nil
|
791
|
+
ensure_service!
|
792
|
+
grpc = service.create_metric name, filter, description
|
793
|
+
Metric.from_grpc grpc, service
|
794
|
+
end
|
795
|
+
alias new_metric create_metric
|
796
|
+
|
797
|
+
##
|
798
|
+
# Retrieves metric by name.
|
799
|
+
#
|
800
|
+
# @param [String] name Name of a metric.
|
801
|
+
#
|
802
|
+
# @return [Google::Cloud::Logging::Metric, nil] Returns `nil` if metric
|
803
|
+
# does not exist.
|
804
|
+
#
|
805
|
+
# @example
|
806
|
+
# require "google/cloud/logging"
|
807
|
+
#
|
808
|
+
# logging = Google::Cloud::Logging.new
|
809
|
+
# metric = logging.metric "existing_metric"
|
810
|
+
#
|
811
|
+
# @example By default `nil` will be returned if metric does not exist.
|
812
|
+
# require "google/cloud/logging"
|
813
|
+
#
|
814
|
+
# logging = Google::Cloud::Logging.new
|
815
|
+
# metric = logging.metric "non_existing_metric" # nil
|
816
|
+
#
|
817
|
+
def metric name
|
818
|
+
ensure_service!
|
819
|
+
grpc = service.get_metric name
|
820
|
+
Metric.from_grpc grpc, service
|
821
|
+
rescue Google::Cloud::NotFoundError
|
822
|
+
nil
|
823
|
+
end
|
824
|
+
alias get_metric metric
|
825
|
+
alias find_metric metric
|
826
|
+
|
827
|
+
protected
|
828
|
+
|
829
|
+
##
|
830
|
+
# @private Raise an error unless an active connection to the service is
|
831
|
+
# available.
|
832
|
+
def ensure_service!
|
833
|
+
raise "Must have active connection to service" unless service
|
834
|
+
end
|
835
|
+
end
|
836
|
+
end
|
837
|
+
end
|
838
|
+
end
|