google-cloud-debugger 0.40.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.
Files changed (45) hide show
  1. checksums.yaml +7 -0
  2. data/.yardopts +18 -0
  3. data/AUTHENTICATION.md +178 -0
  4. data/CHANGELOG.md +233 -0
  5. data/CODE_OF_CONDUCT.md +40 -0
  6. data/CONTRIBUTING.md +188 -0
  7. data/INSTRUMENTATION.md +115 -0
  8. data/LICENSE +201 -0
  9. data/LOGGING.md +32 -0
  10. data/OVERVIEW.md +266 -0
  11. data/TROUBLESHOOTING.md +31 -0
  12. data/ext/google/cloud/debugger/debugger_c/debugger.c +31 -0
  13. data/ext/google/cloud/debugger/debugger_c/debugger.h +26 -0
  14. data/ext/google/cloud/debugger/debugger_c/evaluator.c +115 -0
  15. data/ext/google/cloud/debugger/debugger_c/evaluator.h +25 -0
  16. data/ext/google/cloud/debugger/debugger_c/extconf.rb +22 -0
  17. data/ext/google/cloud/debugger/debugger_c/tracer.c +542 -0
  18. data/ext/google/cloud/debugger/debugger_c/tracer.h +25 -0
  19. data/lib/google-cloud-debugger.rb +181 -0
  20. data/lib/google/cloud/debugger.rb +259 -0
  21. data/lib/google/cloud/debugger/agent.rb +255 -0
  22. data/lib/google/cloud/debugger/backoff.rb +70 -0
  23. data/lib/google/cloud/debugger/breakpoint.rb +443 -0
  24. data/lib/google/cloud/debugger/breakpoint/evaluator.rb +1099 -0
  25. data/lib/google/cloud/debugger/breakpoint/source_location.rb +74 -0
  26. data/lib/google/cloud/debugger/breakpoint/stack_frame.rb +109 -0
  27. data/lib/google/cloud/debugger/breakpoint/status_message.rb +93 -0
  28. data/lib/google/cloud/debugger/breakpoint/validator.rb +92 -0
  29. data/lib/google/cloud/debugger/breakpoint/variable.rb +595 -0
  30. data/lib/google/cloud/debugger/breakpoint/variable_table.rb +96 -0
  31. data/lib/google/cloud/debugger/breakpoint_manager.rb +311 -0
  32. data/lib/google/cloud/debugger/credentials.rb +50 -0
  33. data/lib/google/cloud/debugger/debuggee.rb +222 -0
  34. data/lib/google/cloud/debugger/debuggee/app_uniquifier_generator.rb +76 -0
  35. data/lib/google/cloud/debugger/logpoint.rb +98 -0
  36. data/lib/google/cloud/debugger/middleware.rb +200 -0
  37. data/lib/google/cloud/debugger/project.rb +110 -0
  38. data/lib/google/cloud/debugger/rails.rb +174 -0
  39. data/lib/google/cloud/debugger/request_quota_manager.rb +95 -0
  40. data/lib/google/cloud/debugger/service.rb +88 -0
  41. data/lib/google/cloud/debugger/snappoint.rb +208 -0
  42. data/lib/google/cloud/debugger/tracer.rb +137 -0
  43. data/lib/google/cloud/debugger/transmitter.rb +199 -0
  44. data/lib/google/cloud/debugger/version.rb +22 -0
  45. metadata +353 -0
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA256:
3
+ metadata.gz: 1b4ce08aa3118de8cc2a1afe7874ca26f6d97a7922f84471caef85fe0aed3640
4
+ data.tar.gz: a6bc54a758686120fe5898e69179994e3325e72adf5c9e3b8ef4b0b010a5c9d6
5
+ SHA512:
6
+ metadata.gz: 150edcd3b7d9c16480900ac16d22925eaf08c1629ac40c601d308da5e3db74237dbacd6510c9357861650d8fe519239c53c361448e3f6d005058313c1e442909
7
+ data.tar.gz: ce89d0b2545e87b7587b8887a6eafe1dead96614616437ce2709f60a83780a38607990687caf74398a219093d019f68bcd615aac469e1b35efec732c71141508
@@ -0,0 +1,18 @@
1
+ --no-private
2
+ --title=Stackdriver Debugger
3
+ --exclude _pb\.rb$
4
+ --markup markdown
5
+ --markup-provider redcarpet
6
+ --main OVERVIEW.md
7
+
8
+ ./lib/**/*.rb
9
+ -
10
+ OVERVIEW.md
11
+ AUTHENTICATION.md
12
+ INSTRUMENTATION.md
13
+ LOGGING.md
14
+ CONTRIBUTING.md
15
+ TROUBLESHOOTING.md
16
+ CHANGELOG.md
17
+ CODE_OF_CONDUCT.md
18
+ LICENSE
@@ -0,0 +1,178 @@
1
+ # Authentication
2
+
3
+ In general, the google-cloud-debugger 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 within [Google
6
+ Cloud Platform environments](#google-cloud-platform-environments)
7
+ the credentials will be discovered automatically. When running on other
8
+ environments, the Service Account credentials can be specified by providing the
9
+ path to the [JSON
10
+ keyfile](https://cloud.google.com/iam/docs/managing-service-account-keys) for
11
+ the account (or the JSON itself) in [environment
12
+ variables](#environment-variables). Additionally, Cloud SDK credentials can also
13
+ be discovered automatically, but this is only recommended during development.
14
+
15
+ ## Quickstart
16
+
17
+ 1. [Create a service account and credentials](#creating-a-service-account).
18
+ 2. Set the [environment variable](#environment-variables).
19
+
20
+ ```sh
21
+ export DEBUGGER_CREDENTIALS=/path/to/json`
22
+ ```
23
+
24
+ 3. Initialize the client.
25
+
26
+ ```ruby
27
+ require "google/cloud/debugger"
28
+
29
+ client = Google::Cloud::Debugger.new
30
+ ```
31
+
32
+ ## Project and Credential Lookup
33
+
34
+ The google-cloud-debugger library aims to make authentication
35
+ as simple as possible, and provides several mechanisms to configure your system
36
+ without providing **Project ID** and **Service Account Credentials** directly in
37
+ code.
38
+
39
+ **Project ID** is discovered in the following order:
40
+
41
+ 1. Specify project ID in method arguments
42
+ 2. Specify project ID in configuration
43
+ 3. Discover project ID in environment variables
44
+ 4. Discover GCE project ID
45
+ 5. Discover project ID in credentials JSON
46
+
47
+ **Credentials** are discovered in the following order:
48
+
49
+ 1. Specify credentials in method arguments
50
+ 2. Specify credentials in configuration
51
+ 3. Discover credentials path in environment variables
52
+ 4. Discover credentials JSON in environment variables
53
+ 5. Discover credentials file in the Cloud SDK's path
54
+ 6. Discover GCE credentials
55
+
56
+ ### Google Cloud Platform environments
57
+
58
+ When running on Google Cloud Platform (GCP), including Google Compute Engine (GCE),
59
+ Google Kubernetes Engine (GKE), Google App Engine (GAE), Google Cloud Functions
60
+ (GCF) and Cloud Run, the **Project ID** and **Credentials** and are discovered
61
+ automatically. Code should be written as if already authenticated.
62
+
63
+ ### Environment Variables
64
+
65
+ The **Project ID** and **Credentials JSON** can be placed in environment
66
+ variables instead of declaring them directly in code. Each service has its own
67
+ environment variable, allowing for different service accounts to be used for
68
+ different services. (See the READMEs for the individual service gems for
69
+ details.) The path to the **Credentials JSON** file can be stored in the
70
+ environment variable, or the **Credentials JSON** itself can be stored for
71
+ environments such as Docker containers where writing files is difficult or not
72
+ encouraged.
73
+
74
+ The environment variables that google-cloud-debugger checks for project ID are:
75
+
76
+ 1. `DEBUGGER_PROJECT`
77
+ 2. `GOOGLE_CLOUD_PROJECT`
78
+
79
+ The environment variables that google-cloud-debugger checks for credentials are
80
+ configured on `Google::Cloud::Debugger::V2::Debugger::Credentials`:
81
+
82
+ 1. `DEBUGGER_CREDENTIALS` - Path to JSON file, or JSON contents
83
+ 2. `DEBUGGER_KEYFILE` - Path to JSON file, or JSON contents
84
+ 3. `GOOGLE_CLOUD_CREDENTIALS` - Path to JSON file, or JSON contents
85
+ 4. `GOOGLE_CLOUD_KEYFILE` - Path to JSON file, or JSON contents
86
+ 5. `GOOGLE_APPLICATION_CREDENTIALS` - Path to JSON file
87
+
88
+ ```ruby
89
+ require "google/cloud/debugger"
90
+
91
+ ENV["DEBUGGER_PROJECT"] = "my-project-id"
92
+ ENV["DEBUGGER_CREDENTIALS"] = "path/to/keyfile.json"
93
+
94
+ client = Google::Cloud::Debugger.new
95
+ ```
96
+
97
+ ### Configuration
98
+
99
+ The **Project ID** and **Credentials JSON** can be configured instead of placing them in environment variables or providing them as arguments.
100
+
101
+ ```ruby
102
+ require "google/cloud/debugger"
103
+
104
+ Google::Cloud::Debugger.configure do |config|
105
+ config.project_id = "my-project-id"
106
+ config.credentials = "path/to/keyfile.json"
107
+ end
108
+
109
+ client = Google::Cloud::Debugger.new
110
+ ```
111
+
112
+ ### Cloud SDK
113
+
114
+ This option allows for an easy way to authenticate during development. If
115
+ credentials are not provided in code or in environment variables, then Cloud SDK
116
+ credentials are discovered.
117
+
118
+ To configure your system for this, simply:
119
+
120
+ 1. [Download and install the Cloud SDK](https://cloud.google.com/sdk)
121
+ 2. Authenticate using OAuth 2.0 `$ gcloud auth login`
122
+ 3. Write code as if already authenticated.
123
+
124
+ **NOTE:** This is _not_ recommended for running in production. The Cloud SDK
125
+ *should* only be used during development.
126
+
127
+ [gce-how-to]: https://cloud.google.com/compute/docs/authentication#using
128
+ [dev-console]: https://console.cloud.google.com/project
129
+
130
+ [enable-apis]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/enable-apis.png
131
+
132
+ [create-new-service-account]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/create-new-service-account.png
133
+ [create-new-service-account-existing-keys]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/create-new-service-account-existing-keys.png
134
+ [reuse-service-account]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/reuse-service-account.png
135
+
136
+ ## Creating a Service Account
137
+
138
+ Google Cloud requires a **Project ID** and **Service Account Credentials** to
139
+ connect to the APIs. You will use the **Project ID** and **JSON key file** to
140
+ connect to most services with google-cloud-debugger.
141
+
142
+ If you are not running this client within [Google Cloud Platform
143
+ environments](#google-cloud-platform-environments), you need a Google
144
+ Developers service account.
145
+
146
+ 1. Visit the [Google Developers Console][dev-console].
147
+ 1. Create a new project or click on an existing project.
148
+ 1. Activate the slide-out navigation tray and select **API Manager**. From
149
+ here, you will enable the APIs that your application requires.
150
+
151
+ ![Enable the APIs that your application requires][enable-apis]
152
+
153
+ *Note: You may need to enable billing in order to use these services.*
154
+
155
+ 1. Select **Credentials** from the side navigation.
156
+
157
+ You should see a screen like one of the following.
158
+
159
+ ![Create a new service account][create-new-service-account]
160
+
161
+ ![Create a new service account With Existing Keys][create-new-service-account-existing-keys]
162
+
163
+ Find the "Add credentials" drop down and select "Service account" to be
164
+ guided through downloading a new JSON key file.
165
+
166
+ If you want to re-use an existing service account, you can easily generate a
167
+ new key file. Just select the account you wish to re-use, and click "Generate
168
+ new JSON key":
169
+
170
+ ![Re-use an existing service account][reuse-service-account]
171
+
172
+ The key file you download will be used by this library to authenticate API
173
+ requests and should be stored in a secure location.
174
+
175
+ ## Troubleshooting
176
+
177
+ If you're having trouble authenticating you can ask for help by following the
178
+ {file:TROUBLESHOOTING.md Troubleshooting Guide}.
@@ -0,0 +1,233 @@
1
+ # Release History
2
+
3
+ ### 0.40.0 / 2020-07-21
4
+
5
+ This is a major update that removes the "low-level" client interface code, and
6
+ instead adds the new `google-cloud-debugger-v2` gem as a dependency.
7
+ The new dependency is a rewritten low-level client, produced by a next-
8
+ generation client code generator, with improved performance and stability.
9
+
10
+ This change should have no effect on the high-level interface that most users
11
+ will use. The one exception is that the (mostly undocumented) `client_config`
12
+ argument, for adjusting low-level parameters such as RPC retry settings on
13
+ client objects, has been removed. If you need to adjust these parameters, use
14
+ the configuration interface in `google-cloud-debugger-v2`.
15
+
16
+ Substantial changes have been made in the low-level interfaces, however. If you
17
+ are using the low-level classes under the `Google::Cloud::Debugger::V2` module,
18
+ please review the docs for the new `google-cloud-debugger-v2` gem. In
19
+ particular:
20
+
21
+ * Some classes have been renamed, notably the client class itself.
22
+ * The client constructor takes a configuration block instead of configuration
23
+ keyword arguments.
24
+ * All RPC method arguments are now keyword arguments.
25
+
26
+ ### 0.36.3 / 2020-07-06
27
+
28
+ #### Bug Fixes
29
+
30
+ * Fix segfaults on Ruby 2.7
31
+
32
+ ### 0.36.2 / 2020-05-28
33
+
34
+ #### Documentation
35
+
36
+ * Fix a few broken links
37
+
38
+ ### 0.36.1 / 2020-05-19
39
+
40
+ #### Bug Fixes
41
+
42
+ * Adjusted some default timeout and retry settings
43
+
44
+ ### 0.36.0 / 2020-03-11
45
+
46
+ #### Features
47
+
48
+ * Support separate project setting for quota/billing
49
+
50
+ ### 0.35.2 / 2020-01-23
51
+
52
+ #### Documentation
53
+
54
+ * Update copyright year
55
+
56
+ ### 0.35.1 / 2019-11-06
57
+
58
+ #### Bug Fixes
59
+
60
+ * Update minimum runtime dependencies
61
+
62
+ ### 0.35.0 / 2019-10-29
63
+
64
+ This release requires Ruby 2.4 or later.
65
+
66
+ #### Documentation
67
+
68
+ * Clarify which Google Cloud Platform environments support automatic authentication
69
+
70
+ #### Performance Improvements
71
+
72
+ * Update lower-level client network configuration
73
+
74
+ ### 0.34.0 / 2019-08-23
75
+
76
+ #### Features
77
+
78
+ * Support overriding of service endpoint
79
+
80
+ ### 0.33.7 / 2019-07-31
81
+
82
+ * Fix max threads setting in thread pools
83
+ * Thread pools once again limit the number of threads allocated.
84
+ * Update documentation links
85
+
86
+ ### 0.33.6 / 2019-07-08
87
+
88
+ * Support overriding service host and port in the low-level client.
89
+
90
+ ### 0.33.5 / 2019-06-11
91
+
92
+ * Google::Cloud::Env provides additional configuration options including retries and cache control
93
+ * Add VERSION constant
94
+
95
+ ### 0.33.4 / 2019-04-29
96
+
97
+ * Add AUTHENTICATION.md guide.
98
+ * Update documentation for common types.
99
+ * Extract gRPC header values from request.
100
+
101
+ ### 0.33.3 / 2019-02-13
102
+
103
+ * Fix bug (typo) in retrieving default on_error proc.
104
+
105
+ ### 0.33.2 / 2019-02-08
106
+
107
+ * Fix conversion code for ErrorEvent and Debugee.
108
+ * Prepare for changes in JSON serialization coming in
109
+ google-protobuf 3.7.
110
+
111
+ ### 0.33.1 / 2019-02-07
112
+
113
+ * Update concurrent-ruby dependency
114
+
115
+ ### 0.33.0 / 2019-02-01
116
+
117
+ * Add Debugger on_error configuration.
118
+ * Update Transmitter
119
+ * Add dependency on current-ruby.
120
+ * Add Transmitter#on_error method.
121
+ * Update Transmitter documentation.
122
+ * Make use of Credentials#project_id
123
+ * Use Credentials#project_id
124
+ If a project_id is not provided, use the value on the Credentials object.
125
+ This value was added in googleauth 0.7.0.
126
+ * Loosen googleauth dependency
127
+ Allow for new releases up to 0.10.
128
+ The googleauth devs have committed to maintaining the current API
129
+ and will not make backwards compatible changes before 0.10.
130
+
131
+ ### 0.32.6 / 2018-11-15
132
+
133
+ * Update network configuration.
134
+
135
+ ### 0.32.5 / 2018-09-20
136
+
137
+ * Update documentation.
138
+ * Change documentation URL to googleapis GitHub org.
139
+ * Fix circular require warning.
140
+
141
+ ### 0.32.4 / 2018-09-12
142
+
143
+ * Add missing documentation files to package.
144
+
145
+ ### 0.32.3 / 2018-09-10
146
+
147
+ * Update documentation.
148
+
149
+ ### 0.32.2 / 2018-08-21
150
+
151
+ * Update documentation.
152
+
153
+ ### 0.32.1 / 2018-07-05
154
+
155
+ * Fix issue when disabling Stackdriver components with Rails.env.production.
156
+ * Add documentation for enabling gRPC logging.
157
+
158
+ ### 0.32.0 / 2018-05-24
159
+
160
+ * Delay starting the debugger agent until the first request to ensure it
161
+ happens after workers are forked. Should prevent grpc from malfunctioning in
162
+ this case.
163
+
164
+ ### 0.31.0 / 2018-02-27
165
+
166
+ * Use Google Cloud Shared Configuration.
167
+ * Fix for mutation detection using Ruby 2.5.
168
+ * Support disabling mutation detection in debugger evaluation.
169
+
170
+ ### 0.30.0 / 2017-12-19
171
+
172
+ * Update google-gax dependency to 1.0.
173
+
174
+ ### 0.29.1 / 2017-11-15
175
+
176
+ * Fix credentials verification bug in Railtie.
177
+
178
+ ### 0.29.0 / 2017-11-14
179
+
180
+ * Add `Google::Cloud::Debugger::Credentials` class.
181
+ * Rename constructor arguments to `project_id` and `credentials`.
182
+ (The previous arguments `project` and `keyfile` are still supported.)
183
+ * Document `Google::Auth::Credentials` as `credentials` value.
184
+ * Add Debugger Agent Design Document.
185
+ * Updated `google-gax` (`grpc`, `google-protobuf`), `googleauth` dependencies.
186
+
187
+ ### 0.28.2 / 2017-09-28
188
+
189
+ * Improve Breakpoint tracer performance by not tracking C function calls in file tracing.
190
+ * Add a backoff behavior in the debuggee registration to reduce spamming requests when registrations fail.
191
+
192
+ ### 0.28.1 / 2017-09-08
193
+
194
+ * Print captured exception from asynchronous worker threads.
195
+
196
+ ### 0.28.0 / 2017-08-25
197
+
198
+ * Support single file Rack-based applications.
199
+ * Support none-Rack-based Ruby applications.
200
+ * API Breaking Change:
201
+ * `module_name` initialization parameter renamed to `service_name`
202
+ * `module_version` initialization parameter renamed to `module_version`
203
+
204
+ ### 0.27.0 / 2017-08-07
205
+
206
+ * Optimize breakpoint evaluation memory usage by adopting shared variable table.
207
+ * Update breakpoint to error state if the breakpoint is set at an invalid position or
208
+ if condition evaluation fail with an error.
209
+ * Set errored variable evaluation to error state.
210
+ * Restrict the amount of time spent on evaluating breakpoints within each rack application request.
211
+ * Restrict total memory usage on collecting variables within each breakpoint evaluation. Prioritize
212
+ memory allocation to user defined variables over local variables.
213
+
214
+ ### 0.26.1 / 2017-07-11
215
+
216
+ * stackdriver-core 1.2.0 release
217
+
218
+ ### 0.26.0 / 2017-07-11
219
+
220
+ * Update GAPIC configuration to exclude `UNAVAILABLE` errors from automatic retry.
221
+
222
+ ### 0.25.0 / 2017-05-25
223
+
224
+ * Introduce new `Google::Cloud::Debugger.configure` instrumentation configuration interface.
225
+
226
+ ### 0.24.1 / 2017-04-07
227
+
228
+ * Fixed Google::Cloud::Debugger::Railtie initialization on non-GCP environments
229
+ to not interfere with Rails startup
230
+
231
+ ### 0.24.0 / 2017-04-06
232
+
233
+ * First release
@@ -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/)