Skip to content

Commit 4ec4ed8

Browse files
hxiong388hxiong388
committed
Update stackdriver readmes
1 parent 98042d6 commit 4ec4ed8

4 files changed

Lines changed: 524 additions & 105 deletions

File tree

‎google-cloud-debugger/README.md‎

Lines changed: 158 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,177 @@
11
# google-cloud-debugger
22

3-
[Stackdriver Debugger](https://cloud.google.com/debugger/) ([docs](https://cloud.google.com/debugger/docs/)) lets you inspect the state of a running application at any code location in real time, without stopping or slowing down the application, and without modifying the code to add logging statements. You can use Stackdriver Debugger with any deployment of your application, including test, development, and production. The Ruby debugger adds minimal request latency, typically less than 50ms, and only when the application state is captured. In most cases, this is not noticeable by users.
3+
[Stackdriver Debugger](https://cloud.google.com/debugger/) lets you inspect the state of a running application at any code location in real time, without stopping or slowing down the application, and without modifying the code to add logging statements. You can use Stackdriver Debugger with any deployment of your application, including test, development, and production. The Ruby debugger adds minimal request latency, typically less than 50ms, and only when the application state is captured. In most cases, this is not noticeable by users.
44

55
- [google-cloud-debugger documentation](http://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-debugger/master/google/cloud/debugger)
66
- [google-cloud-debugger on RubyGems](https://rubygems.org/gems/google-cloud-debugger)
77
- [Stackdriver Debugger documentation](https://cloud.google.com/debugger/docs/)
88

99
## Quick Start
1010

11-
Setting up Stackdriver Debugger involves three steps:
11+
Install the gem directly:
1212

13-
1. Add the `google-cloud-debugger` library to your app.
14-
2. Register your app's source code.
15-
3. Deploy your app and set a breakpoint.
13+
```sh
14+
$ gem install google-cloud-debugger
15+
```
1616

17-
See the
18-
[google-cloud-debugger documentation](http://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-debugger/master/google/cloud/debugger)
19-
for a quick tutorial.
17+
Or install through Bundler:
2018

21-
## Authentication
19+
1. Add the `google-cloud-debugger` gem to your Gemfile:
20+
21+
```ruby
22+
gem "google-cloud-debugger"
23+
```
24+
25+
2. Use Bundler to install the gem:
26+
27+
```sh
28+
$ bundle install
29+
```
30+
31+
Alternatively, check out the [`stackdriver`](../stackdriver) gem that includes
32+
the `google-cloud-debugger` gem.
33+
34+
## Enable Stackdriver Debugger API
35+
36+
The Stackdriver Debugger agent would need the [Stackdriver Debugger
37+
API](https://console.cloud.google.com/apis/library/clouddebugger.googleapis.com)
38+
to be enabled on your Google Cloud project. Make sure it's enabled if not
39+
already.
40+
41+
## Enabling the Debugger agent
42+
43+
If you're using Ruby on Rails and the `stackdriver` gem, they automatically
44+
loads the library into your application when it starts.
45+
46+
Otherwise, you can load the Railtie that comes with the library into your Ruby
47+
on Rails application by explicitly require it in the application startup path:
48+
49+
```ruby
50+
# In config/application.rb
51+
require "google/cloud/debugger/rails"
52+
```
53+
54+
Other Rack-based frameworks, such as Sinatra, can use the Rack Middleware
55+
provided by the library:
56+
57+
```ruby
58+
require "google/cloud/debugger"
59+
use Google::Cloud::Debugger::Middleware
60+
```
61+
62+
Non-rack-based applications can start the agent explicitly at the entry point of
63+
your application:
64+
65+
```ruby
66+
require "google/cloud/debugger"
67+
Google::Cloud::Debugger.new.start
68+
```
69+
70+
### Configuring the agent
2271

23-
This library uses Service Account credentials to connect to Google Cloud services. When running on Compute Engine the credentials will be discovered automatically. When running on other environments the Service Account credentials can be specified by providing the path to the JSON file, or the JSON itself, in environment variables.
72+
You can customize the behavior of the Stackdriver Debugger agent. See the
73+
[agent configuration](../stackdriver/docs/configuration.md) for a list of
74+
possible configuration options.
2475

25-
Instructions and configuration options are covered in the [Authentication Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-debugger/guides/authentication).
76+
## Running on Google Cloud Platform
2677

27-
## Usage
78+
The Stackdriver Debugger agent should work without you manually providing
79+
authentication credentials for instances running on Google Cloud Platform, as
80+
long as the Stackdriver Debugger API access scope is enabled on that instance.
81+
82+
### App Engine
83+
84+
On Google App Engine, the Stackdriver Debugger API access scope is enabled by
85+
default, and the Stackdriver Debugger agent can be used without providing
86+
credentials or a project ID.
87+
88+
### Container Engine
89+
90+
On Google Container Engine, you must explicitly add the `cloud_debugger` OAuth
91+
scope when creating the cluster:
92+
93+
```sh
94+
$ gcloud container clusters create example-cluster-name --scopes https://www.googleapis.com/auth/cloud_debugger
95+
```
96+
97+
You can also do this through the Google Cloud Platform Console. Select
98+
**Enabled** in the Cloud Platform section of **Create a container cluster**.
99+
100+
### Compute Engine
101+
102+
To use Stackdriver Debugger, Compute Engine VM instances should have one of the
103+
following access scopes. These are only relevant when you use Compute Engine's
104+
default service account:
105+
106+
* `https://www.googleapis.com/auth/cloud-platform`
107+
* `https://www.googleapis.com/auth/cloud_debugger`
108+
109+
The `cloud-platform` access scope can be supplied when creating a new instance
110+
through the Google Cloud Platform Console. Select **Allow full access to all
111+
Cloud APIs** in the **Identity and API access** section of **Create an
112+
instance**.
113+
114+
The `cloud_debugger` access scope must be supplied manually using the SDK's
115+
`gcloud compute instances create` command or the `gcloud compute instances
116+
set-service-account` command.
117+
118+
## Running locally and elsewhere
119+
120+
To run the Stackdriver Debugger agent outside of Google Cloud Platform, you must
121+
supply your GCP project ID and appropriate service account credentials directly
122+
to the Stackdriver Debugger agent. This applies to running the agent on your own
123+
workstation, on your datacenter's computers, or on the VM instances of another
124+
cloud provider. See the [Authentication section](#authentication) for
125+
instructions on how to do so.
126+
127+
## Authentication
28128

29-
This library provides a Stackdriver Debugger Agent that's able to work with Ruby applications. It also integrates with Ruby on Rails and other popular Rack-based frameworks. See the [Instrumentation Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-debugger/guides/instrumentation) for more details.
129+
This library uses Service Account credentials to connect to Google Cloud
130+
services. When running on Compute Engine the credentials will be discovered
131+
automatically. When running on other environments the Service Account
132+
credentials can be specified by providing in several ways.
133+
134+
The best way to provide authentication information if you're using Ruby on Rails
135+
is through the Rails configuration interface:
136+
137+
```ruby
138+
# in config/environments/*.rb
139+
Rails.application.configure do |config|
140+
# Shared parameters
141+
config.google_cloud.project_id = "your-project-id"
142+
config.google_cloud.keyfile = "/path/to/key.json"
143+
# Or Stackdriver Debugger agent specific parameters
144+
config.google_cloud.debugger.project_id = "your-project-id"
145+
config.google_cloud.debugger.keyfile = "/path/to/key.json"
146+
end
147+
```
148+
149+
Other Rack-based applications that are loading the Rack Middleware directly can use
150+
the configration interface:
151+
152+
```ruby
153+
require "google/cloud/debugger"
154+
Google::Cloud.configure do |config|
155+
# Shared parameters
156+
config.project_id = "your-project-id"
157+
config.keyfile = "/path/to/key.json"
158+
# Or Stackdriver Debugger agent specific parameters
159+
config.debugger.project_id = "your-project-id"
160+
config.debugger.keyfile = "/path/to/key.json"
161+
end
162+
```
163+
164+
Or provide the parameters to the Stackdriver Debugger agent when it starts:
165+
166+
```ruby
167+
require "google/cloud/debugger"
168+
Google::Cloud::Debugger.new(project_id: "your-project-id",
169+
keyfile: "/path/to/key.json").start
170+
```
171+
172+
This library also supports the other authentication methods provided by the
173+
`google-cloud-ruby` suite. Instructions and configuration options are covered
174+
in the [Authentication Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-debugger/guides/authentication).
30175

31176
## Supported Ruby Versions
32177

‎google-cloud-error_reporting/README.md‎

Lines changed: 138 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -13,63 +13,166 @@ new errors.
1313
- [google-cloud-error_reporting on RubyGems](https://rubygems.org/gems/google-cloud-error_reporting)
1414
- [Stackdriver ErrorReporting documentation](https://cloud.google.com/error-reporting/docs/)
1515

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-
2216
## Quick Start
17+
18+
Install the gem directly:
19+
2320
```sh
2421
$ gem install google-cloud-error_reporting
2522
```
2623

27-
## Authentication
24+
Or install through Bundler:
2825

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.
26+
1. Add the `google-cloud-error_reporting` gem to your Gemfile:
27+
28+
```ruby
29+
gem "google-cloud-error_reporting"
30+
```
31+
32+
2. Use Bundler to install the gem:
33+
34+
```sh
35+
$ bundle install
36+
```
37+
38+
Alternatively, check out the [`stackdriver`](../stackdriver) gem that includes
39+
the `google-cloud-error_reporting` gem.
40+
41+
## Enable Stackdriver Error Reporting API
3542

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).
43+
The Stackdriver Error Reporting library would need the [Stackdriver Error
44+
Reporting 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+
If you're using Ruby on Rails and the `stackdriver` gem, they automatically
56+
loads the library into your application when it starts.
57+
58+
Otherwise, you can load the Railtie that comes with the library into your Ruby
59+
on Rails application by explicitly require it in the application startup path:
60+
61+
```ruby
62+
# In config/application.rb
63+
require "google/cloud/error_reporting/rails"
64+
```
65+
66+
Other Rack-based frameworks, such as Sinatra, can use the Rack Middleware
67+
provided by the library:
3868

39-
## Instrumentation Example
4069
```ruby
4170
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
5071
use Google::Cloud::ErrorReporting::Middleware
51-
52-
# Or explicitly submit exceptions
72+
```
73+
74+
## Reporting errors manually
75+
76+
Manually reporting an error is as easy as calling the report method:
77+
78+
```ruby
79+
require "google/cloud/error_reporting"
5380
begin
54-
fail "Boom!"
81+
fail "boom!"
5582
rescue => exception
5683
Google::Cloud::ErrorReporting.report exception
5784
end
5885
```
5986

60-
## Rails and Rack Integration
87+
## Configuring the library
88+
89+
You can customize the behavior of the Stackdriver Error Reporting library for
90+
Ruby. See the [configuration guide](../stackdriver/configuration.md) for a list
91+
of possible configuration options.
92+
93+
## Running on Google Cloud Platform
94+
95+
The Stackdriver Error Reporting library for Ruby should work without you
96+
manually providing authentication credentials for instances running on Google
97+
Cloud Platform, as long as the Stackdriver Error Reporting API access scope is
98+
enabled on that instance.
99+
100+
### App Engine
101+
102+
On Google App Engine, the Stackdriver Error Reporting API access scope is
103+
enabled by default, and the Stackdriver Error Reporting library for Ruby can
104+
be used without providing credentials or a project ID.
105+
106+
### Container Engine
107+
108+
On Google Container Engine, you must explicitly add the `cloud-platform` OAuth
109+
scope when creating the cluster:
110+
111+
```sh
112+
$ gcloud container clusters create example-cluster-name --scopes https://www.googleapis.com/auth/cloud-platform
113+
```
114+
115+
You may also do this through the Google Cloud Platform Console. Select
116+
**Enabled** in the **Cloud Platform** section of **Create a container cluster**.
117+
118+
### Compute Engine
119+
120+
For Google Compute Engine instances, you must explicitly enable the
121+
`cloud-platform` access scope for each instance. When you create a new instance
122+
through the Google Cloud Platform Console, you can do this under Identity and
123+
API access: Use the Compute Engine default service account and select "Allow
124+
full access to all Cloud APIs" under Access scopes.
125+
126+
## Running locally and elsewhere
127+
128+
To run the Stackdriver Error Reporting outside of Google Cloud Platform, you
129+
must supply your GCP project ID and appropriate service account credentials
130+
directly to the Stackdriver Error Reporting. This applies to running the
131+
library on your own workstation, on your datacenter's computers, or on the VM
132+
instances of another cloud provider. See the [Authentication
133+
section](#authentication) for instructions on how to do so.
134+
135+
## Authentication
136+
137+
The Instrumentation client and API use Service Account credentials to connect
138+
to Google Cloud services. When running on Google Cloud Platform environments,
139+
the credentials will be discovered automatically. When running on other
140+
environments the Service Account credentials can be specified by providing in
141+
several ways.
142+
143+
The best way to provide authentication information if you're using Ruby on Rails
144+
is through the Rails configuration interface:
61145

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:
64146
```ruby
65-
require "google/cloud/error_reporting/rails"
147+
# in config/environments/*.rb
148+
Rails.application.configure do |config|
149+
# Shared parameters
150+
config.google_cloud.project_id = "your-project-id"
151+
config.google_cloud.keyfile = "/path/to/key.json"
152+
# Or Stackdriver Error Reporting specific parameters
153+
config.google_cloud.error_reporting.project_id = "your-project-id"
154+
config.google_cloud.error_reporting.keyfile = "/path/to/key.json"
155+
end
66156
```
67157

68-
Alternatively, check out the [stackdriver](../stackdriver) gem, which includes
69-
this library and enables the Railtie by default.
158+
Other Rack-based applications that are loading the Rack Middleware directly can use
159+
the configration interface:
160+
161+
```ruby
162+
require "google/cloud/error_reporting"
163+
Google::Cloud.configure do |config|
164+
# Shared parameters
165+
config.project_id = "your-project-id"
166+
config.keyfile = "/path/to/key.json"
167+
# Or Stackdriver Error Reporting specific parameters
168+
config.error_reporting.project_id = "your-project-id"
169+
config.error_reporting.keyfile = "/path/to/key.json"
170+
end
171+
```
70172

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).
173+
This library also supports the other authentication methods provided by the
174+
`google-cloud-ruby` suite. Instructions and configuration options are covered
175+
in the [Authentication Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-debugger/guides/authentication).
73176

74177
## Supported Ruby Versions
75178

0 commit comments

Comments
 (0)