google-cloud-error_reporting 0.30.3 → 0.30.4
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/AUTHENTICATION.md +180 -0
- data/CHANGELOG.md +102 -0
- data/CODE_OF_CONDUCT.md +40 -0
- data/CONTRIBUTING.md +189 -0
- data/INSTRUMENTATION.md +91 -0
- data/LOGGING.md +32 -0
- data/OVERVIEW.md +48 -0
- data/TROUBLESHOOTING.md +37 -0
- data/lib/google/cloud/error_reporting/version.rb +1 -1
- metadata +10 -3
- data/README.md +0 -257
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: f6b3875ef96a2a0861e6398e925cdbfcc86b945c29274c28a08f0a480021c468
|
|
4
|
+
data.tar.gz: b0b8f6a7bb99ea7a99a9e9fbe5c2882007fa6e5142251daa22a45314096dccda
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: fac501a993ac6f6bc474b0fcb9210ada3386bfd6281b003a0e334276f15e2ee8d64a4ff73fedd866ed23022a97f8401278a69f3c927e7448647f8ba8fe223431
|
|
7
|
+
data.tar.gz: 1a5136a8d82ea9d1e3733cbfd180662d9d6b4d1bb82404da3bc46b5edcdccb28f760b0c3be9b70c16ba5c99931b31c427fafc3ef5d3938462c86f80e2ab68fc7
|
data/AUTHENTICATION.md
ADDED
|
@@ -0,0 +1,180 @@
|
|
|
1
|
+
Error Reporting# Authentication
|
|
2
|
+
|
|
3
|
+
In general, the google-cloud-error_reporting library uses [Service
|
|
4
|
+
Account](https://cloud.google.com/iam/docs/creating-managing-service-accounts)
|
|
5
|
+
credentials to connect to Google Cloud services. When running on Compute Engine
|
|
6
|
+
the credentials will be discovered automatically. When running on other
|
|
7
|
+
environments, the Service Account credentials can be specified by providing the
|
|
8
|
+
path to the [JSON
|
|
9
|
+
keyfile](https://cloud.google.com/iam/docs/managing-service-account-keys) for
|
|
10
|
+
the account (or the JSON itself) in environment variables. Additionally, Cloud
|
|
11
|
+
SDK credentials can also be discovered automatically, but this is only
|
|
12
|
+
recommended during development.
|
|
13
|
+
|
|
14
|
+
## Project and Credential Lookup
|
|
15
|
+
|
|
16
|
+
The google-cloud-error_reporting library aims to make authentication as simple
|
|
17
|
+
as possible, and provides several mechanisms to configure your system without
|
|
18
|
+
providing **Project ID** and **Service Account Credentials** directly in code.
|
|
19
|
+
|
|
20
|
+
**Project ID** is discovered in the following order:
|
|
21
|
+
|
|
22
|
+
1. Specify project ID in method arguments
|
|
23
|
+
2. Specify project ID in configuration
|
|
24
|
+
3. Discover project ID in environment variables
|
|
25
|
+
4. Discover GCE project ID
|
|
26
|
+
|
|
27
|
+
**Credentials** are discovered in the following order:
|
|
28
|
+
|
|
29
|
+
1. Specify credentials in method arguments
|
|
30
|
+
2. Specify credentials in configuration
|
|
31
|
+
3. Discover credentials path in environment variables
|
|
32
|
+
4. Discover credentials JSON in environment variables
|
|
33
|
+
5. Discover credentials file in the Cloud SDK's path
|
|
34
|
+
6. Discover GCE credentials
|
|
35
|
+
|
|
36
|
+
### Google Cloud Platform environments
|
|
37
|
+
|
|
38
|
+
While running on Google Cloud Platform environments such as Google Compute
|
|
39
|
+
Engine, Google App Engine and Google Kubernetes Engine, no extra work is needed.
|
|
40
|
+
The **Project ID** and **Credentials** and are discovered automatically. Code
|
|
41
|
+
should be written as if already authenticated. Just be sure when you [set up the
|
|
42
|
+
GCE instance][gce-how-to], you add the correct scopes for the APIs you want to
|
|
43
|
+
access. For example:
|
|
44
|
+
|
|
45
|
+
* **All APIs**
|
|
46
|
+
* `https://www.googleapis.com/auth/cloud-platform`
|
|
47
|
+
* `https://www.googleapis.com/auth/cloud-platform.read-only`
|
|
48
|
+
* **BigQuery**
|
|
49
|
+
* `https://www.googleapis.com/auth/bigquery`
|
|
50
|
+
* `https://www.googleapis.com/auth/bigquery.insertdata`
|
|
51
|
+
* **Compute Engine**
|
|
52
|
+
* `https://www.googleapis.com/auth/compute`
|
|
53
|
+
* **Datastore**
|
|
54
|
+
* `https://www.googleapis.com/auth/datastore`
|
|
55
|
+
* `https://www.googleapis.com/auth/userinfo.email`
|
|
56
|
+
* **DNS**
|
|
57
|
+
* `https://www.googleapis.com/auth/ndev.clouddns.readwrite`
|
|
58
|
+
* **Pub/Sub**
|
|
59
|
+
* `https://www.googleapis.com/auth/pubsub`
|
|
60
|
+
* **Storage**
|
|
61
|
+
* `https://www.googleapis.com/auth/devstorage.full_control`
|
|
62
|
+
* `https://www.googleapis.com/auth/devstorage.read_only`
|
|
63
|
+
* `https://www.googleapis.com/auth/devstorage.read_write`
|
|
64
|
+
|
|
65
|
+
### Environment Variables
|
|
66
|
+
|
|
67
|
+
The **Project ID** and **Credentials JSON** can be placed in environment
|
|
68
|
+
variables instead of declaring them directly in code. Each service has its own
|
|
69
|
+
environment variable, allowing for different service accounts to be used for
|
|
70
|
+
different services. (See the READMEs for the individual service gems for
|
|
71
|
+
details.) The path to the **Credentials JSON** file can be stored in the
|
|
72
|
+
environment variable, or the **Credentials JSON** itself can be stored for
|
|
73
|
+
environments such as Docker containers where writing files is difficult or not
|
|
74
|
+
encouraged.
|
|
75
|
+
|
|
76
|
+
The environment variables that Error Reporting checks for project ID are:
|
|
77
|
+
|
|
78
|
+
1. `ERROR_REPORTING_PROJECT`
|
|
79
|
+
2. `GOOGLE_CLOUD_PROJECT`
|
|
80
|
+
|
|
81
|
+
The environment variables that Error Reporting checks for credentials are
|
|
82
|
+
configured on {Google::Cloud::ErrorReporting::V1beta1::Credentials}:
|
|
83
|
+
|
|
84
|
+
1. `ERROR_REPORTING_CREDENTIALS` - Path to JSON file, or JSON contents
|
|
85
|
+
2. `ERROR_REPORTING_KEYFILE` - Path to JSON file, or JSON contents
|
|
86
|
+
3. `GOOGLE_CLOUD_CREDENTIALS` - Path to JSON file, or JSON contents
|
|
87
|
+
4. `GOOGLE_CLOUD_KEYFILE` - Path to JSON file, or JSON contents
|
|
88
|
+
5. `GOOGLE_APPLICATION_CREDENTIALS` - Path to JSON file
|
|
89
|
+
|
|
90
|
+
```ruby
|
|
91
|
+
require "google/cloud/error_reporting"
|
|
92
|
+
|
|
93
|
+
ENV["ERROR_REPORTING_PROJECT"] = "my-project-id"
|
|
94
|
+
ENV["ERROR_REPORTING_CREDENTIALS"] = "path/to/keyfile.json"
|
|
95
|
+
|
|
96
|
+
error_reporting = Google::Cloud::ErrorReporting.new
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
### Configuration
|
|
100
|
+
|
|
101
|
+
The **Project ID** and **Credentials JSON** can be configured instead of placing
|
|
102
|
+
them in environment variables or providing them as arguments.
|
|
103
|
+
|
|
104
|
+
```ruby
|
|
105
|
+
require "google/cloud/error_reporting"
|
|
106
|
+
|
|
107
|
+
Google::Cloud::ErrorReporting.configure do |config|
|
|
108
|
+
config.project_id = "my-project-id"
|
|
109
|
+
config.credentials = "path/to/keyfile.json"
|
|
110
|
+
end
|
|
111
|
+
|
|
112
|
+
error_reporting = Google::Cloud::ErrorReporting.new
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
### Cloud SDK
|
|
116
|
+
|
|
117
|
+
This option allows for an easy way to authenticate during development. If
|
|
118
|
+
credentials are not provided in code or in environment variables, then Cloud SDK
|
|
119
|
+
credentials are discovered.
|
|
120
|
+
|
|
121
|
+
To configure your system for this, simply:
|
|
122
|
+
|
|
123
|
+
1. [Download and install the Cloud SDK](https://cloud.google.com/sdk)
|
|
124
|
+
2. Authenticate using OAuth 2.0 `$ gcloud auth login`
|
|
125
|
+
3. Write code as if already authenticated.
|
|
126
|
+
|
|
127
|
+
**NOTE:** This is _not_ recommended for running in production. The Cloud SDK
|
|
128
|
+
*should* only be used during development.
|
|
129
|
+
|
|
130
|
+
[gce-how-to]: https://cloud.google.com/compute/docs/authentication#using
|
|
131
|
+
[dev-console]: https://console.cloud.google.com/project
|
|
132
|
+
|
|
133
|
+
[enable-apis]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/enable-apis.png
|
|
134
|
+
|
|
135
|
+
[create-new-service-account]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/create-new-service-account.png
|
|
136
|
+
[create-new-service-account-existing-keys]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/create-new-service-account-existing-keys.png
|
|
137
|
+
[reuse-service-account]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/reuse-service-account.png
|
|
138
|
+
|
|
139
|
+
## Creating a Service Account
|
|
140
|
+
|
|
141
|
+
Google Cloud requires a **Project ID** and **Service Account Credentials** to
|
|
142
|
+
connect to the APIs. You will use the **Project ID** and **JSON key file** to
|
|
143
|
+
connect to most services with google-cloud-error_reporting.
|
|
144
|
+
|
|
145
|
+
If you are not running this client on Google Compute Engine, you need a Google
|
|
146
|
+
Developers service account.
|
|
147
|
+
|
|
148
|
+
1. Visit the [Google Developers Console][dev-console].
|
|
149
|
+
1. Create a new project or click on an existing project.
|
|
150
|
+
1. Activate the slide-out navigation tray and select **API Manager**. From
|
|
151
|
+
here, you will enable the APIs that your application requires.
|
|
152
|
+
|
|
153
|
+
![Enable the APIs that your application requires][enable-apis]
|
|
154
|
+
|
|
155
|
+
*Note: You may need to enable billing in order to use these services.*
|
|
156
|
+
|
|
157
|
+
1. Select **Credentials** from the side navigation.
|
|
158
|
+
|
|
159
|
+
You should see a screen like one of the following.
|
|
160
|
+
|
|
161
|
+
![Create a new service account][create-new-service-account]
|
|
162
|
+
|
|
163
|
+
![Create a new service account With Existing Keys][create-new-service-account-existing-keys]
|
|
164
|
+
|
|
165
|
+
Find the "Add credentials" drop down and select "Service account" to be
|
|
166
|
+
guided through downloading a new JSON key file.
|
|
167
|
+
|
|
168
|
+
If you want to re-use an existing service account, you can easily generate a
|
|
169
|
+
new key file. Just select the account you wish to re-use, and click "Generate
|
|
170
|
+
new JSON key":
|
|
171
|
+
|
|
172
|
+
![Re-use an existing service account][reuse-service-account]
|
|
173
|
+
|
|
174
|
+
The key file you download will be used by this library to authenticate API
|
|
175
|
+
requests and should be stored in a secure location.
|
|
176
|
+
|
|
177
|
+
## Troubleshooting
|
|
178
|
+
|
|
179
|
+
If you're having trouble authenticating you can ask for help by following the
|
|
180
|
+
{file:TROUBLESHOOTING.md Troubleshooting Guide}.
|
data/CHANGELOG.md
ADDED
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
# Release History
|
|
2
|
+
|
|
3
|
+
### 0.30.4 / 2018-09-12
|
|
4
|
+
|
|
5
|
+
* Add missing documentation files to package.
|
|
6
|
+
|
|
7
|
+
### 0.30.3 / 2018-09-10
|
|
8
|
+
|
|
9
|
+
* Update documentation.
|
|
10
|
+
|
|
11
|
+
### 0.30.2 / 2018-08-21
|
|
12
|
+
|
|
13
|
+
* Update documentation.
|
|
14
|
+
|
|
15
|
+
### 0.30.1 / 2018-07-05
|
|
16
|
+
|
|
17
|
+
* Fix undefined method for nil error when error object has empty backtrace.
|
|
18
|
+
* Fix issue when disabling Stackdriver components with Rails.env.production.
|
|
19
|
+
* Capture env["rack.exception"] errors from Rack env.
|
|
20
|
+
* Add documentation for enabling gRPC logging.
|
|
21
|
+
|
|
22
|
+
### 0.30.0 / 2018-02-27
|
|
23
|
+
|
|
24
|
+
* Use Google Cloud Shared Configuration.
|
|
25
|
+
|
|
26
|
+
### 0.29.0 / 2017-12-19
|
|
27
|
+
|
|
28
|
+
* Update google-gax dependency to 1.0.
|
|
29
|
+
|
|
30
|
+
### 0.28.1 / 2017-11-15
|
|
31
|
+
|
|
32
|
+
* Fix credentials verification bug in Railtie.
|
|
33
|
+
|
|
34
|
+
### 0.28.0 / 2017-11-14
|
|
35
|
+
|
|
36
|
+
* Add `Google::Cloud::ErrorReporting::Credentials` class.
|
|
37
|
+
* Rename constructor arguments to `project_id` and `credentials`.
|
|
38
|
+
(The previous arguments `project` and `keyfile` are still supported.)
|
|
39
|
+
* Document `Google::Auth::Credentials` as `credentials` value.
|
|
40
|
+
* Updated `google-gax` (`grpc`, `google-protobuf`), `googleauth` dependencies.
|
|
41
|
+
|
|
42
|
+
### 0.27.0 / 2017-09-08
|
|
43
|
+
|
|
44
|
+
* Rename `module_name` and `module_version` parameters to `service_name` and `service_version` respectively.
|
|
45
|
+
* Print captured exception from asynchronous worker thread.
|
|
46
|
+
|
|
47
|
+
### 0.26.1 / 2017-07-11
|
|
48
|
+
|
|
49
|
+
* stackdriver-core 1.2.0 release
|
|
50
|
+
|
|
51
|
+
### 0.26.0 / 2017-07-11
|
|
52
|
+
|
|
53
|
+
* Update `Google::Cloud::ErrorReporting::Middleware` and `Google::Cloud::ErrorReporting::Railtie` to submit error events asynchronously by default.
|
|
54
|
+
* Update GAPIC configuration to exclude `UNAVAILABLE` errors from automatic retry.
|
|
55
|
+
|
|
56
|
+
### 0.25.0 / 2017-05-25
|
|
57
|
+
|
|
58
|
+
* New Error Reporting instrumentation client.
|
|
59
|
+
* Introduce simple `Google::Cloud::ErrorReporting.report` interface to easily report Ruby exception.
|
|
60
|
+
* New `Google::Cloud::ErrorReporting.configure` instrumentation configuration interface.
|
|
61
|
+
* `Google::Cloud::ErrorReporting::Middleware` can now be used without required parameters.
|
|
62
|
+
|
|
63
|
+
### 0.24.0 / 2017-03-31
|
|
64
|
+
|
|
65
|
+
* Automatic retry on `UNAVAILABLE` errors
|
|
66
|
+
|
|
67
|
+
### 0.23.3 / 2017-03-03
|
|
68
|
+
|
|
69
|
+
* Update GRPC header value sent to the Error Reporting API.
|
|
70
|
+
|
|
71
|
+
### 0.23.2 / 2017-03-01
|
|
72
|
+
|
|
73
|
+
* Update GRPC header value sent to the Error Reporting API.
|
|
74
|
+
|
|
75
|
+
### 0.23.1 / 2017-02-23
|
|
76
|
+
|
|
77
|
+
* Add middleware require to rails module (premist)
|
|
78
|
+
|
|
79
|
+
### 0.23.0 / 2017-02-21
|
|
80
|
+
|
|
81
|
+
* Fix GRPC retry bug
|
|
82
|
+
* The client_config data structure has replaced retry_codes/retry_codes_def with retry_codes
|
|
83
|
+
* Update GRPC/Protobuf/GAX dependencies
|
|
84
|
+
|
|
85
|
+
### 0.22.0 / 2017-01-27
|
|
86
|
+
|
|
87
|
+
* Update Error Reporting requires. For Rack integration, users now need to use
|
|
88
|
+
`require "google/cloud/error_reporting/middleware"` rather than
|
|
89
|
+
`require "google/cloud/error_reporting/v1beta1"`.
|
|
90
|
+
* Change class names in low-level API (GAPIC)
|
|
91
|
+
|
|
92
|
+
### 0.21.2 / 2016-11-03
|
|
93
|
+
|
|
94
|
+
* Fixed instrumentation integration with Ruby on Rails
|
|
95
|
+
|
|
96
|
+
### 0.21.1 / 2016-11-01
|
|
97
|
+
|
|
98
|
+
* Fixed instrumentation integration with non-Rails Rack frameworks
|
|
99
|
+
|
|
100
|
+
### 0.21.0 / 2016-10-20
|
|
101
|
+
|
|
102
|
+
* First release
|
data/CODE_OF_CONDUCT.md
ADDED
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# Contributor Code of Conduct
|
|
2
|
+
|
|
3
|
+
As contributors and maintainers of this project, and in the interest of
|
|
4
|
+
fostering an open and welcoming community, we pledge to respect all people who
|
|
5
|
+
contribute through reporting issues, posting feature requests, updating
|
|
6
|
+
documentation, submitting pull requests or patches, and other activities.
|
|
7
|
+
|
|
8
|
+
We are committed to making participation in this project a harassment-free
|
|
9
|
+
experience for everyone, regardless of level of experience, gender, gender
|
|
10
|
+
identity and expression, sexual orientation, disability, personal appearance,
|
|
11
|
+
body size, race, ethnicity, age, religion, or nationality.
|
|
12
|
+
|
|
13
|
+
Examples of unacceptable behavior by participants include:
|
|
14
|
+
|
|
15
|
+
* The use of sexualized language or imagery
|
|
16
|
+
* Personal attacks
|
|
17
|
+
* Trolling or insulting/derogatory comments
|
|
18
|
+
* Public or private harassment
|
|
19
|
+
* Publishing other's private information, such as physical or electronic
|
|
20
|
+
addresses, without explicit permission
|
|
21
|
+
* Other unethical or unprofessional conduct.
|
|
22
|
+
|
|
23
|
+
Project maintainers have the right and responsibility to remove, edit, or reject
|
|
24
|
+
comments, commits, code, wiki edits, issues, and other contributions that are
|
|
25
|
+
not aligned to this Code of Conduct. By adopting this Code of Conduct, project
|
|
26
|
+
maintainers commit themselves to fairly and consistently applying these
|
|
27
|
+
principles to every aspect of managing this project. Project maintainers who do
|
|
28
|
+
not follow or enforce the Code of Conduct may be permanently removed from the
|
|
29
|
+
project team.
|
|
30
|
+
|
|
31
|
+
This code of conduct applies both within project spaces and in public spaces
|
|
32
|
+
when an individual is representing the project or its community.
|
|
33
|
+
|
|
34
|
+
Instances of abusive, harassing, or otherwise unacceptable behavior may be
|
|
35
|
+
reported by opening an issue or contacting one or more of the project
|
|
36
|
+
maintainers.
|
|
37
|
+
|
|
38
|
+
This Code of Conduct is adapted from the [Contributor
|
|
39
|
+
Covenant](http://contributor-covenant.org), version 1.2.0, available at
|
|
40
|
+
[http://contributor-covenant.org/version/1/2/0/](http://contributor-covenant.org/version/1/2/0/)
|
data/CONTRIBUTING.md
ADDED
|
@@ -0,0 +1,189 @@
|
|
|
1
|
+
# Contributing to Google Cloud Error Reporting
|
|
2
|
+
|
|
3
|
+
1. **Sign one of the contributor license agreements below.**
|
|
4
|
+
2. Fork the repo, develop and test your code changes.
|
|
5
|
+
3. Send a pull request.
|
|
6
|
+
|
|
7
|
+
## Contributor License Agreements
|
|
8
|
+
|
|
9
|
+
Before we can accept your pull requests you'll need to sign a Contributor
|
|
10
|
+
License Agreement (CLA):
|
|
11
|
+
|
|
12
|
+
- **If you are an individual writing original source code** and **you own the
|
|
13
|
+
intellectual property**, then you'll need to sign an [individual
|
|
14
|
+
CLA](https://developers.google.com/open-source/cla/individual).
|
|
15
|
+
- **If you work for a company that wants to allow you to contribute your work**,
|
|
16
|
+
then you'll need to sign a [corporate
|
|
17
|
+
CLA](https://developers.google.com/open-source/cla/corporate).
|
|
18
|
+
|
|
19
|
+
You can sign these electronically (just scroll to the bottom). After that, we'll
|
|
20
|
+
be able to accept your pull requests.
|
|
21
|
+
|
|
22
|
+
## Setup
|
|
23
|
+
|
|
24
|
+
In order to use the google-cloud-error_reporting console and run the project's
|
|
25
|
+
tests, there is a small amount of setup:
|
|
26
|
+
|
|
27
|
+
1. Install Ruby. google-cloud-error_reporting requires Ruby 2.3+. You may choose
|
|
28
|
+
to manage your Ruby and gem installations with [RVM](https://rvm.io/),
|
|
29
|
+
[rbenv](https://github.com/rbenv/rbenv), or
|
|
30
|
+
[chruby](https://github.com/postmodern/chruby).
|
|
31
|
+
|
|
32
|
+
2. Install [Bundler](http://bundler.io/).
|
|
33
|
+
|
|
34
|
+
```sh
|
|
35
|
+
$ gem install bundler
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
3. Install the top-level project dependencies.
|
|
39
|
+
|
|
40
|
+
```sh
|
|
41
|
+
$ bundle install
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
4. Install the Error Reporting dependencies.
|
|
45
|
+
|
|
46
|
+
```sh
|
|
47
|
+
$ cd google-cloud-error_reporting/
|
|
48
|
+
$ bundle exec rake bundleupdate
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
## Console
|
|
52
|
+
|
|
53
|
+
In order to run code interactively, you can automatically load
|
|
54
|
+
google-cloud-error_reporting and its dependencies in IRB. This requires that
|
|
55
|
+
your developer environment has already been configured by following the steps
|
|
56
|
+
described in the {file:AUTHENTICATION.md Authentication Guide}. An IRB console
|
|
57
|
+
can be created with:
|
|
58
|
+
|
|
59
|
+
```sh
|
|
60
|
+
$ cd google-cloud-error_reporting/
|
|
61
|
+
$ bundle exec rake console
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## Error Reporting Tests
|
|
65
|
+
|
|
66
|
+
Tests are very important part of google-cloud-error_reporting. All contributions
|
|
67
|
+
should include tests that ensure the contributed code behaves as expected.
|
|
68
|
+
|
|
69
|
+
To run the unit tests, documentation tests, and code style checks together for a
|
|
70
|
+
package:
|
|
71
|
+
|
|
72
|
+
``` sh
|
|
73
|
+
$ cd google-cloud-error_reporting/
|
|
74
|
+
$ bundle exec rake ci
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
To run the command above, plus all acceptance tests, use `rake ci:acceptance` or
|
|
78
|
+
its handy alias, `rake ci:a`.
|
|
79
|
+
|
|
80
|
+
### Error Reporting Unit Tests
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
The project uses the [minitest](https://github.com/seattlerb/minitest) library,
|
|
84
|
+
including [specs](https://github.com/seattlerb/minitest#specs),
|
|
85
|
+
[mocks](https://github.com/seattlerb/minitest#mocks) and
|
|
86
|
+
[minitest-autotest](https://github.com/seattlerb/minitest-autotest).
|
|
87
|
+
|
|
88
|
+
To run the Error Reporting unit tests:
|
|
89
|
+
|
|
90
|
+
``` sh
|
|
91
|
+
$ cd google-cloud-error_reporting/
|
|
92
|
+
$ bundle exec rake test
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
### Error Reporting Documentation Tests
|
|
96
|
+
|
|
97
|
+
The project tests the code examples in the gem's
|
|
98
|
+
[YARD](https://github.com/lsegal/yard)-based documentation.
|
|
99
|
+
|
|
100
|
+
The example testing functions in a way that is very similar to unit testing, and
|
|
101
|
+
in fact the library providing it,
|
|
102
|
+
[yard-doctest](https://github.com/p0deje/yard-doctest), is based on the
|
|
103
|
+
project's unit test library, [minitest](https://github.com/seattlerb/minitest).
|
|
104
|
+
|
|
105
|
+
To run the Error Reporting documentation tests:
|
|
106
|
+
|
|
107
|
+
``` sh
|
|
108
|
+
$ cd google-cloud-error_reporting/
|
|
109
|
+
$ bundle exec rake doctest
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
If you add, remove or modify documentation examples when working on a pull
|
|
113
|
+
request, you may need to update the setup for the tests. The stubs and mocks
|
|
114
|
+
required to run the tests are located in `support/doctest_helper.rb`. Please
|
|
115
|
+
note that much of the setup is matched by the title of the
|
|
116
|
+
[`@example`](http://www.rubydoc.info/gems/yard/file/docs/Tags.md#example) tag.
|
|
117
|
+
If you alter an example's title, you may encounter breaking tests.
|
|
118
|
+
|
|
119
|
+
### Error Reporting Acceptance Tests
|
|
120
|
+
|
|
121
|
+
The Error Reporting acceptance tests interact with the live service API. Follow
|
|
122
|
+
the instructions in the {file:AUTHENTICATION.md Authentication guide} for
|
|
123
|
+
enabling the Error Reporting API. Occasionally, some API features may not yet be
|
|
124
|
+
generally available, making it difficult for some contributors to successfully
|
|
125
|
+
run the entire acceptance test suite. However, please ensure that you do
|
|
126
|
+
successfully run acceptance tests for any code areas covered by your pull
|
|
127
|
+
request.
|
|
128
|
+
|
|
129
|
+
To run the acceptance tests, first create and configure a project in the Google
|
|
130
|
+
Developers Console, as described in the {file:AUTHENTICATION.md Authentication
|
|
131
|
+
guide}. Be sure to download the JSON KEY file. Make note of the PROJECT_ID and
|
|
132
|
+
the KEYFILE location on your system.
|
|
133
|
+
|
|
134
|
+
Before you can run the Error Reporting acceptance tests, you must first create
|
|
135
|
+
indexes used in the tests.
|
|
136
|
+
|
|
137
|
+
#### Running the Error Reporting acceptance tests
|
|
138
|
+
|
|
139
|
+
To run the Error Reporting acceptance tests:
|
|
140
|
+
|
|
141
|
+
``` sh
|
|
142
|
+
$ cd google-cloud-error_reporting/
|
|
143
|
+
$ bundle exec rake acceptance[\\{my-project-id},\\{/path/to/keyfile.json}]
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
Or, if you prefer you can store the values in the `GCLOUD_TEST_PROJECT` and
|
|
147
|
+
`GCLOUD_TEST_KEYFILE` environment variables:
|
|
148
|
+
|
|
149
|
+
``` sh
|
|
150
|
+
$ cd google-cloud-error_reporting/
|
|
151
|
+
$ export GCLOUD_TEST_PROJECT=\\{my-project-id}
|
|
152
|
+
$ export GCLOUD_TEST_KEYFILE=\\{/path/to/keyfile.json}
|
|
153
|
+
$ bundle exec rake acceptance
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
If you want to use a different project and credentials for acceptance tests, you
|
|
157
|
+
can use the more specific `ERROR_REPORTING_TEST_PROJECT` and
|
|
158
|
+
`ERROR_REPORTING_TEST_KEYFILE` environment variables:
|
|
159
|
+
|
|
160
|
+
``` sh
|
|
161
|
+
$ cd google-cloud-error_reporting/
|
|
162
|
+
$ export ERROR_REPORTING_TEST_PROJECT=\\{my-project-id}
|
|
163
|
+
$ export ERROR_REPORTING_TEST_KEYFILE=\\{/path/to/keyfile.json}
|
|
164
|
+
$ bundle exec rake acceptance
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
## Coding Style
|
|
168
|
+
|
|
169
|
+
Please follow the established coding style in the library. The style is is
|
|
170
|
+
largely based on [The Ruby Style
|
|
171
|
+
Guide](https://github.com/bbatsov/ruby-style-guide) with a few exceptions based
|
|
172
|
+
on seattle-style:
|
|
173
|
+
|
|
174
|
+
* Avoid parenthesis when possible, including in method definitions.
|
|
175
|
+
* Always use double quotes strings. ([Option
|
|
176
|
+
B](https://github.com/bbatsov/ruby-style-guide#strings))
|
|
177
|
+
|
|
178
|
+
You can check your code against these rules by running Rubocop like so:
|
|
179
|
+
|
|
180
|
+
```sh
|
|
181
|
+
$ cd google-cloud-error_reporting/
|
|
182
|
+
$ bundle exec rake rubocop
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
## Code of Conduct
|
|
186
|
+
|
|
187
|
+
Please note that this project is released with a Contributor Code of Conduct. By
|
|
188
|
+
participating in this project you agree to abide by its terms. See
|
|
189
|
+
{file:CODE_OF_CONDUCT.md Code of Conduct} for more information.
|
data/INSTRUMENTATION.md
ADDED
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
# Stackdriver Error Reporting Instrumentation
|
|
2
|
+
|
|
3
|
+
The google-cloud-error_reporting gem provides framework instrumentation features
|
|
4
|
+
to make it easy to report exceptions from your application.
|
|
5
|
+
|
|
6
|
+
## Quick Start
|
|
7
|
+
|
|
8
|
+
```ruby
|
|
9
|
+
require "google/cloud/error_reporting"
|
|
10
|
+
|
|
11
|
+
# Insert a Rack Middleware to report unhanded exceptions
|
|
12
|
+
use Google::Cloud::ErrorReporting::Middleware
|
|
13
|
+
|
|
14
|
+
# Or explicitly submit exceptions
|
|
15
|
+
begin
|
|
16
|
+
fail "Boom!"
|
|
17
|
+
rescue => exception
|
|
18
|
+
Google::Cloud::ErrorReporting.report exception
|
|
19
|
+
end
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
## Configuration
|
|
23
|
+
The default configuration enables Stackdriver instrumentation features to run on
|
|
24
|
+
Google Cloud Platform. You can easily configure the instrumentation library if
|
|
25
|
+
you want to run on a non Google Cloud environment or you want to customize the
|
|
26
|
+
default behavior.
|
|
27
|
+
|
|
28
|
+
See the [Configuration
|
|
29
|
+
Guide](https://googlecloudplatform.github.io/google-cloud-ruby/docs/stackdriver/latest/file.INSTRUMENTATION_CONFIGURATION)
|
|
30
|
+
for full configuration parameters.
|
|
31
|
+
|
|
32
|
+
## Rack Middleware and Railtie
|
|
33
|
+
|
|
34
|
+
The google-cloud-error_reporting gem provides a Rack Middleware class that can
|
|
35
|
+
easily integrate with Rack based application frameworks, such as Rails and
|
|
36
|
+
Sinatra. When enabled, it automatically gathers application exceptions from
|
|
37
|
+
requests and submits the information to the Stackdriver Error Reporting service.
|
|
38
|
+
On top of that, the google-cloud-error_reporting also implements a Railtie class
|
|
39
|
+
that automatically enables the Rack Middleware in Rails applications when used.
|
|
40
|
+
|
|
41
|
+
### Rails Integration
|
|
42
|
+
|
|
43
|
+
To use the Stackdriver Error Reporting Railtie for Ruby on Rails applications,
|
|
44
|
+
simply add this line to `config/application.rb`:
|
|
45
|
+
|
|
46
|
+
```ruby
|
|
47
|
+
require "google/cloud/error_reporting/rails"
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
Alternatively, check out the
|
|
51
|
+
[stackdriver](https://googlecloudplatform.github.io/google-cloud-ruby/docs/stackdriver/latest)
|
|
52
|
+
gem, which enables this Railtie by default.
|
|
53
|
+
|
|
54
|
+
### Rack Integration
|
|
55
|
+
|
|
56
|
+
Other Rack-based framework can also directly leverage the Middleware directly:
|
|
57
|
+
|
|
58
|
+
```ruby
|
|
59
|
+
require "google/cloud/error_reporting"
|
|
60
|
+
|
|
61
|
+
use Google::Cloud::ErrorReporting::Middleware
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## Report Captured Exceptions
|
|
65
|
+
Captured Ruby exceptions can be reported directly to Stackdriver Error Reporting
|
|
66
|
+
by using {Google::Cloud::ErrorReporting.report}:
|
|
67
|
+
|
|
68
|
+
```ruby
|
|
69
|
+
begin
|
|
70
|
+
fail "Boom!"
|
|
71
|
+
rescue => exception
|
|
72
|
+
Google::Cloud::ErrorReporting.report exception
|
|
73
|
+
end
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
The reported error event can also be customized:
|
|
77
|
+
|
|
78
|
+
```ruby
|
|
79
|
+
begin
|
|
80
|
+
fail "Boom!"
|
|
81
|
+
rescue => exception
|
|
82
|
+
Google::Cloud::ErrorReporting.report exception do |error_event|
|
|
83
|
+
# Directly modify the Google::Cloud::ErrorReporting::ErrorEvent object before submission
|
|
84
|
+
error_event.message = "Custom error message"
|
|
85
|
+
error_event.user = "johndoh@example.com"
|
|
86
|
+
error_event.http_status = 502
|
|
87
|
+
end
|
|
88
|
+
end
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
See {Google::Cloud::ErrorReporting::ErrorEvent} class for all options.
|
data/LOGGING.md
ADDED
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
# Enabling gRPC Logging
|
|
2
|
+
|
|
3
|
+
To enable logging for this library, set the logger for the underlying
|
|
4
|
+
[gRPC](https://github.com/grpc/grpc/tree/master/src/ruby) library. The logger
|
|
5
|
+
that you set may be a Ruby stdlib
|
|
6
|
+
[`Logger`](https://ruby-doc.org/stdlib-2.5.0/libdoc/logger/rdoc/Logger.html) as
|
|
7
|
+
shown below, or a
|
|
8
|
+
[`Google::Cloud::Logging::Logger`](https://googlecloudplatform.github.io/google-cloud-ruby/docs/google-cloud-logging/latest/Google/Cloud/Logging/Logger)
|
|
9
|
+
that will write logs to [Stackdriver
|
|
10
|
+
Logging](https://cloud.google.com/logging/). See
|
|
11
|
+
[grpc/logconfig.rb](https://github.com/grpc/grpc/blob/master/src/ruby/lib/grpc/logconfig.rb)
|
|
12
|
+
and the gRPC
|
|
13
|
+
[spec_helper.rb](https://github.com/grpc/grpc/blob/master/src/ruby/spec/spec_helper.rb)
|
|
14
|
+
for additional information.
|
|
15
|
+
|
|
16
|
+
Configuring a Ruby stdlib logger:
|
|
17
|
+
|
|
18
|
+
```ruby
|
|
19
|
+
require "logger"
|
|
20
|
+
|
|
21
|
+
module MyLogger
|
|
22
|
+
LOGGER = Logger.new $stderr, level: Logger::WARN
|
|
23
|
+
def logger
|
|
24
|
+
LOGGER
|
|
25
|
+
end
|
|
26
|
+
end
|
|
27
|
+
|
|
28
|
+
# Define a gRPC module-level logger method before grpc/logconfig.rb loads.
|
|
29
|
+
module GRPC
|
|
30
|
+
extend MyLogger
|
|
31
|
+
end
|
|
32
|
+
```
|
data/OVERVIEW.md
ADDED
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# Error Reporting
|
|
2
|
+
|
|
3
|
+
Stackdriver Error Reporting counts, analyzes and aggregates the crashes in your
|
|
4
|
+
running cloud services. The Stackdriver Error Reporting Instrumentation client
|
|
5
|
+
provides a simple way to report errors from your application.
|
|
6
|
+
|
|
7
|
+
For general information about Stackdriver Error Reporting, read [Stackdriver
|
|
8
|
+
Error Reporting Documentation](https://cloud.google.com/error-reporting/docs/).
|
|
9
|
+
|
|
10
|
+
The goal of google-cloud is to provide an API that is comfortable to Rubyists.
|
|
11
|
+
Your authentication credentials are detected automatically in Google Cloud
|
|
12
|
+
Platform environments such as Google Compute Engine, Google App Engine and
|
|
13
|
+
Google Kubernetes Engine. In other environments you can configure authentication
|
|
14
|
+
easily, either directly in your code or via environment variables. Read more
|
|
15
|
+
about the options for connecting in the {file:AUTHENTICATION.md Authentication
|
|
16
|
+
Guide}.
|
|
17
|
+
|
|
18
|
+
## How to report errors
|
|
19
|
+
|
|
20
|
+
You can easily report exceptions from your applications to Stackdriver Error
|
|
21
|
+
Reporting service:
|
|
22
|
+
|
|
23
|
+
```ruby
|
|
24
|
+
require "google/cloud/error_reporting"
|
|
25
|
+
|
|
26
|
+
# Configure Stackdriver ErrorReporting instrumentation
|
|
27
|
+
Google::Cloud::ErrorReporting.configure do |config|
|
|
28
|
+
config.project_id = "my-project"
|
|
29
|
+
config.keyfile = "/path/to/keyfile.json"
|
|
30
|
+
end
|
|
31
|
+
|
|
32
|
+
# Insert a Rack Middleware to report unhanded exceptions
|
|
33
|
+
use Google::Cloud::ErrorReporting::Middleware
|
|
34
|
+
|
|
35
|
+
# Or explicitly submit exceptions
|
|
36
|
+
begin
|
|
37
|
+
fail "Boom!"
|
|
38
|
+
rescue => exception
|
|
39
|
+
Google::Cloud::ErrorReporting.report exception
|
|
40
|
+
end
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
See the {file:INSTRUMENTATION.md Instrumentation Guide} for more examples.
|
|
44
|
+
|
|
45
|
+
## Additional information
|
|
46
|
+
|
|
47
|
+
Stackdriver Error Reporting can be configured to use gRPC's logging. To learn more, see the
|
|
48
|
+
{file:LOGGING.md Logging guide}.
|
data/TROUBLESHOOTING.md
ADDED
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
# Troubleshooting
|
|
2
|
+
|
|
3
|
+
## Where can I get more help?
|
|
4
|
+
|
|
5
|
+
### Ask the Community
|
|
6
|
+
|
|
7
|
+
If you have a question about how to use a Google Cloud client library in your
|
|
8
|
+
project or are stuck in the Developer's console and don't know where to turn,
|
|
9
|
+
it's possible your questions have already been addressed by the community.
|
|
10
|
+
|
|
11
|
+
First, check out the appropriate tags on StackOverflow:
|
|
12
|
+
- [`google-cloud-platform+ruby+errorreporting`][so-ruby]
|
|
13
|
+
|
|
14
|
+
Next, try searching through the issues on GitHub:
|
|
15
|
+
|
|
16
|
+
- [`api:error reporting` issues][gh-search-ruby]
|
|
17
|
+
|
|
18
|
+
Still nothing?
|
|
19
|
+
|
|
20
|
+
### Ask the Developers
|
|
21
|
+
|
|
22
|
+
If you're experiencing a bug with the code, or have an idea for how it can be
|
|
23
|
+
improved, *please* create a new issue on GitHub so we can talk about it.
|
|
24
|
+
|
|
25
|
+
- [New issue][gh-ruby]
|
|
26
|
+
|
|
27
|
+
Or, you can ask questions on the [Google Cloud Platform Slack][slack-ruby]. You
|
|
28
|
+
can use the "ruby" channel for general Ruby questions, or use the
|
|
29
|
+
"google-cloud-ruby" channel if you have questions about this gem in particular.
|
|
30
|
+
|
|
31
|
+
[so-ruby]: http://stackoverflow.com/questions/tagged/google-cloud-platform+ruby+errorreporting
|
|
32
|
+
|
|
33
|
+
[gh-search-ruby]: https://github.com/googlecloudplatform/google-cloud-ruby/issues?q=label%3A%22api%3A+error+reporting%22
|
|
34
|
+
|
|
35
|
+
[gh-ruby]: https://github.com/googlecloudplatform/google-cloud-ruby/issues/new
|
|
36
|
+
|
|
37
|
+
[slack-ruby]: https://gcp-slack.appspot.com/
|
metadata
CHANGED
|
@@ -1,14 +1,14 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: google-cloud-error_reporting
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 0.30.
|
|
4
|
+
version: 0.30.4
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- Google Inc
|
|
8
8
|
autorequire:
|
|
9
9
|
bindir: bin
|
|
10
10
|
cert_chain: []
|
|
11
|
-
date: 2018-09-
|
|
11
|
+
date: 2018-09-12 00:00:00.000000000 Z
|
|
12
12
|
dependencies:
|
|
13
13
|
- !ruby/object:Gem::Dependency
|
|
14
14
|
name: google-cloud-core
|
|
@@ -215,8 +215,15 @@ extensions: []
|
|
|
215
215
|
extra_rdoc_files: []
|
|
216
216
|
files:
|
|
217
217
|
- ".yardopts"
|
|
218
|
+
- AUTHENTICATION.md
|
|
219
|
+
- CHANGELOG.md
|
|
220
|
+
- CODE_OF_CONDUCT.md
|
|
221
|
+
- CONTRIBUTING.md
|
|
222
|
+
- INSTRUMENTATION.md
|
|
218
223
|
- LICENSE
|
|
219
|
-
-
|
|
224
|
+
- LOGGING.md
|
|
225
|
+
- OVERVIEW.md
|
|
226
|
+
- TROUBLESHOOTING.md
|
|
220
227
|
- lib/google-cloud-error_reporting.rb
|
|
221
228
|
- lib/google/cloud/error_reporting.rb
|
|
222
229
|
- lib/google/cloud/error_reporting/async_error_reporter.rb
|
data/README.md
DELETED
|
@@ -1,257 +0,0 @@
|
|
|
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 and
|
|
6
|
-
filtering capabilities. A dedicated view shows the error details: time chart,
|
|
7
|
-
occurrences, affected user count, first and last seen dates and a cleaned
|
|
8
|
-
exception stack trace. Opt-in to receive email and mobile alerts on new errors.
|
|
9
|
-
|
|
10
|
-
- [google-cloud-error_reporting API documentation](http://googlecloudplatform.github.io/google-cloud-ruby/docs/google-cloud-error_reporting/latest)
|
|
11
|
-
- [google-cloud-error_reporting instrumentation documentation](https://googlecloudplatform.github.io/google-cloud-ruby/docs/google-cloud-error_reporting/latest/file.INSTRUMENTATION)
|
|
12
|
-
- [google-cloud-error_reporting on RubyGems](https://rubygems.org/gems/google-cloud-error_reporting)
|
|
13
|
-
- [Stackdriver ErrorReporting documentation](https://cloud.google.com/error-reporting/docs/)
|
|
14
|
-
|
|
15
|
-
## Quick Start
|
|
16
|
-
|
|
17
|
-
Install the gem directly:
|
|
18
|
-
|
|
19
|
-
```sh
|
|
20
|
-
$ gem install google-cloud-error_reporting
|
|
21
|
-
```
|
|
22
|
-
|
|
23
|
-
Or install through Bundler:
|
|
24
|
-
|
|
25
|
-
1. Add the `google-cloud-error_reporting` gem to your Gemfile:
|
|
26
|
-
|
|
27
|
-
```ruby
|
|
28
|
-
gem "google-cloud-error_reporting"
|
|
29
|
-
```
|
|
30
|
-
|
|
31
|
-
2. Use Bundler to install the gem:
|
|
32
|
-
|
|
33
|
-
```sh
|
|
34
|
-
$ bundle install
|
|
35
|
-
```
|
|
36
|
-
|
|
37
|
-
Alternatively, check out the
|
|
38
|
-
[`stackdriver`](http://googlecloudplatform.github.io/google-cloud-ruby/docs/stackdriver/latest)
|
|
39
|
-
gem that includes the `google-cloud-error_reporting` gem.
|
|
40
|
-
|
|
41
|
-
## Enable Stackdriver Error Reporting API
|
|
42
|
-
|
|
43
|
-
The Stackdriver Error Reporting library needs the [Stackdriver Error Reporting
|
|
44
|
-
API](https://console.cloud.google.com/apis/library/clouderrorreporting.googleapis.com)
|
|
45
|
-
to be enabled on your Google Cloud project. Make sure it's enabled if not
|
|
46
|
-
already.
|
|
47
|
-
|
|
48
|
-
## Reporting errors in Rack-based frameworks
|
|
49
|
-
|
|
50
|
-
The Stackdriver Error Reporting library for Ruby makes it easy to integrate
|
|
51
|
-
Stackdriver Error Reporting into popular Rack-based Ruby web frameworks such as
|
|
52
|
-
Ruby on Rails and Sinatra. When the library integration is enabled, it
|
|
53
|
-
automatically reports exceptions captured from the application's Rack stack.
|
|
54
|
-
|
|
55
|
-
### With Ruby on Rails
|
|
56
|
-
|
|
57
|
-
You can load the Railtie that comes with the library into your Ruby on Rails
|
|
58
|
-
application by explicitly requiring it during the application startup:
|
|
59
|
-
|
|
60
|
-
```ruby
|
|
61
|
-
# In config/application.rb
|
|
62
|
-
require "google/cloud/error_reporting/rails"
|
|
63
|
-
```
|
|
64
|
-
|
|
65
|
-
If you're using the `stackdriver` gem, it automatically loads the Railtie into
|
|
66
|
-
your application when it starts.
|
|
67
|
-
|
|
68
|
-
### With other Rack-based frameworks
|
|
69
|
-
|
|
70
|
-
Other Rack-based frameworks, such as Sinatra, can use the Rack Middleware
|
|
71
|
-
provided by the library:
|
|
72
|
-
|
|
73
|
-
```ruby
|
|
74
|
-
require "google/cloud/error_reporting"
|
|
75
|
-
use Google::Cloud::ErrorReporting::Middleware
|
|
76
|
-
```
|
|
77
|
-
|
|
78
|
-
## Reporting errors manually
|
|
79
|
-
|
|
80
|
-
Manually reporting an error is as easy as calling the report method:
|
|
81
|
-
|
|
82
|
-
```ruby
|
|
83
|
-
require "google/cloud/error_reporting"
|
|
84
|
-
begin
|
|
85
|
-
fail "boom!"
|
|
86
|
-
rescue => exception
|
|
87
|
-
Google::Cloud::ErrorReporting.report exception
|
|
88
|
-
end
|
|
89
|
-
```
|
|
90
|
-
|
|
91
|
-
## Configuring the library
|
|
92
|
-
|
|
93
|
-
You can customize the behavior of the Stackdriver Error Reporting library for
|
|
94
|
-
Ruby. See the [configuration
|
|
95
|
-
guide](http://googlecloudplatform.github.io/google-cloud-ruby/docs/stackdriver/latest/file.INSTRUMENTATION_CONFIGURATION)
|
|
96
|
-
for a list of possible configuration options.
|
|
97
|
-
|
|
98
|
-
## Running on Google Cloud Platform
|
|
99
|
-
|
|
100
|
-
The Stackdriver Error Reporting library for Ruby should work without you
|
|
101
|
-
manually providing authentication credentials for instances running on Google
|
|
102
|
-
Cloud Platform, as long as the Stackdriver Error Reporting API access scope is
|
|
103
|
-
enabled on that instance.
|
|
104
|
-
|
|
105
|
-
### App Engine
|
|
106
|
-
|
|
107
|
-
On Google App Engine, the Stackdriver Error Reporting API access scope is
|
|
108
|
-
enabled by default, and the Stackdriver Error Reporting library for Ruby can be
|
|
109
|
-
used without providing credentials or a project ID.
|
|
110
|
-
|
|
111
|
-
### Container Engine
|
|
112
|
-
|
|
113
|
-
On Google Container Engine, you must explicitly add the `cloud-platform` OAuth
|
|
114
|
-
scope when creating the cluster:
|
|
115
|
-
|
|
116
|
-
```sh
|
|
117
|
-
$ gcloud container clusters create example-cluster-name --scopes https://www.googleapis.com/auth/cloud-platform
|
|
118
|
-
```
|
|
119
|
-
|
|
120
|
-
You may also do this through the Google Cloud Platform Console. Select
|
|
121
|
-
**Enabled** in the **Cloud Platform** section of **Create a container cluster**.
|
|
122
|
-
|
|
123
|
-
### Compute Engine
|
|
124
|
-
|
|
125
|
-
For Google Compute Engine instances, you must explicitly enable the
|
|
126
|
-
`cloud-platform` access scope for each instance. When you create a new instance
|
|
127
|
-
through the Google Cloud Platform Console, you can do this under Identity and
|
|
128
|
-
API access: Use the Compute Engine default service account and select "Allow
|
|
129
|
-
full access to all Cloud APIs" under Access scopes.
|
|
130
|
-
|
|
131
|
-
## Running locally and elsewhere
|
|
132
|
-
|
|
133
|
-
To run the Stackdriver Error Reporting outside of Google Cloud Platform, you
|
|
134
|
-
must supply your GCP project ID and appropriate service account credentials
|
|
135
|
-
directly to the Stackdriver Error Reporting. This applies to running the library
|
|
136
|
-
on your own workstation, on your datacenter's computers, or on the VM instances
|
|
137
|
-
of another cloud provider. See the [Authentication section](#authentication) for
|
|
138
|
-
instructions on how to do so.
|
|
139
|
-
|
|
140
|
-
## Authentication
|
|
141
|
-
|
|
142
|
-
The Instrumentation client and API use Service Account credentials to connect to
|
|
143
|
-
Google Cloud services. When running on Google Cloud Platform environments, the
|
|
144
|
-
credentials will be discovered automatically. When running on other environments
|
|
145
|
-
the Service Account credentials can be specified by providing in several ways.
|
|
146
|
-
|
|
147
|
-
The best way to provide authentication information if you're using Ruby on Rails
|
|
148
|
-
is through the Rails configuration interface:
|
|
149
|
-
|
|
150
|
-
```ruby
|
|
151
|
-
# in config/environments/*.rb
|
|
152
|
-
Rails.application.configure do |config|
|
|
153
|
-
# Shared parameters
|
|
154
|
-
config.google_cloud.project_id = "your-project-id"
|
|
155
|
-
config.google_cloud.keyfile = "/path/to/key.json"
|
|
156
|
-
# Or Stackdriver Error Reporting specific parameters
|
|
157
|
-
config.google_cloud.error_reporting.project_id = "your-project-id"
|
|
158
|
-
config.google_cloud.error_reporting.keyfile = "/path/to/key.json"
|
|
159
|
-
end
|
|
160
|
-
```
|
|
161
|
-
|
|
162
|
-
Other Rack-based applications that are loading the Rack Middleware directly or
|
|
163
|
-
using the manually reporting interface can leverage the configration interface:
|
|
164
|
-
|
|
165
|
-
```ruby
|
|
166
|
-
require "google/cloud/error_reporting"
|
|
167
|
-
Google::Cloud.configure do |config|
|
|
168
|
-
# Shared parameters
|
|
169
|
-
config.project_id = "your-project-id"
|
|
170
|
-
config.keyfile = "/path/to/key.json"
|
|
171
|
-
# Or Stackdriver Error Reporting specific parameters
|
|
172
|
-
config.error_reporting.project_id = "your-project-id"
|
|
173
|
-
config.error_reporting.keyfile = "/path/to/key.json"
|
|
174
|
-
end
|
|
175
|
-
```
|
|
176
|
-
|
|
177
|
-
This library also supports the other authentication methods provided by the
|
|
178
|
-
`google-cloud-ruby` suite. Instructions and configuration options are covered in
|
|
179
|
-
the [Authentication
|
|
180
|
-
Guide](https://googlecloudplatform.github.io/google-cloud-ruby/docs/google-cloud-debugger/latest/file.AUTHENTCATION).
|
|
181
|
-
|
|
182
|
-
## Enabling Logging
|
|
183
|
-
|
|
184
|
-
To enable logging for this library, set the logger for the underlying
|
|
185
|
-
[gRPC](https://github.com/grpc/grpc/tree/master/src/ruby) library. The logger
|
|
186
|
-
that you set may be a Ruby stdlib
|
|
187
|
-
[`Logger`](https://ruby-doc.org/stdlib-2.5.0/libdoc/logger/rdoc/Logger.html) as
|
|
188
|
-
shown below, or a
|
|
189
|
-
[`Google::Cloud::Logging::Logger`](https://googlecloudplatform.github.io/google-cloud-ruby/docs/google-cloud-logging/latest/Google/Cloud/Logging/Logger)
|
|
190
|
-
that will write logs to [Stackdriver
|
|
191
|
-
Logging](https://cloud.google.com/logging/). See
|
|
192
|
-
[grpc/logconfig.rb](https://github.com/grpc/grpc/blob/master/src/ruby/lib/grpc/logconfig.rb)
|
|
193
|
-
and the gRPC
|
|
194
|
-
[spec_helper.rb](https://github.com/grpc/grpc/blob/master/src/ruby/spec/spec_helper.rb)
|
|
195
|
-
for additional information.
|
|
196
|
-
|
|
197
|
-
Configuring a Ruby stdlib logger:
|
|
198
|
-
|
|
199
|
-
```ruby
|
|
200
|
-
require "logger"
|
|
201
|
-
|
|
202
|
-
module MyLogger
|
|
203
|
-
LOGGER = Logger.new $stderr, level: Logger::WARN
|
|
204
|
-
def logger
|
|
205
|
-
LOGGER
|
|
206
|
-
end
|
|
207
|
-
end
|
|
208
|
-
|
|
209
|
-
# Define a gRPC module-level logger method before grpc/logconfig.rb loads.
|
|
210
|
-
module GRPC
|
|
211
|
-
extend MyLogger
|
|
212
|
-
end
|
|
213
|
-
```
|
|
214
|
-
|
|
215
|
-
## Supported Ruby Versions
|
|
216
|
-
|
|
217
|
-
This library is supported on Ruby 2.3+.
|
|
218
|
-
|
|
219
|
-
Google provides official support for Ruby versions that are actively supported
|
|
220
|
-
by Ruby Core—that is, Ruby versions that are either in normal maintenance or in
|
|
221
|
-
security maintenance, and not end of life. Currently, this means Ruby 2.3 and
|
|
222
|
-
later. Older versions of Ruby _may_ still work, but are unsupported and not
|
|
223
|
-
recommended. See https://www.ruby-lang.org/en/downloads/branches/ for details
|
|
224
|
-
about the Ruby support schedule.
|
|
225
|
-
|
|
226
|
-
## Versioning
|
|
227
|
-
|
|
228
|
-
This library follows [Semantic Versioning](http://semver.org/).
|
|
229
|
-
|
|
230
|
-
It is currently in major version zero (0.y.z), which means that anything may
|
|
231
|
-
change at any time and the public API should not be considered stable.
|
|
232
|
-
|
|
233
|
-
## Contributing
|
|
234
|
-
|
|
235
|
-
Contributions to this library are always welcome and highly encouraged.
|
|
236
|
-
|
|
237
|
-
See the [Contributing
|
|
238
|
-
Guide](https://googlecloudplatform.github.io/google-cloud-ruby/docs/google-cloud-debugger/latest/file.CONTRIBUTING)
|
|
239
|
-
for more information on how to get started.
|
|
240
|
-
|
|
241
|
-
Please note that this project is released with a Contributor Code of Conduct. By
|
|
242
|
-
participating in this project you agree to abide by its terms. See [Code of
|
|
243
|
-
Conduct](https://googlecloudplatform.github.io/google-cloud-ruby/docs/google-cloud-debugger/latest/file.CODE_OF_CONDUCT)
|
|
244
|
-
for more information.
|
|
245
|
-
|
|
246
|
-
## License
|
|
247
|
-
|
|
248
|
-
This library is licensed under Apache 2.0. Full license text is available in
|
|
249
|
-
[LICENSE](https://googlecloudplatform.github.io/google-cloud-ruby/docs/google-cloud-debugger/latest/file.LICENSE).
|
|
250
|
-
|
|
251
|
-
## Support
|
|
252
|
-
|
|
253
|
-
Please [report bugs at the project on
|
|
254
|
-
Github](https://github.com/GoogleCloudPlatform/google-cloud-ruby/issues). Don't
|
|
255
|
-
hesitate to [ask
|
|
256
|
-
questions](http://stackoverflow.com/questions/tagged/google-cloud-platform+ruby)
|
|
257
|
-
about the client or APIs on [StackOverflow](http://stackoverflow.com).
|