google-cloud-logging 2.0.0

data/LOGGING.md

@@ -0,0 +1,32 @@
+# Enabling gRPC Logging
+
+To enable logging for this library, set the logger for the underlying
+[gRPC](https://github.com/grpc/grpc/tree/master/src/ruby) library. The logger
+that you set may be a Ruby stdlib
+[`Logger`](https://ruby-doc.org/stdlib-2.5.0/libdoc/logger/rdoc/Logger.html) as
+shown below, or a
+[`Google::Cloud::Logging::Logger`](https://googleapis.dev/ruby/google-cloud-logging/latest)
+that will write logs to [Stackdriver
+Logging](https://cloud.google.com/logging/). See
+[grpc/logconfig.rb](https://github.com/grpc/grpc/blob/master/src/ruby/lib/grpc/logconfig.rb)
+and the gRPC
+[spec_helper.rb](https://github.com/grpc/grpc/blob/master/src/ruby/spec/spec_helper.rb)
+for additional information.
+
+Configuring a Ruby stdlib logger:
+
+```ruby
+require "logger"
+
+module MyLogger
+  LOGGER = Logger.new $stderr, level: Logger::WARN
+  def logger
+    LOGGER
+  end
+end
+
+# Define a gRPC module-level logger method before grpc/logconfig.rb loads.
+module GRPC
+  extend MyLogger
+end
+```

data/OVERVIEW.md

@@ -0,0 +1,321 @@
+# Stackdriver Logging
+
+The Stackdriver Logging service collects and stores logs from applications and
+services on the Google Cloud Platform, giving you fine-grained, programmatic
+control over your projects' logs. You can use the Stackdriver Logging API to:
+
+* [Read and filter log entries](#listing-log-entries)
+* [Export your log entries](#exporting-log-entries) to Cloud Storage,
+  BigQuery, or Cloud Pub/Sub
+* [Create logs-based metrics](#creating-logs-based-metrics) for use in
+  Cloud Monitoring
+* [Write log entries](#writing-log-entries)
+
+For general information about Stackdriver Logging, read [Stackdriver Logging
+Documentation](https://cloud.google.com/logging/docs/).
+
+The goal of google-cloud is to provide an API that is comfortable to Rubyists.
+Your authentication credentials are detected automatically in Google Cloud
+Platform (GCP), including Google Compute Engine (GCE), Google Kubernetes Engine
+(GKE), Google App Engine (GAE), Google Cloud Functions (GCF) and Cloud Run. In
+other environments you can configure authentication easily, either directly in
+your code or via environment variables. Read more about the options for
+connecting in the {file:AUTHENTICATION.md Authentication Guide}.
+
+## Listing log entries
+
+Stackdriver Logging gathers log entries from many services, including Google App
+Engine and Google Compute Engine. (See the [List of Log
+Types](https://cloud.google.com/logging/docs/view/logs_index).) In addition, you
+can write your own log entries to the service.
+
+{Google::Cloud::Logging::Project#entries Project#entries} returns the
+{Google::Cloud::Logging::Entry Entry} records belonging to your project:
+
+```ruby
+require "google/cloud/logging"
+
+logging = Google::Cloud::Logging.new
+entries = logging.entries
+entries.each do |e|
+  puts "[#{e.timestamp}] #{e.log_name} #{e.payload.inspect}"
+end
+```
+
+You can narrow the results to a single log using an [advanced logs
+filter](https://cloud.google.com/logging/docs/view/advanced_filters). A log is a
+named collection of entries. Logs can be produced by Google Cloud Platform
+services, by third-party services, or by your applications. For example, the log
+`compute.googleapis.com/activity_log` is produced by Google Compute Engine. Logs
+are simply referenced by name in google-cloud. There is no `Log` type in
+google-cloud or `Log` resource in the Stackdriver Logging API.
+
+```ruby
+require "google/cloud/logging"
+
+logging = Google::Cloud::Logging.new
+entries = logging.entries filter: "logName:syslog"
+entries.each do |e|
+  puts "[#{e.timestamp}] #{e.payload.inspect}"
+end
+```
+
+You can also order the log entries by `timestamp`.
+
+```ruby
+require "google/cloud/logging"
+
+logging = Google::Cloud::Logging.new
+entries = logging.entries order: "timestamp desc"
+entries.each do |e|
+  puts "[#{e.timestamp}] #{e.log_name}"
+end
+```
+
+## Exporting log entries
+
+Stackdriver Logging lets you export log entries to destinations including Google
+Cloud Storage buckets (for long term log storage), Google BigQuery datasets (for
+log analysis), and Google Pub/Sub (for streaming to other applications).
+
+### Creating sinks
+
+A {Google::Cloud::Logging::Sink Sink} is an object that lets you to specify a
+set of log entries to export.
+
+In addition to the name of the sink and the export destination,
+{Google::Cloud::Logging::Project#create_sink Project#create_sink} accepts an
+[advanced logs
+filter](https://cloud.google.com/logging/docs/view/advanced_filters) to narrow
+the collection.
+
+Before creating the sink, ensure that you have granted `cloud-logs@google.com`
+permission to write logs to the destination. See [Exporting Logs
+(V2)](https://cloud.google.com/logging/docs/export/configure_export_v2).
+
+```ruby
+require "google/cloud/storage"
+require "google/cloud/logging"
+
+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}"
+
+logging = Google::Cloud::Logging.new
+
+sink = logging.create_sink "my-sink",
+                           "storage.googleapis.com/#{bucket.id}"
+```
+
+When you create a sink, only new log entries are exported. Stackdriver Logging
+does not send previously-ingested log entries to the sink's destination.
+
+### Listing sinks
+
+You can also list the sinks belonging to your project with
+{Google::Cloud::Logging::Project#sinks Project#sinks}.
+
+```ruby
+require "google/cloud/logging"
+
+logging = Google::Cloud::Logging.new
+sinks = logging.sinks
+sinks.each do |s|
+  puts "#{s.name}: #{s.filter} -> #{s.destination}"
+end
+```
+
+## Creating logs-based metrics
+
+You can use log entries in your project as the basis for [Google Cloud
+Monitoring](https://cloud.google.com/monitoring/docs) metrics. These metrics can
+then be used to produce Cloud Monitoring reports and alerts.
+
+### Creating metrics
+
+A metric is a measured value that can be used to assess a system. Use
+{Google::Cloud::Logging::Project#create_metric Project#create_metric} to
+configure a  {Google::Cloud::Logging::Metric Metric} based on a collection of
+log entries matching an [advanced logs
+filter](https://cloud.google.com/logging/docs/view/advanced_filters).
+
+```ruby
+require "google/cloud/logging"
+
+logging = Google::Cloud::Logging.new
+metric = logging.create_metric "errors", "severity>=ERROR"
+```
+
+### Listing metrics
+
+You can also list the metrics belonging to your project with
+{Google::Cloud::Logging::Project#metrics Project#metrics}.
+
+```ruby
+require "google/cloud/logging"
+
+logging = Google::Cloud::Logging.new
+metrics = logging.metrics
+metrics.each do |m|
+  puts "#{m.name}: #{m.filter}"
+end
+```
+
+## Writing log entries
+
+An {Google::Cloud::Logging::Entry} is composed of metadata and a payload. The
+payload is traditionally a message string, but in Stackdriver Logging it can
+also be a JSON or protocol buffer object. A single log can have entries with
+different payload types. In addition to the payload, your argument(s) to
+{Google::Cloud::Logging::Project#write_entries Project#write_entries} must also
+contain a log name and a resource.
+
+```ruby
+require "google/cloud/logging"
+
+logging = Google::Cloud::Logging.new
+
+entry = logging.entry
+entry.payload = "Job started."
+entry.log_name = "my_app_log"
+entry.resource.type = "gae_app"
+entry.resource.labels[:module_id] = "1"
+entry.resource.labels[:version_id] = "20150925t173233"
+
+logging.write_entries entry
+```
+
+To write a JSON payload to the log, simply pass a hash argument:
+
+```ruby
+require "google/cloud/logging"
+
+logging = Google::Cloud::Logging.new
+
+entry = logging.entry
+entry.payload = { "stats" => { "a" => 8, "b" => 12.5} }
+entry.log_name = "my_app_log"
+entry.resource.type = "gae_app"
+entry.resource.labels[:module_id] = "1"
+entry.resource.labels[:version_id] = "20150925t173233"
+
+logging.write_entries entry
+```
+
+If you write a collection of log entries, you can provide the log name,
+resource, and/or labels hash to be used for all of the entries, and omit these
+values from the individual entries.
+
+```ruby
+require "google/cloud/logging"
+
+logging = Google::Cloud::Logging.new
+
+entry1 = logging.entry
+entry1.payload = "Job started."
+entry2 = logging.entry
+entry2.payload = "Job completed."
+labels = { job_size: "large", job_code: "red" }
+
+resource = logging.resource "gae_app",
+                            "module_id" => "1",
+                            "version_id" => "20150925t173233"
+
+logging.write_entries [entry1, entry2],
+                      log_name: "my_app_log",
+                      resource: resource,
+                      labels: labels
+```
+
+Normally, writing log entries is done synchronously; the call to
+{Google::Cloud::Logging::Project#write_entries Project#write_entries} will block
+until it has either completed transmitting the data or encountered an error. To
+"fire and forget" without blocking, use {Google::Cloud::Logging::AsyncWriter
+AsyncWriter}; it spins up a background thread that writes log entries in
+batches. Calls to {Google::Cloud::Logging::AsyncWriter#write_entries
+AsyncWriter#write_entries} simply add entries to its work queue and return
+immediately.
+
+```ruby
+require "google/cloud/logging"
+
+logging = Google::Cloud::Logging.new
+async = logging.async_writer
+
+entry1 = logging.entry
+entry1.payload = "Job started."
+entry2 = logging.entry
+entry2.payload = "Job completed."
+labels = { job_size: "large", job_code: "red" }
+
+resource = logging.resource "gae_app",
+                            "module_id" => "1",
+                            "version_id" => "20150925t173233"
+
+async.write_entries [entry1, entry2],
+                    log_name: "my_app_log",
+                    resource: resource,
+                    labels: labels,
+                    partial_success: true
+```
+
+### Creating a Ruby Logger implementation
+
+If your environment requires a logger instance that is API-compatible with
+Ruby's standard library [Logger](http://ruby-doc.org/stdlib/libdoc/logger/rdoc),
+you can use {Google::Cloud::Logging::Project#logger Project#logger} to create
+one.
+
+```ruby
+require "google/cloud/logging"
+
+logging = Google::Cloud::Logging.new
+
+resource = logging.resource "gae_app",
+                            module_id: "1",
+                            version_id: "20150925t173233"
+
+logger = logging.logger "my_app_log", resource, env: :production
+logger.info "Job started."
+```
+
+By default, the logger instance writes log entries asynchronously in a
+background thread using an {Google::Cloud::Logging::AsyncWriter AsyncWriter}. If
+you want to customize or disable asynchronous writing, you may call the Logger
+constructor directly.
+
+```ruby
+require "google/cloud/logging"
+
+logging = Google::Cloud::Logging.new
+
+resource = logging.resource "gae_app",
+                            module_id: "1",
+                            version_id: "20150925t173233"
+
+logger = Google::Cloud::Logging::Logger.new logging,
+                                            "my_app_log",
+                                            resource,
+                                            {env: :production}
+logger.info "Log entry written synchronously."
+```
+
+## Configuring timeout
+
+You can configure the request `timeout` value in seconds.
+
+```ruby
+require "google/cloud/logging"
+
+logging = Google::Cloud::Logging.new timeout: 120
+```
+
+## Additional information
+
+Stackdriver Logging can be configured to be used in Rack applications or to use
+gRPC's logging. To learn more, see the {file:INSTRUMENTATION.md Instrumentation
+Guide} and {file:LOGGING.md Logging guide}.

data/TROUBLESHOOTING.md

@@ -0,0 +1,31 @@
+# Troubleshooting
+
+## Where can I get more help?
+
+### Ask the Community
+
+If you have a question about how to use a Google Cloud client library in your
+project or are stuck in the Developer's console and don't know where to turn,
+it's possible your questions have already been addressed by the community.
+
+First, check out the appropriate tags on StackOverflow:
+  - [`google-cloud-platform+ruby+logging`][so-ruby]
+
+Next, try searching through the issues on GitHub:
+
+  - [`api:logging` issues][gh-search-ruby]
+
+Still nothing?
+
+### Ask the Developers
+
+If you're experiencing a bug with the code, or have an idea for how it can be
+improved, *please* create a new issue on GitHub so we can talk about it.
+
+  - [New issue][gh-ruby]
+
+[so-ruby]: http://stackoverflow.com/questions/tagged/google-cloud-platform+ruby+logging
+
+[gh-search-ruby]: https://github.com/googleapis/google-cloud-ruby/issues?q=label%3A%22api%3A+logging%22
+
+[gh-ruby]: https://github.com/googleapis/google-cloud-ruby/issues/new

data/lib/google-cloud-logging.rb

@@ -0,0 +1,161 @@
+# Copyright 2016 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+##
+# This file is here to be autorequired by bundler, so that the
+# Google::Cloud.logging and Google::Cloud#logging methods can be available, but
+# the library and all dependencies won't be loaded until required and used.
+
+
+gem "google-cloud-core"
+require "google/cloud" unless defined? Google::Cloud.new
+require "google/cloud/config"
+require "googleauth"
+
+module Google
+  module Cloud
+    ##
+    # Creates a new object for connecting to the Stackdriver Logging service.
+    # Each call creates a new connection.
+    #
+    # For more information on connecting to Google Cloud see the
+    # {file:AUTHENTICATION.md Authentication Guide}.
+    #
+    # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling the
+    #   set of resources and operations that the connection can access. See
+    #   [Using OAuth 2.0 to Access Google
+    #   APIs](https://developers.google.com/identity/protocols/OAuth2).
+    #
+    #   The default scope is:
+    #
+    #   * `https://www.googleapis.com/auth/logging.admin`
+    #
+    # @param [Integer] timeout Default timeout to use in requests. Optional.
+    #
+    # @return [Google::Cloud::Logging::Project]
+    #
+    # @example
+    #   require "google/cloud"
+    #
+    #   gcloud = Google::Cloud.new
+    #   logging = gcloud.logging
+    #
+    #   entries = logging.entries
+    #   entries.each do |e|
+    #     puts "[#{e.timestamp}] #{e.log_name} #{e.payload.inspect}"
+    #   end
+    #
+    # @example The default scope can be overridden with the `scope` option:
+    #   require "google/cloud"
+    #
+    #   gcloud  = Google::Cloud.new
+    #   platform_scope = "https://www.googleapis.com/auth/cloud-platform"
+    #   logging = gcloud.logging scope: platform_scope
+    #
+    def logging scope: nil, timeout: nil
+      timeout ||= @timeout
+      Google::Cloud.logging @project, @keyfile, scope:   scope,
+                                                timeout: timeout
+    end
+
+    ##
+    # Creates a new object for connecting to the Stackdriver Logging service.
+    # Each call creates a new connection.
+    #
+    # For more information on connecting to Google Cloud see the
+    # {file:AUTHENTICATION.md Authentication Guide}.
+    #
+    # @param [String] project_id Project identifier for the Stackdriver Logging
+    #   service you are connecting to. If not present, the default project for
+    #   the credentials is used.
+    # @param [String, Hash, Google::Auth::Credentials] credentials The path to
+    #   the keyfile as a String, the contents of the keyfile as a Hash, or a
+    #   Google::Auth::Credentials object. (See {Logging::Credentials})
+    # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling the
+    #   set of resources and operations that the connection can access. See
+    #   [Using OAuth 2.0 to Access Google
+    #   APIs](https://developers.google.com/identity/protocols/OAuth2).
+    #
+    #   The default scope is:
+    #
+    #   * `https://www.googleapis.com/auth/logging.admin`
+    #
+    # @param [Integer] timeout Default timeout to use in requests. Optional.
+    #
+    # @return [Google::Cloud::Logging::Project]
+    #
+    # @example
+    #   require "google/cloud"
+    #
+    #   logging = Google::Cloud.logging
+    #
+    #   entries = logging.entries
+    #   entries.each do |e|
+    #     puts "[#{e.timestamp}] #{e.log_name} #{e.payload.inspect}"
+    #   end
+    #
+    def self.logging project_id = nil, credentials = nil, scope: nil, timeout: nil
+      require "google/cloud/logging"
+      Google::Cloud::Logging.new project_id: project_id,
+                                 credentials: credentials,
+                                 scope: scope, timeout: timeout
+    end
+  end
+end
+
+# Add logging to top-level configuration
+Google::Cloud.configure do |config|
+  unless config.field? :use_logging
+    config.add_field! :use_logging, nil, enum: [true, false]
+  end
+end
+
+# Set the default logging configuration
+Google::Cloud.configure.add_config! :logging do |config|
+  default_project = Google::Cloud::Config.deferred do
+    ENV["LOGGING_PROJECT"]
+  end
+  default_creds = Google::Cloud::Config.deferred do
+    Google::Cloud::Config.credentials_from_env \
+      "LOGGING_CREDENTIALS", "LOGGING_CREDENTIALS_JSON",
+      "LOGGING_KEYFILE", "LOGGING_KEYFILE_JSON"
+  end
+  default_scopes = [
+    "https://www.googleapis.com/auth/cloud-platform",
+    "https://www.googleapis.com/auth/cloud-platform.read-only",
+    "https://www.googleapis.com/auth/logging.admin",
+    "https://www.googleapis.com/auth/logging.read",
+    "https://www.googleapis.com/auth/logging.write"
+  ]
+
+  config.add_field! :project_id, default_project, match: String, allow_nil: true
+  config.add_alias! :project, :project_id
+  config.add_field! :credentials, default_creds,
+                    match:     [String, Hash, Google::Auth::Credentials],
+                    allow_nil: true
+  config.add_alias! :keyfile, :credentials
+  config.add_field! :scope, default_scopes, match: [String, Array]
+  config.add_field! :timeout, nil, match: Integer
+  config.add_field! :endpoint, "logging.googleapis.com", match: String
+  config.add_field! :log_name, nil, match: String
+  config.add_field! :log_name_map, nil, match: Hash
+  config.add_field! :labels, nil, match: Hash
+  config.add_config! :monitored_resource do |mrconfig|
+    mrconfig.add_field! :type, nil, match: String
+    mrconfig.add_field! :labels, nil, match: Hash
+  end
+  config.add_field! :set_default_logger_on_rails_init, nil, enum: [true, false]
+  config.add_field! :on_error, nil, match: Proc
+end