google-cloud-error_reporting 0.24.0 → 0.25.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: 09b2cd382fd915741f345c17f5f14d822bdfa5f7
4
- data.tar.gz: 441052f69914747bb47c7dbf085ac4f89d3520a2
3
+ metadata.gz: 2f57b6c70aad426eb8b82902378418d095dcb7df
4
+ data.tar.gz: 68844ca432aa4fea4ccf1846928ba9ede67b175c
5
5
  SHA512:
6
- metadata.gz: e02c93b66aaf87937656a5ae65f342b48cb2409863695870ba4eac0da9d315ebcff19ec6de433030c375eea4e3f2c6b47a0d6fe230c504df367a5c794c8e15cd
7
- data.tar.gz: 6a8440e222cb88dde032a3366728fb7ee73802a5ef87b41ed70ac797287049d5fdaec3d8a7ab8f38e88c5669ec074dd09fcb49809eb54ac8d64b9f4fe4191c09
6
+ metadata.gz: 1fc21b526bdb71e683f6a17d8eea04ff90f19d5f16b4344de4ff9ad1e039ad0a0db5a45a7e5b2370d6ddc36a210d682f166e120bb2e0b6367fb35a91b5c600c5
7
+ data.tar.gz: 9d7b384e32d1c9b25b61305cd00d3c594db0d625ee94eeff1791c703bf3d023569a5844c3df5eaf59809d1948b358e9323cea9e0e40fdf9f8479aee7a0a9e800
data/README.md CHANGED
@@ -1,82 +1,109 @@
1
- Stackdriver Error Reporting API for Ruby
2
- =================================================
3
-
4
- google-cloud-error_reporting uses [Google API extensions][google-gax] to provide an
5
- easy-to-use client library for the [Stackdriver Error Reporting API][] (v1beta1) defined in the [googleapis][] git repository
6
-
7
-
8
- [googleapis]: https://github.com/googleapis/googleapis/tree/master/google/devtools/clouderrorreporting/v1beta1
9
- [google-gax]: https://github.com/googleapis/gax-ruby
10
- [Stackdriver Error Reporting API]: https://developers.google.com/apis-explorer/#p/clouderrorreporting/v1beta1/
1
+ # google-cloud-error_reporting
2
+
3
+ [Stackdriver Error Reporting](https://cloud.google.com/error-reporting/) counts,
4
+ analyzes and aggregates errors raised in your running cloud services. A
5
+ centralized error management interface displays the results with sorting
6
+ and filtering capabilities. A dedicated view shows the error details: time
7
+ chart, occurrences, affected user count, first and last seen dates and a
8
+ cleaned exception stack trace. Opt-in to receive email and mobile alerts on
9
+ new errors.
10
+
11
+ - [google-cloud-error_reporting API documentation](http://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-error_reporting/latest)
12
+ - [google-cloud-error_reporting instrumentation documentation](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-error_reporting/guides/instrumentation)
13
+ - [google-cloud-error_reporting on RubyGems](https://rubygems.org/gems/google-cloud-error_reporting)
14
+ - [Stackdriver ErrorReporting documentation](https://cloud.google.com/error-reporting/docs/)
15
+
16
+ google-cloud-error_reporting provides an instrumentation API that makes it easy
17
+ to report exceptions to the Stackdriver Error Reporting service. It also
18
+ contains a full API client library for the
19
+ [Stackdriver Error Reporting API](https://developers.google.com/apis-explorer/#p/clouderrorreporting/v1beta1/)
20
+ (v1beta1).
21
+
22
+ ## Quick Start
23
+ ```sh
24
+ $ gem install google-cloud-error_reporting
25
+ ```
11
26
 
12
- Getting started
13
- ---------------
27
+ ## Authentication
14
28
 
15
- google-cloud-error_reporting will allow you to connect to the [Stackdriver Error Reporting API][] and access all its methods.
29
+ The Instrumentation client and API use Service Account credentials to connect
30
+ to Google Cloud services. When running on Google Cloud Platform environments,
31
+ the credentials will be discovered automatically. When running on other
32
+ environments the Service Account credentials can be specified by providing the
33
+ path to the JSON file, or the JSON itself, in environment variables or
34
+ configuration code.
16
35
 
17
- In order to achieve so you need to set up authentication as well as install the library locally.
36
+ Instructions and configuration options are covered in the
37
+ [Authentication Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-error_reporting/guides/authentication).
18
38
 
39
+ ## Instrumentation Example
40
+ ```ruby
41
+ require "google/cloud/error_reporting"
42
+
43
+ # Configure Stackdriver ErrorReporting instrumentation
44
+ Google::Cloud::ErrorReporting.configure do |config|
45
+ config.project_id = "my-project"
46
+ config.keyfile = "/path/to/keyfile.json"
47
+ end
48
+
49
+ # Insert a Rack Middleware to report unhanded exceptions
50
+ use Google::Cloud::ErrorReporting::Middleware
51
+
52
+ # Or explicitly submit exceptions
53
+ begin
54
+ fail "Boom!"
55
+ rescue => exception
56
+ Google::Cloud::ErrorReporting.report exception
57
+ end
58
+ ```
19
59
 
20
- Setup Authentication
21
- --------------------
60
+ ## Rails and Rack Integration
22
61
 
23
- To authenticate all your API calls, first install and setup the [Google Cloud SDK][].
24
- Once done, you can then run the following command in your terminal:
62
+ This library also provides a built-in Railtie for Ruby on Rails integration. To
63
+ do this, simply add this line to config/application.rb:
64
+ ```ruby
65
+ require "google/cloud/error_reporting/rails"
66
+ ```
25
67
 
26
- $ gcloud beta auth application-default login
68
+ Alternatively, check out the [stackdriver](../stackdriver) gem, which includes
69
+ this library and enables the Railtie by default.
27
70
 
28
- or
71
+ For Rack integration and more examples, see the
72
+ [Instrumentation Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-error_reporting/guides/instrumentation).
29
73
 
30
- $ gcloud auth login
74
+ ## Supported Ruby Versions
31
75
 
32
- Please see [gcloud beta auth application-default login][] document for the difference between these commands.
76
+ This library is supported on Ruby 2.0+.
33
77
 
34
- [Google Cloud SDK]: https://cloud.google.com/sdk/
35
- [gcloud beta auth application-default login]: https://cloud.google.com/sdk/gcloud/reference/beta/auth/application-default/login
78
+ ## Versioning
36
79
 
80
+ This library follows [Semantic Versioning](http://semver.org/).
37
81
 
38
- Installation
39
- -------------------
82
+ It is currently in major version zero (0.y.z), which means that anything may
83
+ change at any time and the public API should not be considered stable.
40
84
 
41
- Install this library using gem:
85
+ ## Contributing
42
86
 
43
- $ [sudo] gem install google-cloud-error_reporting
44
-
87
+ Contributions to this library are always welcome and highly encouraged.
45
88
 
46
- Rails Integration
47
- ---------------
89
+ See the
90
+ [Contributing Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/contributing)
91
+ for more information on how to get started.
48
92
 
49
- This library also provides a built in Railtie for Ruby on Rails integration. To do this, simply add this line to config/application.rb:
50
- ```ruby
51
- require "google/cloud/error_reporting/rails"
52
- ```
53
- Then the library can be configured through this set of Rails parameters in config/environments/*.rb:
54
- ```ruby
55
- # Sharing authentication parameters
56
- config.google_cloud.project_id = "gcp-project-id"
57
- config.google_cloud.keyfile = "/path/to/gcp/secret.json"
58
- # Or more specificly for ErrorReporting
59
- config.google_cloud.error_reporting.project_id = "gcp-project-id"
60
- config.google_cloud.error_reporting.keyfile = "/path/to/gcp/sercret.json"
61
-
62
- # Explicitly enable or disable ErrorReporting
63
- config.google_cloud.use_error_reporting = true
64
-
65
- # Set Stackdriver Error Reporting service context
66
- config.google_cloud.error_reporting.service_name = "my-app-name"
67
- config.google_cloud.error_reporting.service_version = "my-app-version"
68
- ```
93
+ Please note that this project is released with a Contributor Code of Conduct. By
94
+ participating in this project you agree to abide by its terms. See
95
+ [Code of Conduct](../CODE_OF_CONDUCT.md) for more information.
69
96
 
70
- Alternatively, check out [stackdriver](../stackdriver) gem, which includes this Railtie by default.
97
+ ## License
71
98
 
72
- Rack Integration
73
- ---------------
99
+ This library is licensed under Apache 2.0. Full license text is available in
100
+ [LICENSE](LICENSE).
74
101
 
75
- Other Rack base framework can also directly leverage the built-in Middleware.
76
- ```ruby
77
- require "google/cloud/error_reporting/v1beta1"
102
+ ## Support
78
103
 
79
- use Google::Cloud::ErrorReporting::Middleware
80
- ```
104
+ Please
105
+ [report bugs at the project on Github](https://github.com/GoogleCloudPlatform/google-cloud-ruby/issues).
106
+ Don't hesitate to
107
+ [ask questions](http://stackoverflow.com/questions/tagged/google-cloud-platform+ruby)
108
+ about the client or APIs on [StackOverflow](http://stackoverflow.com).
81
109
 
82
- At this point you are all set to continue.
@@ -1,4 +1,4 @@
1
- # Copyright 2016 Google Inc. All rights reserved.
1
+ # Copyright 2017 Google Inc. All rights reserved.
2
2
  #
3
3
  # Licensed under the Apache License, Version 2.0 (the "License");
4
4
  # you may not use this file except in compliance with the License.
@@ -13,12 +13,100 @@
13
13
  # limitations under the License.
14
14
 
15
15
  ##
16
- # This file is here to be autorequired by bundler, so that the .logging and
17
- # #logging methods can be available, but the library and all dependencies won't
18
- # be loaded until required and used.
16
+ # This file is here to be autorequired by bundler
19
17
 
20
18
 
21
19
  gem "google-cloud-core"
22
20
  require "google/cloud"
23
21
 
24
- # There is no Google::Cloud integration to add.
22
+ module Google
23
+ module Cloud
24
+ ##
25
+ # Create a new object for connecting to the Stackdriver Error Reporting
26
+ # service. Each call creates a new connection.
27
+ #
28
+ # For more information on connecting to Google Cloud see the [Authentication
29
+ # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication)
30
+ #
31
+ # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling the
32
+ # set of resources and operations that the connection can access. See
33
+ # [Using OAuth 2.0 to Access Google
34
+ # APIs](https://developers.google.com/identity/protocols/OAuth2).
35
+ #
36
+ # The default scope is:
37
+ #
38
+ # * `https://www.googleapis.com/auth/cloud-platform`
39
+ # @param [Integer] timeout Default timeout to use in requests. Optional.
40
+ # @param [Hash] client_config A hash of values to override the default
41
+ # behavior of the API client. Optional.
42
+ #
43
+ # @return [Google::Cloud::ErrorReporting::Project]
44
+ #
45
+ # @example
46
+ # require "google/cloud/error_reporting"
47
+ #
48
+ # gcloud = Google::Cloud.new "GCP_Project_ID",
49
+ # "/path/to/gcp/secretkey.json"
50
+ # error_reporting = gcloud.error_reporting
51
+ #
52
+ # error_event = error_reporting.error_event "Error with Backtrace",
53
+ # timestamp: Time.now,
54
+ # service_name: "my_app_name",
55
+ # service_version: "v8"
56
+ # error_reporting.report error_event
57
+ #
58
+ def error_reporting scope: nil, timeout: nil, client_config: nil
59
+ Google::Cloud.error_reporting @project, @keyfile,
60
+ scope: scope,
61
+ timeout: (timeout || @timeout),
62
+ client_config: client_config
63
+ end
64
+
65
+
66
+ ##
67
+ # Create a new object for connecting to the Stackdriver Error Reporting
68
+ # service. Each call creates a new connection.
69
+ #
70
+ # For more information on connecting to Google Cloud see the [Authentication
71
+ # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication)
72
+ #
73
+ # @param [String] project Google Cloud Platform project identifier for the
74
+ # Stackdriver Error Reporting service you are connecting to. Use
75
+ # Project.default_project if not provided.
76
+ # @param [String, Hash] keyfile Keyfile downloaded from Google Cloud. If
77
+ # file path the file must be readable.
78
+ # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling the
79
+ # set of resources and operations that the connection can access. See
80
+ # [Using OAuth 2.0 to Access Google
81
+ # APIs](https://developers.google.com/identity/protocols/OAuth2).
82
+ #
83
+ # The default scope is:
84
+ #
85
+ # * `https://www.googleapis.com/auth/cloud-platform`
86
+ # @param [Integer] timeout Default timeout to use in requests. Optional.
87
+ # @param [Hash] client_config A hash of values to override the default
88
+ # behavior of the API client. Optional.
89
+ #
90
+ # @return [Google::Cloud::ErrorReporting::Project]
91
+ #
92
+ # @example
93
+ # require "google/cloud/error_reporting"
94
+ #
95
+ # gcloud = Google::Cloud.error_reporting "GCP_Project_ID",
96
+ # "/path/to/gcp/secretkey.json"
97
+ #
98
+ # error_event = error_reporting.error_event "Error with Backtrace",
99
+ # timestamp: Time.now,
100
+ # service_name: "my_app_name",
101
+ # service_version: "v8"
102
+ # error_reporting.report error_event
103
+ #
104
+ def self.error_reporting project = nil, keyfile = nil, scope: nil,
105
+ timeout: nil, client_config: nil
106
+ require "google/cloud/error_reporting"
107
+ Google::Cloud::ErrorReporting.new project: project, keyfile: keyfile,
108
+ scope: scope, timeout: timeout,
109
+ client_config: client_config
110
+ end
111
+ end
112
+ end
@@ -0,0 +1,238 @@
1
+ # Copyright 2017 Google Inc. All rights reserved.
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
+ # http://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-error_reporting"
17
+ require "google/cloud/error_reporting/project"
18
+ require "google/cloud/error_reporting/middleware"
19
+ require "stackdriver/core"
20
+
21
+ module Google
22
+ module Cloud
23
+ ##
24
+ # # ErrorReporting
25
+ #
26
+ # Stackdriver Error Reporting counts, analyzes and aggregates the crashes in
27
+ # your running cloud services. The Stackdriver Error Reporting
28
+ # Instrumentation client provides
29
+ # [a simple way to report errors](#how-to-report-errors) from your
30
+ # application.
31
+ #
32
+ # For general information about Stackdriver Error Reporting, read
33
+ # [Stackdriver Error Reporting
34
+ # Documentation](https://cloud.google.com/error-reporting/docs/).
35
+ #
36
+ # The goal of google-cloud-ruby is to provide an API that is comfortable to
37
+ # Rubyists. Authentication is handled by the client. You can provide the
38
+ # project and credential information to connect to the Stackdriver Error
39
+ # Reporting service, or if you are running on Google Cloud Platform this
40
+ # configuration is taken care of for you. You can read more about the
41
+ # options for connecting in the [Authentication
42
+ # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication).
43
+ #
44
+ # ## How to report errors
45
+ #
46
+ # You can easily report exceptions from your applications to Stackdriver
47
+ # Error Reporting service:
48
+ #
49
+ # ```ruby
50
+ # require "google/cloud/error_reporting"
51
+ #
52
+ # # Configure Stackdriver ErrorReporting instrumentation
53
+ # Google::Cloud::ErrorReporting.configure do |config|
54
+ # config.project_id = "my-project"
55
+ # config.keyfile = "/path/to/keyfile.json"
56
+ # end
57
+ #
58
+ # # Insert a Rack Middleware to report unhanded exceptions
59
+ # use Google::Cloud::ErrorReporting::Middleware
60
+ #
61
+ # # Or explicitly submit exceptions
62
+ # begin
63
+ # fail "Boom!"
64
+ # rescue => exception
65
+ # Google::Cloud::ErrorReporting.report exception
66
+ # end
67
+ # ```
68
+ #
69
+ # See the [Instrumentation
70
+ # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-error_reporting/guides/instrumentation)
71
+ # for more examples.
72
+ #
73
+ module ErrorReporting
74
+ # Initialize :error_reporting as a nested Configuration under
75
+ # Google::Cloud if haven't already
76
+ unless Google::Cloud.configure.option? :error_reporting
77
+ Google::Cloud.configure.add_options :error_reporting
78
+ end
79
+
80
+ ##
81
+ # @private The default Google::Cloud::ErrorReporting::Project client used
82
+ # for the Google::Cloud::ErrorReporting.report API.
83
+ @@default_client = nil
84
+
85
+ ##
86
+ # Creates a new object for connecting to the Stackdriver Error Reporting
87
+ # service. Each call creates a new connection.
88
+ #
89
+ # For more information on connecting to Google Cloud see the
90
+ # [Authentication
91
+ # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication).
92
+ #
93
+ # @param [String] project Project identifier for the Stackdriver Error
94
+ # Reporting service.
95
+ # @param [String, Hash] keyfile Keyfile downloaded from Google Cloud. If
96
+ # file path the file must be readable.
97
+ # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling
98
+ # the set of resources and operations that the connection can access.
99
+ # See [Using OAuth 2.0 to Access Google
100
+ # APIs](https://developers.google.com/identity/protocols/OAuth2).
101
+ #
102
+ # The default scope is:
103
+ #
104
+ # * `https://www.googleapis.com/auth/cloud-platform`
105
+ #
106
+ # @param [Integer] timeout Default timeout to use in requests. Optional.
107
+ # @param [Hash] client_config A hash of values to override the default
108
+ # behavior of the API client. Optional.
109
+ #
110
+ # @return [Google::Cloud::ErrorReporting::Project]
111
+ #
112
+ # @example
113
+ # require "google/cloud/error_reporting"
114
+ #
115
+ # error_reporting = Google::Cloud::ErrorReporting.new
116
+ # # ...
117
+ #
118
+ def self.new project: nil, keyfile: nil, scope: nil, timeout: nil,
119
+ client_config: nil
120
+ project ||= Google::Cloud::ErrorReporting::Project.default_project
121
+ project = project.to_s
122
+ fail ArgumentError, "project is missing" if project.empty?
123
+
124
+ credentials =
125
+ Google::Cloud::ErrorReporting::Credentials.credentials_with_scope(
126
+ keyfile, scope)
127
+
128
+ Google::Cloud::ErrorReporting::Project.new(
129
+ Google::Cloud::ErrorReporting::Service.new(
130
+ project, credentials, timeout: timeout, client_config: client_config
131
+ )
132
+ )
133
+ end
134
+
135
+ ##
136
+ # Configure the default {Google::Cloud::ErrorReporting::Project}
137
+ # client, allows the {.report} public method to reuse these
138
+ # configured parameters.
139
+ #
140
+ # See the [Configuration
141
+ # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/stackdriver/guides/instrumentation_configuration)
142
+ # for full configuration parameters.
143
+ #
144
+ # @example
145
+ # # in app.rb
146
+ # require "google/cloud/error_reporting"
147
+ #
148
+ # Google::Cloud::ErrorReporting.configure do |config|
149
+ # config.project_id = "my-project-id"
150
+ # config.keyfile = "/path/to/keyfile.json"
151
+ # config.service_name = "my-service"
152
+ # config.service_version = "v8"
153
+ # end
154
+ #
155
+ # begin
156
+ # fail "boom"
157
+ # rescue => exception
158
+ # # Report exception using configuration parameters provided above
159
+ # Google::Cloud::ErrorReporting.report exception
160
+ # end
161
+ #
162
+ # @return [Stackdriver::Core::Configuration] The configuration object
163
+ # the Google::Cloud::ErrorReporting module uses.
164
+ #
165
+ def self.configure
166
+ yield Google::Cloud.configure.error_reporting if block_given?
167
+
168
+ Google::Cloud.configure.error_reporting
169
+ end
170
+
171
+ ##
172
+ # Provides an easy-to-use interface to Report a Ruby exception object to
173
+ # Stackdriver ErrorReporting service. This method helps users to
174
+ # transform the Ruby exception into an Stackdriver ErrorReporting
175
+ # ErrorEvent gRPC structure, so users don't need to. This should be the
176
+ # prefered method to use when users wish to report captured exception in
177
+ # applications.
178
+ #
179
+ # This public method creates a default Stackdriver ErrorReporting client
180
+ # and reuse that between calls. The default client is initialized with
181
+ # parameters defined in {.configure}.
182
+ #
183
+ # The error event can be customized before reporting. See the example
184
+ # below and {Google::Cloud::ErrorReporting::ErrorEvent} class for avaiable
185
+ # error event fields.
186
+ #
187
+ # @example Basic usage
188
+ # # in app.rb
189
+ # require "google/cloud/error_reporting"
190
+ #
191
+ # begin
192
+ # fail "boom"
193
+ # rescue => exception
194
+ # # Report exception using configuration parameters provided above
195
+ # Google::Cloud::ErrorReporting.report exception
196
+ # end
197
+ #
198
+ # @example The error event can be customized if needed
199
+ # require "google/cloud/error_reporting"
200
+ #
201
+ # begin
202
+ # fail "boom"
203
+ # rescue => exception
204
+ # Google::Cloud::ErrorReporting.report exception do |error_event|
205
+ # error_event.user = "johndoh@example.com"
206
+ # error_event.http_status = "502"
207
+ # end
208
+ # end
209
+ #
210
+ # @param [Exception] exception The captured Ruby Exception object
211
+ # @param [String] service_name An identifier for running service.
212
+ # Optional.
213
+ # @param [String] service_version A version identifier for running
214
+ # service.
215
+ #
216
+ def self.report exception, service_name: nil, service_version: nil, &block
217
+ return if Google::Cloud.configure.use_error_reporting == false
218
+
219
+ unless @@default_client
220
+ project_id = configure.project_id ||
221
+ Google::Cloud.configure.project_id
222
+ keyfile = configure.keyfile ||
223
+ Google::Cloud.configure.keyfile
224
+
225
+ @@default_client = new project: project_id, keyfile: keyfile
226
+ end
227
+
228
+ service_name ||= configure.service_name
229
+ service_version ||= configure.service_version
230
+
231
+ @@default_client.report_exception exception,
232
+ service_name: service_name,
233
+ service_version: service_version,
234
+ &block
235
+ end
236
+ end
237
+ end
238
+ end