Skip to content
This repository was archived by the owner on Apr 3, 2024. It is now read-only.

Commit b5b691f

Browse files
ofrobotsofrobots
authored
move config to src/agent and add jsdocs (#196)
1 parent 4dc2aa0 commit b5b691f

15 files changed

+224
-118
lines changed

‎README.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -73,15 +73,15 @@ If your application is running outside of Google Cloud Platform, such as locally
7373
});
7474
```
7575

76-
See the [default configuration](https://github.com/GoogleCloudPlatform/cloud-debug-nodejs/blob/master/config.js) for more details.
76+
See the [default configuration][config-js] for more details.
7777

7878
1. Generate a `source-context.json` file which contains information about the version of the source code used to build the application. This file should be located in the root directory of your application. When you open the Stackdriver Debugger in the Cloud Platform Console, it uses the information in this file to display the correct version of the source.
7979

8080
gcloud beta debug source gen-repo-info-file
8181

8282
## Configuration
8383

84-
See [the default configuration](config.js) for a list of possible configuration options. These options can be passed to the agent through the object argument to the start command as shown below:
84+
See [the default configuration][config-js] for a list of possible configuration options. These options can be passed to the agent through the object argument to the start command as shown below:
8585

8686
require('@google/cloud-debug').start({
8787
logLevel: 2,
@@ -135,3 +135,4 @@ As soon as that line of code is reached in any of the running instances of your
135135
[david-dev-url]: https://david-dm.org/GoogleCloudPlatform/cloud-debug-nodejs?type=dev
136136
[snyk-image]: https://snyk.io/test/github/GoogleCloudPlatform/cloud-debug-nodejs/badge.svg
137137
[snyk-url]: https://snyk.io/test/github/GoogleCloudPlatform/cloud-debug-nodejs
138+
[config-js]: https://github.com/GoogleCloudPlatform/cloud-debug-nodejs/blob/master/src/agent/config.js

‎src/agent/config.js‎

Lines changed: 206 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,206 @@
1+
/**
2+
* Copyright 2015 Google Inc. All Rights Reserved.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
'use strict';
17+
18+
/**
19+
* @typedef {object} DebugAgentConfig
20+
*/
21+
22+
module.exports = {
23+
/**
24+
* @property {boolean} Whether the debug agent should be started.
25+
* @memberof DebugAgentConfig
26+
* @default
27+
*/
28+
enabled: true,
29+
30+
// FIXME(ofrobots): presently this is dependent what cwd() is at the time this
31+
// file is first required. We should make the default config static.
32+
/**
33+
* @property {?string}
34+
* @memberof DebugAgentConfig
35+
* @default
36+
*/
37+
workingDirectory: process.cwd(),
38+
39+
/**
40+
* @property {?string} A user specified way of identifying the service
41+
* that the debug agent is monitoring.
42+
* @memberof DebugAgentConfig
43+
* @default
44+
*/
45+
description: null,
46+
47+
// FIXME(ofrobots): today we prioritize GAE_MODULE_NAME/GAE_MODULE_VERSION
48+
// over the user specified config. We should reverse that.
49+
/**
50+
* @property {object} Identifies the context of the running service -
51+
* [ServiceContext](https://cloud.google.com/error-reporting/reference/rest/v1beta1/ServiceContext?authuser=2).
52+
* This information is utilized in the UI to identify all the running
53+
* instances of your service. This is discovered automatically when your
54+
* application is running on Google Cloud Platform. You may optionally choose
55+
* to provide this information yourself to identify your service differently
56+
* from the default mechanism.
57+
* @memberof DebugAgentConfig
58+
* @default
59+
*/
60+
serviceContext: {
61+
/**
62+
* @property {?string} the service name
63+
* @default
64+
*/
65+
service: null,
66+
67+
/**
68+
* @property {?string} the service version
69+
* @default
70+
*/
71+
version: null
72+
},
73+
74+
/**
75+
* @property {?string} The path within your repository to the directory
76+
* containing the package.json for your deployed application. This should be
77+
* provided if your deployed application appears as a subdirectory of your
78+
* repository. Usually this is unnecessary, but may be useful in cases where
79+
* the debug agent is unable to resolve breakpoint locations unambiguously.
80+
* @memberof DebugAgentConfig
81+
* @default
82+
*/
83+
appPathRelativeToRepository: null,
84+
85+
/**
86+
* @property {number} agent log level 0-disabled, 1-error, 2-warn, 3-info,
87+
* 4-debug
88+
* @memberof DebugAgentConfig
89+
* @default
90+
*/
91+
logLevel: 1,
92+
93+
/**
94+
* @property {number} How frequently should the list of breakpoints be
95+
* refreshed from the cloud debug server.
96+
* @memberof DebugAgentConfig
97+
* @default
98+
*/
99+
breakpointUpdateIntervalSec: 10,
100+
101+
/**
102+
* @property {number} breakpoints and logpoints older than this number of
103+
* seconds will be expired on the server.
104+
* @memberof DebugAgentConfig
105+
* @default
106+
*/
107+
breakpointExpirationSec: 60 * 60 * 24, // 24 hours
108+
109+
/**
110+
* @property {object} configuration options on what is captured on a
111+
* snapshot.
112+
* @memberof DebugAgentConfig
113+
*/
114+
capture: {
115+
/**
116+
* @property {boolean} Whether to include details about stack frames
117+
* belonging to node-core.
118+
* @default
119+
*/
120+
includeNodeModules: false,
121+
122+
123+
/**
124+
* @property {number} Maximum number of stack frames to capture data for.
125+
* The limit is aimed to reduce overall capture time.
126+
* @default
127+
*/
128+
maxFrames: 20,
129+
130+
/**
131+
* @property {number} We collect locals and arguments on a few top frames.
132+
* For the rest only collect the source location
133+
* @default
134+
*/
135+
maxExpandFrames: 5,
136+
137+
/**
138+
* @property {number} To reduce the overall capture time, limit the number
139+
* of properties gathered on large objects. A value of 0 disables the limit.
140+
* @default
141+
*/
142+
maxProperties: 10,
143+
144+
/**
145+
* @property {number} Total 'size' of data to gather. This is NOT the
146+
* number of bytes of data that are sent over the wire, but instead a very
147+
* very coarse approximation based on the length of names and values of the
148+
* properties. This should be somewhat proportional to the amount of
149+
* processing needed to capture the data and subsequently the network
150+
* traffic. A value of 0 disables the limit.
151+
* @default
152+
*/
153+
maxDataSize: 20000,
154+
155+
/**
156+
* @property {number} To limit the size of the buffer, we truncate long
157+
* strings. A value of 0 disables truncation.
158+
* @default
159+
*/
160+
maxStringLength: 100
161+
},
162+
163+
/**
164+
* @property {object} options affecting log points.
165+
* @memberof DebugAgentConfig
166+
*/
167+
log: {
168+
/**
169+
* @property {number} The maximum number of logs to record per second per
170+
* logpoint.
171+
* @memberof DebugAgentConfig
172+
* @default
173+
*/
174+
maxLogsPerSecond: 50,
175+
176+
/**
177+
* @property {number} Number of seconds to wait after the
178+
* `maxLogsPerSecond` rate is hit before logging resumes per logpoint.
179+
* @default
180+
*/
181+
logDelaySeconds: 1
182+
},
183+
184+
// FIXME(ofrobots): stop accepting this property here
185+
// A path to a key file relative to the current working directory. If this
186+
// field is set, the contents of the pointed file will be used for
187+
// authentication instead of your application default credentials.
188+
keyFilename: null,
189+
190+
// FIXME(ofrobots): stop accepting this property here
191+
// The contents of a key file. If this field is set, its contents will be
192+
// used for authentication instead of your application default credentials.
193+
// If keyFilename is also set, the value of credentials will be ignored.
194+
credentials: null,
195+
196+
/**
197+
* @property {object} These configuration options are for internal
198+
* experimentation only.
199+
* @memberof DebugAgentConfig
200+
* @private
201+
*/
202+
internal: {
203+
registerDelayOnFetcherErrorSec: 300, // 5 minutes.
204+
maxRegistrationRetryDelay: 40
205+
}
206+
};

‎src/config.js‎

Lines changed: 0 additions & 103 deletions
This file was deleted.

‎src/index.js‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,7 @@ util.inherits(Debug, common.Service);
6969
var initConfig = function(config_) {
7070
var config = config_ || {};
7171

72-
var defaults = require('./config.js').debug;
72+
var defaults = require('./agent/config.js');
7373
_.defaultsDeep(config, defaults);
7474
if (process.env.hasOwnProperty('GCLOUD_DEBUG_LOGLEVEL')) {
7575
config.logLevel = process.env.GCLOUD_DEBUG_LOGLEVEL;
@@ -105,6 +105,8 @@ Debug.prototype.startAgent = function(config) {
105105
if (debuglet) {
106106
throw new Error('Debug Agent has already been started');
107107
}
108+
109+
// FIXME(ofrobots): the initConfig logic belongs in the agent/ directory.
108110
config = initConfig(config);
109111
if (config.enabled) {
110112
debuglet = new Debuglet(

‎test/e2e/test-capture-time.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@
1818
var assert = require('assert');
1919
var request = require('request');
2020
var logger = require('@google/cloud-diagnostics-common').logger;
21-
var config = require('../../src/config.js').debug;
21+
var config = require('../../src/agent/config.js');
2222
var semver = require('semver');
2323
var Debuglet = require('../../src/debuglet.js');
2424

‎test/e2e/test-log-throttling.js‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -201,7 +201,7 @@ if (cluster.isMaster) {
201201
runTest();
202202
} else {
203203
var debug = require('../..')();
204-
var defaultConfig = require('../../src/config.js');
204+
var defaultConfig = require('../../src/agent/config.js');
205205
var config = extend({}, defaultConfig, {
206206
log: {
207207
maxLogsPerSecond: 2,
@@ -220,4 +220,4 @@ if (cluster.isMaster) {
220220
process.send([debuggee.id, debuggee.project]);
221221
setInterval(fib.bind(null, 12), 500);
222222
}, 7000);
223-
}
223+
}

‎test/standalone/test-config-credentials.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ var assert = require('assert');
2020
var nock = require('nock');
2121
var extend = require('extend');
2222
var logger = require('@google/cloud-diagnostics-common').logger;
23-
var defaultConfig = require('../../src/config.js').debug;
23+
var defaultConfig = require('../../src/agent/config.js');
2424
var Debuglet = require('../../src/agent/debuglet.js');
2525

2626
var envProject = process.env.GCLOUD_PROJECT;

‎test/standalone/test-debuglet.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@
1818
var assert = require('assert');
1919
var request = require('../auth-request.js');
2020
var loggerModule = require('@google/cloud-diagnostics-common').logger;
21-
var defaultConfig = require('../../src/config.js').debug;
21+
var defaultConfig = require('../../src/agent/config.js');
2222
var Debuglet = require('../../src/agent/debuglet.js');
2323
var extend = require('extend');
2424

0 commit comments

Comments
 (0)