Miss any of our Open RFC calls?Watch the recordings here! »

@scout_apm/scout-apm

0.1.12 • Public • Published

Scout APM NodeJS Client

Monitor the performance of NodeJS apps, with Scout. Detailed performance metrics and transactional traces are collected once the scout-apm package is installed and configured.

Requirements

NodeJS Versions:

  • 10+

Scout APM works with the following frameworks:

Quick Start

A Scout account is required. Signup for Scout.

Installing the Scout client

Install @scout_apm/scout-apm:

$ npm install @scout_apm/scout-apm

Using @scout_apm/scout-apm with express

Scout supports use with express-based applications by using app-wide middleware:

const scout = require("@scout_apm/scout-apm");
const process = require("process");
const express = require("express");
 
// Initialize the express application
const app = express();
 
// Enable the app-wide scout middleware
app.use(scout.expressMiddleware());
 
// Set up the routes for the application
app.get('/', function (req, res) {
  // Add some custom context to the request synchronously
  // In an asynchronous context, `await` or `.then` can be used with `scout.api.Context.add`
  scout.api.Context.addSync("custom_name", "custom_value");
 
  res.send('hello, world!');
});
 
// Shut down the core-agent when this program exits
process.on('exit', () => {
  if (app && app.scout) {
    app.scout.shutdown();
  }
});
 
// Start application
async function start() {
  // Install and wait for scout to set up
  await scout.install({
    monitor: true, // enable monitoring
    name: "<application name>",
    key: "<scout key>",
 
    // allow scout to be shutdown when the process exits
    allowShutdown: true,
  });
 
  // Start the server
  app.listen(3000);
}
 
if require.main === module { start(); }

In addition to specifying app and name in the config object when building the middleware, you may also specify it via ENV by setting SCOUT_NAME and SCOUT_APP as environment variables for the process.

If your core-agent instance is running externally and you do not need @scout_apm/scout-apm to start it, you can set the coreAgentLaunch setting to false or specify the ENV variable SCOUT_CORE_AGENT_LAUNCH with value false.

For more information on configuration, see docs/configuration.md

Supported module integrations

@scout_apm/scout-apm supports a variety of modules and

Name Status Description
net STABLE NodeJS standard library net module
http STABLE NodeJS standard library http module
https STABLE NodeJS standard library https module
ejs STABLE EJS templating library
mustache STABLE Mustache templating library
pug STABLE Pug (formerly Jade) templating library
mysql STABLE Mysql database driver
mysql2 STABLE Mysql2 database driver
pg STABLE Postgres database driver
express STABLE Express web framework
nuxt ALPHA Nuxt web framework

Using @scout_apm/scout-apm with other frameworks

Scout supports use with any other frameworks through it's Promise based API:

const scout = require("@scout_apm/scout-apm");
 
// Set up scout (this returns a Promise you may wait on if desired)
scout.install(
  {
    allowShutdown: true, // allow shutting down spawned scout-agent processes from this program
    monitor: true, // enable monitoring
    name: "<application name>",
    key: "<scout key>",
  },
);
 
// Run a WebTransaction
scout.api.WebTransaction.run("GET /users", (finishTransaction) => { .
   return yourHandler
     .run()
     .then(() => finishTransaction());
});
 
// Run a BackgroundTransaction
scout.api.BackgroundTransaction.run("your-large-transaction", (finishTransaction) => {
  return bigHeavyTaskThatReturnsAPromise()
      .then(() => finishTransaction());
});

For more examples, see docs/cookbook.md For more information on the architecture of the client see docs/architecture.md.

Development

To get started developing @scout_apm/scout-apm, run:

$ make dev-setup

This will set up the necessary environment (including git hooks) to get started hacking on @scout_apm/scout-apm.

This repository comes with a few development aids pre-installed, via make targets:

$ make lint # run tslint (a typescript linter
$ make lint-watch # run tslint continuously

$ make build # run tsc (the typescript compiler)
$ make build-watch # run tsc continuously

For more information on the development environment and tools, see docs/development.md.

Contributing

To contribute to development of the NodeJS client:

  1. Clone this repository
  2. Run make dev-setup to set up the local development environment
  3. Run make build to build the project
  4. Write code for the change/bugfix/feature
  5. Run make test to ensure all tests are passing (see docs/tests.md for more information)
  6. Submit a PR

Documentation

For full installation and troubleshooting documentation, visit our help site.

Support

Please contact us at support@scoutapp.com or create an issue in this repository.

Install

npm i @scout_apm/scout-apm

DownloadsWeekly Downloads

243

Version

0.1.12

License

MIT

Unpacked Size

346 kB

Total Files

81

Last publish

Collaborators

  • avatar
  • avatar