Configuration

Customizing Glimpse for Node.js

In most cases, Glimpse should work “out of the box” with no configuration needed. However, Glimpse does include a few knobs that can be turned to customize how Glimpse interacts with your application. You can configure Glimpse using configuration files, environment variables, and command-line arguments (or a combination of the three).

Settings

  • agent.validate-packages.enabled: (boolean)

    Glimpse requires that it be imported and initialized prior to importing any other instrumented package, otherwise it may not capture that package’s activity. When enabled, Glimpse will generate warnings on the console for any package that is imported prior to Glimpse initialization. Change this setting if you do not want warnings written to the console.

    Defaults to true.

  • agent.validate-packages.excludedPackages: (array)

    When agent.validate-packages.enabled is true, this setting can be used to prevent Glimpse from generating warnings for specific packages. Change this setting if your application must import packages prior to initializing Glimpse and those imports will not affect Glimpse instrumentation.

    Defaults to excluding the Glimpse packages:

    [
        { "packageName": "@glimpse/glimpse" },
        { "packageName": "@glimpse/glimpse-common" },
        { "packageName": "@glimpse/glimpse-agent-node" },
        { "packageName": "@glimpse/glimpse-server" }
    ]
    
  • inspector.http.body.capture.maxsize: (number)

    The maximum size, in bytes, of request or response body captured by the Glimpse agent. Bodies larger than this value will appear truncated in the Glimpse client. Change this setting if you want to capture more (or less) of your application’s request or response bodies.

    Defaults to 132000.

    Note: this value must be smaller than server.max.json.body.size.

  • instrumentor.console.stack-capture.size: (number)

    The maximum number of frames of a given call stack captured by Glimpse. Change this setting if you want to capture more (or less) frames (e.g. to help locate an executing piece of code).

    Defaults to 10.

  • proxy.<package>.enabled: (boolean)

    When present, determines whether a specific package is instrumented by Glimpse. Add or change this setting if you do not want Glimpse to instrument a package.

    Defaults to true.

  • server.protocol: (http | https)

    When present, determines the protocol used for URLs generated by Glimpse (e.g. in metadata returned by the Glimpse server to be used by the Glimpse client). Change this setting in cases where the protocol of the request made of the application does not necessarily match the protocol of the request made by the client. For example, when the application sits behind a proxy exposed via HTTPS, where the application itself is exposed via HTTP.

    Defaults to the protocol of the request.

  • server.max.json.body.size: (number)

    The maximum size, in bytes, of request bodies processed by the Glimpse server. Change this setting to allow the server to capture larger application activity (such as with large request or response bodies).

    Defaults to 135000.

    Note: this setting must be larger than inspector.http.body.capture.maxsize.

  • telemetry.enabled: (boolean)

    Determines whether limited and anonymous metrics related your use of Glimpse is captured and reported to the Glimpse team. Change this setting if you do not want telemetry sent. See our privacy policy for more information about the telemetry data collected by Glimpse.

    Defaults to true.

  • telemetry.identity.salt: (string) When present, adds a custom “salt” to the machine ID hash generated by Glimpse and used for telemetry purposes. Change this setting to further obscure identification of any given machine.

    Defaults to undefined.

Configuration files

When initialized, Glimpse will search the application folder for a glimpse.config.json file. If present, this file will be used as a source of custom Glimpse settings. The file schema is a JSON object with properties that correspond to each setting name with values being the appropriate type for the setting.

glimpse.config.json:

{
    "server.protocol": "https"
}

Configuration environment variables

You can pass simple settings to Glimpse via environment variables. Use the GLIMPSE_ prefix for each setting. Environment variables have higher precedence than configuration files.

export GLIMPSE_server.protocol=https
node app.js

Configuration command-line arguments

You can pass simple settings to Glimpse via the command line when starting your application. Use the --Glimpse_ prefix for each setting. Command-line arguments have higher precedence than both environment variables configuration files.

node app.js --GLIMPSE_server.protocol https

Ignoring Express routes and middleware

There may be certain routes or middleware in your application that you want Glimpse to ignore. You can instruct Glimpse to ignore their execution by attaching a glimpse object to the object or function, with a ignore property set to true.

For example:

var express = require('express');
var app = express();

var excludedRouter = express.Router();

// Ignore execution along this route.
excludedRouter.glimpse = {
    ignore: true
};

app.use('/excluded-route', excludedRouter);

var router = express.Router();

function excludedMiddleware(req, res, next) {
    next();
}

// Ignore execution of this middleware.
excludedMiddleware.glimpse = {
    ignore: true
};

router.use(excludedMiddleware);

app.use('/route', router);