Nostalgic Primordial Monster

    @scout_apm/scout-apm
    TypeScript icon, indicating that this package has built-in type declarations

    0.2.2 • 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
    nest ALPHA Nest 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

    168

    Version

    0.2.2

    License

    MIT

    Unpacked Size

    369 kB

    Total Files

    81

    Last publish

    Collaborators

    • avatar
    • avatar