diff --git a/README.md b/README.md index 81ca71f8..2ebd1498 100644 --- a/README.md +++ b/README.md @@ -73,7 +73,7 @@ If your application is running outside of Google Cloud Platform, such as locally }); ``` - See the [default configuration](https://github.com/GoogleCloudPlatform/cloud-debug-nodejs/blob/master/config.js) for more details. + See the [default configuration][config-js] for more details. 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. @@ -81,7 +81,7 @@ If your application is running outside of Google Cloud Platform, such as locally ## Configuration -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: +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: require('@google/cloud-debug').start({ logLevel: 2, @@ -135,3 +135,4 @@ As soon as that line of code is reached in any of the running instances of your [david-dev-url]: https://david-dm.org/GoogleCloudPlatform/cloud-debug-nodejs?type=dev [snyk-image]: https://snyk.io/test/github/GoogleCloudPlatform/cloud-debug-nodejs/badge.svg [snyk-url]: https://snyk.io/test/github/GoogleCloudPlatform/cloud-debug-nodejs +[config-js]: https://github.com/GoogleCloudPlatform/cloud-debug-nodejs/blob/master/src/agent/config.js diff --git a/src/agent/config.js b/src/agent/config.js new file mode 100644 index 00000000..9d9967d5 --- /dev/null +++ b/src/agent/config.js @@ -0,0 +1,206 @@ +/** + * Copyright 2015 Google Inc. All Rights Reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +'use strict'; + +/** + * @typedef {object} DebugAgentConfig + */ + +module.exports = { + /** + * @property {boolean} Whether the debug agent should be started. + * @memberof DebugAgentConfig + * @default + */ + enabled: true, + + // FIXME(ofrobots): presently this is dependent what cwd() is at the time this + // file is first required. We should make the default config static. + /** + * @property {?string} + * @memberof DebugAgentConfig + * @default + */ + workingDirectory: process.cwd(), + + /** + * @property {?string} A user specified way of identifying the service + * that the debug agent is monitoring. + * @memberof DebugAgentConfig + * @default + */ + description: null, + + // FIXME(ofrobots): today we prioritize GAE_MODULE_NAME/GAE_MODULE_VERSION + // over the user specified config. We should reverse that. + /** + * @property {object} Identifies the context of the running service - + * [ServiceContext](https://cloud.google.com/error-reporting/reference/rest/v1beta1/ServiceContext?authuser=2). + * This information is utilized in the UI to identify all the running + * instances of your service. This is discovered automatically when your + * application is running on Google Cloud Platform. You may optionally choose + * to provide this information yourself to identify your service differently + * from the default mechanism. + * @memberof DebugAgentConfig + * @default + */ + serviceContext: { + /** + * @property {?string} the service name + * @default + */ + service: null, + + /** + * @property {?string} the service version + * @default + */ + version: null + }, + + /** + * @property {?string} The path within your repository to the directory + * containing the package.json for your deployed application. This should be + * provided if your deployed application appears as a subdirectory of your + * repository. Usually this is unnecessary, but may be useful in cases where + * the debug agent is unable to resolve breakpoint locations unambiguously. + * @memberof DebugAgentConfig + * @default + */ + appPathRelativeToRepository: null, + + /** + * @property {number} agent log level 0-disabled, 1-error, 2-warn, 3-info, + * 4-debug + * @memberof DebugAgentConfig + * @default + */ + logLevel: 1, + + /** + * @property {number} How frequently should the list of breakpoints be + * refreshed from the cloud debug server. + * @memberof DebugAgentConfig + * @default + */ + breakpointUpdateIntervalSec: 10, + + /** + * @property {number} breakpoints and logpoints older than this number of + * seconds will be expired on the server. + * @memberof DebugAgentConfig + * @default + */ + breakpointExpirationSec: 60 * 60 * 24, // 24 hours + + /** + * @property {object} configuration options on what is captured on a + * snapshot. + * @memberof DebugAgentConfig + */ + capture: { + /** + * @property {boolean} Whether to include details about stack frames + * belonging to node-core. + * @default + */ + includeNodeModules: false, + + + /** + * @property {number} Maximum number of stack frames to capture data for. + * The limit is aimed to reduce overall capture time. + * @default + */ + maxFrames: 20, + + /** + * @property {number} We collect locals and arguments on a few top frames. + * For the rest only collect the source location + * @default + */ + maxExpandFrames: 5, + + /** + * @property {number} To reduce the overall capture time, limit the number + * of properties gathered on large objects. A value of 0 disables the limit. + * @default + */ + maxProperties: 10, + + /** + * @property {number} Total 'size' of data to gather. This is NOT the + * number of bytes of data that are sent over the wire, but instead a very + * very coarse approximation based on the length of names and values of the + * properties. This should be somewhat proportional to the amount of + * processing needed to capture the data and subsequently the network + * traffic. A value of 0 disables the limit. + * @default + */ + maxDataSize: 20000, + + /** + * @property {number} To limit the size of the buffer, we truncate long + * strings. A value of 0 disables truncation. + * @default + */ + maxStringLength: 100 + }, + + /** + * @property {object} options affecting log points. + * @memberof DebugAgentConfig + */ + log: { + /** + * @property {number} The maximum number of logs to record per second per + * logpoint. + * @memberof DebugAgentConfig + * @default + */ + maxLogsPerSecond: 50, + + /** + * @property {number} Number of seconds to wait after the + * `maxLogsPerSecond` rate is hit before logging resumes per logpoint. + * @default + */ + logDelaySeconds: 1 + }, + + // FIXME(ofrobots): stop accepting this property here + // A path to a key file relative to the current working directory. If this + // field is set, the contents of the pointed file will be used for + // authentication instead of your application default credentials. + keyFilename: null, + + // FIXME(ofrobots): stop accepting this property here + // The contents of a key file. If this field is set, its contents will be + // used for authentication instead of your application default credentials. + // If keyFilename is also set, the value of credentials will be ignored. + credentials: null, + + /** + * @property {object} These configuration options are for internal + * experimentation only. + * @memberof DebugAgentConfig + * @private + */ + internal: { + registerDelayOnFetcherErrorSec: 300, // 5 minutes. + maxRegistrationRetryDelay: 40 + } +}; diff --git a/src/config.js b/src/config.js deleted file mode 100644 index a0171d8b..00000000 --- a/src/config.js +++ /dev/null @@ -1,103 +0,0 @@ -/** - * Copyright 2015 Google Inc. All Rights Reserved. - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ -'use strict'; - -// Default configuration -module.exports = { - debug: { - enabled: true, - workingDirectory: process.cwd(), - - // An identifier for the current code deployment. - description: undefined, - - serviceContext: { - // An identifier for the deployed application's service name - service: undefined, - - // An identifier for the deployed application's version - version: undefined - }, - - // The path within your repository to the directory containing the - // package.json for your deployed application. This should be provided - // if your deployed application appears as a subdirectory of your repository. - appPathRelativeToRepository: undefined, - - // Log levels: 0-disabled,1-error,2-warn,3-info,4-debug. - logLevel: 1, - - // How frequently should the list of breakpoints be refreshed from the - // cloud debug server. - breakpointUpdateIntervalSec: 10, - - // We expire stale breakpoints on the server. - breakpointExpirationSec: 60 * 60 * 24, // 24 hours - - capture: { - // Whether to include details about stack frames belonging to node-core. - includeNodeModules: false, - - // Maximum number of stack frames to capture data for. The limit is aimed - // to reduce overall capture time - maxFrames: 20, - - // Only collect locals and arguments on a few top frames. For the rest - // only collect the source location - maxExpandFrames: 5, - - // To reduce the overall capture time, limit the number of properties - // gathered on large object. A value of 0 disables the limit. - maxProperties: 10, - - // Total 'size' of data to gather. This is NOT the number of bytes of data - // that are sent over the wire, but instead a very very coarse approximation - // based on the length of names and values of the properties. This should - // be somewhat proportional to the amount of processing needed to capture - // the data and subsequently the network traffic. A value of 0 disables the - // limit. - maxDataSize: 20000, - - // To limit the size of the buffer, we truncate long strings. - // A value of 0 disables truncation. - maxStringLength: 100 - }, - - log: { - // The maximum number of logs to record per second per logpoint. - maxLogsPerSecond: 50, - // Number of seconds to wait after the `maxLogsPerSecond` rate is hit before - // logging resumes per logpoint. - logDelaySeconds: 1 - }, - - // A path to a key file relative to the current working directory. If this - // field is set, the contents of the pointed file will be used for - // authentication instead of your application default credentials. - keyFilename: null, - - // The contents of a key file. If this field is set, its contents will be - // used for authentication instead of your application default credentials. - // If keyFilename is also set, the value of credentials will be ignored. - credentials: null, - - // These configuration options are for internal experimentation only. - internal: { - registerDelayOnFetcherErrorSec: 300, // 5 minutes. - maxRegistrationRetryDelay: 40 - } - } -}; diff --git a/src/index.js b/src/index.js index 0bf03b18..2ce251c8 100644 --- a/src/index.js +++ b/src/index.js @@ -69,7 +69,7 @@ util.inherits(Debug, common.Service); var initConfig = function(config_) { var config = config_ || {}; - var defaults = require('./config.js').debug; + var defaults = require('./agent/config.js'); _.defaultsDeep(config, defaults); if (process.env.hasOwnProperty('GCLOUD_DEBUG_LOGLEVEL')) { config.logLevel = process.env.GCLOUD_DEBUG_LOGLEVEL; @@ -105,6 +105,8 @@ Debug.prototype.startAgent = function(config) { if (debuglet) { throw new Error('Debug Agent has already been started'); } + + // FIXME(ofrobots): the initConfig logic belongs in the agent/ directory. config = initConfig(config); if (config.enabled) { debuglet = new Debuglet( diff --git a/test/e2e/test-capture-time.js b/test/e2e/test-capture-time.js index 81a9c39e..e4796e05 100644 --- a/test/e2e/test-capture-time.js +++ b/test/e2e/test-capture-time.js @@ -18,7 +18,7 @@ var assert = require('assert'); var request = require('request'); var logger = require('@google/cloud-diagnostics-common').logger; -var config = require('../../src/config.js').debug; +var config = require('../../src/agent/config.js'); var semver = require('semver'); var Debuglet = require('../../src/debuglet.js'); diff --git a/test/e2e/test-log-throttling.js b/test/e2e/test-log-throttling.js index 945b2025..4dd1e2c8 100644 --- a/test/e2e/test-log-throttling.js +++ b/test/e2e/test-log-throttling.js @@ -201,7 +201,7 @@ if (cluster.isMaster) { runTest(); } else { var debug = require('../..')(); - var defaultConfig = require('../../src/config.js'); + var defaultConfig = require('../../src/agent/config.js'); var config = extend({}, defaultConfig, { log: { maxLogsPerSecond: 2, @@ -220,4 +220,4 @@ if (cluster.isMaster) { process.send([debuggee.id, debuggee.project]); setInterval(fib.bind(null, 12), 500); }, 7000); -} \ No newline at end of file +} diff --git a/test/standalone/test-config-credentials.js b/test/standalone/test-config-credentials.js index 3a251e86..b6f3dd36 100644 --- a/test/standalone/test-config-credentials.js +++ b/test/standalone/test-config-credentials.js @@ -20,7 +20,7 @@ var assert = require('assert'); var nock = require('nock'); var extend = require('extend'); var logger = require('@google/cloud-diagnostics-common').logger; -var defaultConfig = require('../../src/config.js').debug; +var defaultConfig = require('../../src/agent/config.js'); var Debuglet = require('../../src/agent/debuglet.js'); var envProject = process.env.GCLOUD_PROJECT; diff --git a/test/standalone/test-debuglet.js b/test/standalone/test-debuglet.js index c879f288..fb2cddee 100644 --- a/test/standalone/test-debuglet.js +++ b/test/standalone/test-debuglet.js @@ -18,7 +18,7 @@ var assert = require('assert'); var request = require('../auth-request.js'); var loggerModule = require('@google/cloud-diagnostics-common').logger; -var defaultConfig = require('../../src/config.js').debug; +var defaultConfig = require('../../src/agent/config.js'); var Debuglet = require('../../src/agent/debuglet.js'); var extend = require('extend'); diff --git a/test/standalone/test-duplicate-expressions.js b/test/standalone/test-duplicate-expressions.js index e51c0de4..a8e7905a 100644 --- a/test/standalone/test-duplicate-expressions.js +++ b/test/standalone/test-duplicate-expressions.js @@ -29,7 +29,7 @@ var breakpointInFoo = { var assert = require('assert'); var v8debugapi = require('../../src/agent/v8debugapi.js'); var logModule = require('@google/cloud-diagnostics-common').logger; -var config = require('../../src/config.js').debug; +var config = require('../../src/agent/config.js'); var SourceMapper = require('../../src/agent/sourcemapper.js'); var scanner = require('../../src/agent/scanner.js'); var path = require('path'); diff --git a/test/standalone/test-duplicate-nested-expressions.js b/test/standalone/test-duplicate-nested-expressions.js index f5924132..d65d5e93 100644 --- a/test/standalone/test-duplicate-nested-expressions.js +++ b/test/standalone/test-duplicate-nested-expressions.js @@ -27,7 +27,7 @@ var assert = require('assert'); var v8debugapi = require('../../src/agent/v8debugapi.js'); var logModule = require('@google/cloud-diagnostics-common').logger; -var config = require('../../src/config.js').debug; +var config = require('../../src/agent/config.js'); var SourceMapper = require('../../src/agent/sourcemapper.js'); var scanner = require('../../src/agent/scanner.js'); var path = require('path'); diff --git a/test/standalone/test-fat-arrow.js b/test/standalone/test-fat-arrow.js index 40455c5d..3cc34a56 100644 --- a/test/standalone/test-fat-arrow.js +++ b/test/standalone/test-fat-arrow.js @@ -18,7 +18,7 @@ var assert = require('assert'); var v8debugapi = require('../../src/agent/v8debugapi.js'); var logModule = require('@google/cloud-diagnostics-common').logger; -var config = require('../../src/config.js').debug; +var config = require('../../src/agent/config.js'); var SourceMapper = require('../../src/agent/sourcemapper.js'); var scanner = require('../../src/agent/scanner.js'); var path = require('path'); diff --git a/test/standalone/test-max-data-size.js b/test/standalone/test-max-data-size.js index 85895dbe..c56f275d 100644 --- a/test/standalone/test-max-data-size.js +++ b/test/standalone/test-max-data-size.js @@ -26,7 +26,7 @@ var logModule = require('@google/cloud-diagnostics-common').logger; var v8debugapi = require('../../src/agent/v8debugapi.js'); var SourceMapper = require('../../src/agent/sourcemapper.js'); var scanner = require('../../src/agent/scanner.js'); -var config = require('../../src/config.js').debug; +var config = require('../../src/agent/config.js'); var api; var breakpointInFoo = { diff --git a/test/standalone/test-this-context.js b/test/standalone/test-this-context.js index 992c55c6..0192ac1a 100644 --- a/test/standalone/test-this-context.js +++ b/test/standalone/test-this-context.js @@ -27,7 +27,7 @@ var assert = require('assert'); var v8debugapi = require('../../src/agent/v8debugapi.js'); var logModule = require('@google/cloud-diagnostics-common').logger; -var config = require('../../src/config.js').debug; +var config = require('../../src/agent/config.js'); var SourceMapper = require('../../src/agent/sourcemapper.js'); var scanner = require('../../src/agent/scanner.js'); var path = require('path'); diff --git a/test/standalone/test-try-catch.js b/test/standalone/test-try-catch.js index 87e4caeb..535fa546 100644 --- a/test/standalone/test-try-catch.js +++ b/test/standalone/test-try-catch.js @@ -27,7 +27,7 @@ var assert = require('assert'); var v8debugapi = require('../../src/agent/v8debugapi.js'); var logModule = require('@google/cloud-diagnostics-common').logger; -var config = require('../../src/config.js').debug; +var config = require('../../src/agent/config.js'); var SourceMapper = require('../../src/agent/sourcemapper.js'); var scanner = require('../../src/agent/scanner.js'); var path = require('path'); diff --git a/test/test-v8debugapi.js b/test/test-v8debugapi.js index 965790ef..e9494037 100644 --- a/test/test-v8debugapi.js +++ b/test/test-v8debugapi.js @@ -34,7 +34,7 @@ var MAX_INT = 2147483647; // Max signed int32. var assert = require('assert'); var v8debugapi = require('../src/agent/v8debugapi.js'); var logModule = require('@google/cloud-diagnostics-common').logger; -var config = require('../src/config.js').debug; +var config = require('../src/agent/config.js'); var StatusMessage = require('../src/status-message.js'); var scanner = require('../src/agent/scanner.js'); var SourceMapper = require('../src/agent/sourcemapper.js');