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

Commit

Permalink
tune up configuration types (#300)
Browse files Browse the repository at this point in the history
  • Loading branch information
@ofrobots
ofrobots committed Jul 7, 2017
1 parent 9eb42e6 commit 2d07105
Show file tree
Hide file tree
Showing 6 changed files with 94 additions and 119 deletions.
133 changes: 42 additions & 91 deletions src/agent/config.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,207 +14,158 @@
* limitations under the License.
*/

/**
* @typedef {object} DebugAgentConfig
*/
export interface DebugAgentConfig {
/**
* @property {?string}
* @memberof DebugAgentConfig
* @default
*/
import {AuthenticationConfig} from '../types/common-types';

export interface DebugAgentConfig extends AuthenticationConfig {
workingDirectory: string|null;

/**
* @property {?string} A user specified way of identifying the service
* that the debug agent is monitoring.
* @memberof DebugAgentConfig
* @default
* A user specified way of identifying the service
*/
description: string|null;

/**
* @property {boolean} Whether or not it is permitted to evaluate expressions.
* Whether or not it is permitted to evaluate expressions.
* Locals and arguments are not displayed and watch expressions and
* conditions are dissallowed when this is `false`.
* @memberof DebugAgentConfig
* @default
*/
allowExpressions: boolean;

/**
* @property {object} Identifies the context of the running service -
* 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
* The service name.
*/
service: string | null;

/**
* @property {?string} the service version
* @default
* The service version.
*/
version: string | null;

/**
* @property {?string} a unique deployment identifier. This is used
* internally only.
* @private
* A unique deployment identifier. This is used internally only.
*/
minorVersion_: string | null;
};

/**
* @property {?string} The path within your repository to the directory
* 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: string|null;

/**
* @property {number} agent log level 0-disabled, 1-error, 2-warn, 3-info,
* 4-debug
* @memberof DebugAgentConfig
* @default
* agent log level 0-disabled, 1-error, 2-warn, 3-info, 4-debug
*/
logLevel: number;

/**
* @property {number} How frequently should the list of breakpoints be
* refreshed from the cloud debug server.
* @memberof DebugAgentConfig
* @default
* How frequently should the list of breakpoints be refreshed from the cloud
* debug server.
*/
breakpointUpdateIntervalSec: number;

/**
* @property {number} breakpoints and logpoints older than this number of
* seconds will be expired on the server.
* @memberof DebugAgentConfig
* @default
* breakpoints and logpoints older than this number of seconds will be expired
* on the server.
*/
breakpointExpirationSec: number;

/**
* @property {object} configuration options on what is captured on a
* snapshot.
* @memberof DebugAgentConfig
* configuration options on what is captured on a snapshot.
*/
capture: {
/**
* @property {boolean} Whether to include details about stack frames
* belonging to node-core.
* @default
* Whether to include details about stack frames belonging to node-core.
*/
includeNodeModules: boolean;


/**
* @property {number} Maximum number of stack frames to capture data for.
* The limit is aimed to reduce overall capture time.
* @default
* Maximum number of stack frames to capture data for. The limit is aimed to
* reduce overall capture time.
*/
maxFrames: number;

/**
* @property {number} We collect locals and arguments on a few top frames.
* For the rest only collect the source location
* @default
* We collect locals and arguments on a few top frames. For the rest only
* collect the source location
*/
maxExpandFrames: number;

/**
* @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
* To reduce the overall capture time, limit the number of properties
* gathered on large objects. A value of 0 disables the limit.
*/
maxProperties: number;

/**
* @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
* 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: number;

/**
* @property {number} To limit the size of the buffer, we truncate long
* strings. A value of 0 disables truncation.
* @default
* To limit the size of the buffer, we truncate long strings. A value of 0
* disables truncation.
*/
maxStringLength: number;
};

/**
* @property {object} options affecting log points.
* @memberof DebugAgentConfig
* options affecting log points.
*/
log: {
/**
* @property {number} The maximum number of logs to record per second per
* logpoint.
* @memberof DebugAgentConfig
* @default
* The maximum number of logs to record per second per logpoint.
*/
maxLogsPerSecond: number;

/**
* @property {number} Number of seconds to wait after the
* `maxLogsPerSecond` rate is hit before logging resumes per logpoint.
* @default
* Number of seconds to wait after the `maxLogsPerSecond` rate is hit before
* logging resumes per logpoint.
*/
logDelaySeconds: number;
};

/**
* @property {object} These configuration options are for internal
* experimentation only.
* @memberof DebugAgentConfig
* @private
* These configuration options are for internal experimentation only.
*/
internal: {
// TODO: Determine if clang-format can be configured to place
// a newline between these two statements.
registerDelayOnFetcherErrorSec: number; maxRegistrationRetryDelay: number;
};

/**
* @property {boolean} Used by tests to force loading of a new agent if one
* exists already
* @memberof DebugAgentConfig
* @private
* Used by tests to force loading of a new agent if one exists already
*/
forceNewAgent_: boolean;

/**
* @property {boolean} Uses by tests to cause the start() function to return
* the debuglet.
* @memberof DebugAgentConfig
* @private
* Uses by tests to cause the start() function to return the debuglet.
*/
testMode_: boolean;
}

export interface StackdriverConfig extends AuthenticationConfig {
debug?: DebugAgentConfig;
}

const defaultConfig: DebugAgentConfig = {
// FIXME(ofrobots): presently this is dependent what cwd() is at the time this
// file is first required. We should make the default config static.
Expand Down
3 changes: 2 additions & 1 deletion src/agent/debuglet.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -392,7 +392,8 @@ export class Debuglet extends EventEmitter {
// named `response`) is not used.
metadata.project(
'project-id',
function(err: Error, _res: http.ServerResponse, metadataProject: string) {
function(
err: Error, _res: http.ServerResponse, metadataProject: string) {
// We should get an error if we are not on GCP.
const onGCP = !err;

Expand Down
13 changes: 7 additions & 6 deletions src/agent/scanner.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -207,12 +207,13 @@ function findFiles(
return;
});

find.on('directory', function(dir: string, _ignore: fs.Stats, stop: () => void) {
const base = path.basename(dir);
if (base === '.git' || base === 'node_modules') {
stop(); // do not descend
}
});
find.on(
'directory', function(dir: string, _ignore: fs.Stats, stop: () => void) {
const base = path.basename(dir);
if (base === '.git' || base === 'node_modules') {
stop(); // do not descend
}
});

find.on('file', function(file: string) {
if (regex.test(file)) {
Expand Down
8 changes: 4 additions & 4 deletions src/debug.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,11 +14,11 @@
* limitations under the License.
*/

import {AuthOptions, Common} from './types/common-types';
import {AuthenticationConfig, Common} from './types/common-types';
export const common: Common = require('@google-cloud/common');

export class Debug extends common.Service {
options: AuthOptions;
options: AuthenticationConfig;

/**
* <p class="notice">
Expand All @@ -41,9 +41,9 @@ export class Debug extends common.Service {
* @resource [What is Stackdriver Debug]{@link
* https://cloud.google.com/debug/}
*
* @param {object} options - [Configuration object](#/docs)
* @param options - [Authentication options](#/docs)
*/
constructor(options: AuthOptions) {
constructor(options: AuthenticationConfig) {
if (new.target !== Debug) {
options = common.util.normalizeArguments(null, options);
return new Debug(options);
Expand Down
20 changes: 7 additions & 13 deletions src/index.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,10 +14,9 @@
* limitations under the License.
*/

import {DebugAgentConfig} from './agent/config';
import {DebugAgentConfig, StackdriverConfig} from './agent/config';
import {Debuglet} from './agent/debuglet';
import {Debug} from './debug';
import {AuthOptions} from './types/common-types';

// Singleton.
let debuglet: Debuglet;
Expand All @@ -26,31 +25,26 @@ let debuglet: Debuglet;
* Start the Debug agent that will make your application available for debugging
* with Stackdriver Debug.
*
* @param {object=} options - Options
* @param {object=} options.debugAgent - Debug agent configuration
* TODO: add an optional callback function.
* @param options - Authentication and agent configuration.
*
* @resource [Introductory video]{@link
* https://www.youtube.com/watch?v=tyHcK_kAOpw}
*
* @example
* debug.startAgent();
*/
export function start(options: DebugAgentConfig|
{debug?: DebugAgentConfig}): Debuglet|undefined {
export function start(options: DebugAgentConfig|StackdriverConfig): Debuglet|
undefined {
options = options || {};
// TODO: Update the documentation to specify that the options object
// contains a `debug` attribute and not a `debugAgent` object.
// TODO: Determine how to remove this cast to `any`.
const agentConfig = (options as any).debug || options;
const agentConfig: DebugAgentConfig =
(options as StackdriverConfig).debug || (options as DebugAgentConfig);

// forceNewAgent_ is for testing purposes only.
if (debuglet && !agentConfig.forceNewAgent_) {
throw new Error('Debug Agent has already been started');
}

// TODO: Determine how to remove this cast to `AuthOptions`.
const debug = new Debug(options as AuthOptions);
const debug = new Debug(options);
debuglet = new Debuglet(debug, agentConfig);
debuglet.start();

Expand Down
Loading

0 comments on commit 2d07105

Please sign in to comment.