google-cloud-logging 2.0.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (37) hide show
  1. checksums.yaml +7 -0
  2. data/.yardopts +18 -0
  3. data/AUTHENTICATION.md +178 -0
  4. data/CHANGELOG.md +407 -0
  5. data/CODE_OF_CONDUCT.md +40 -0
  6. data/CONTRIBUTING.md +188 -0
  7. data/INSTRUMENTATION.md +71 -0
  8. data/LICENSE +201 -0
  9. data/LOGGING.md +32 -0
  10. data/OVERVIEW.md +321 -0
  11. data/TROUBLESHOOTING.md +31 -0
  12. data/lib/google-cloud-logging.rb +161 -0
  13. data/lib/google/cloud/logging.rb +188 -0
  14. data/lib/google/cloud/logging/async_writer.rb +513 -0
  15. data/lib/google/cloud/logging/convert.rb +70 -0
  16. data/lib/google/cloud/logging/credentials.rb +44 -0
  17. data/lib/google/cloud/logging/entry.rb +528 -0
  18. data/lib/google/cloud/logging/entry/http_request.rb +167 -0
  19. data/lib/google/cloud/logging/entry/list.rb +178 -0
  20. data/lib/google/cloud/logging/entry/operation.rb +91 -0
  21. data/lib/google/cloud/logging/entry/source_location.rb +85 -0
  22. data/lib/google/cloud/logging/errors.rb +101 -0
  23. data/lib/google/cloud/logging/log/list.rb +156 -0
  24. data/lib/google/cloud/logging/logger.rb +633 -0
  25. data/lib/google/cloud/logging/metric.rb +168 -0
  26. data/lib/google/cloud/logging/metric/list.rb +170 -0
  27. data/lib/google/cloud/logging/middleware.rb +307 -0
  28. data/lib/google/cloud/logging/project.rb +838 -0
  29. data/lib/google/cloud/logging/rails.rb +232 -0
  30. data/lib/google/cloud/logging/resource.rb +85 -0
  31. data/lib/google/cloud/logging/resource_descriptor.rb +137 -0
  32. data/lib/google/cloud/logging/resource_descriptor/list.rb +175 -0
  33. data/lib/google/cloud/logging/service.rb +239 -0
  34. data/lib/google/cloud/logging/sink.rb +315 -0
  35. data/lib/google/cloud/logging/sink/list.rb +168 -0
  36. data/lib/google/cloud/logging/version.rb +22 -0
  37. 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