Monitoring Apigee Microgateway

The Instana Node.js Collector supports Apigee Microgateway (also called edgemicro) beginning with version @instana/collector@1.89.0.

When you start your Microgateway instance by executing edgemicro start or edgemicro forever -a start, there is an additional step (described on this page) required for using it with the Instana Node.js collector. This scenario typically entails that the edgemicro package is installed globally via npm install -g edgemicro or yarn global add edgemicro (instead of installing it as a dependency of your application). If you, on the other hand, use microgateway-core as a dependency in your own, custom app, you do not need the instructions on this page. Instead, use the default installation method for @instana/collector.

Using edgemicro with @instana/collector

To use the Instana Node.js collector in a normal Node.js application you would add a line like

require('@instana/collector')();

to the main entry file of your code base. But when you install edgemicro globally and use the edgemicro command line interface to start the Apigee Microgateway, there is no custom code to add this line to.

For this scenario, the Instana collector package provides an executable that will statically instrument an existing edgemicro installation and make that installation Instana-ready.

The instrumentation needs to be happen on the machine that runs the edgemicro instance you want to monitor. If you are running edgemicro in a container, you need to execute these steps in that container. It only needs to be done once after installing the edgemicro package on that machine/container, not every time you want to start edgemicro. Here are the required steps for preparing your edgemicro installation for Instana monitoring and tracing:

  • Install the package @instana/collector globally on the same machine/in the same container than your edgemicro installation (or more precisely, on a file system that is accessible from your edgemicro installation) by running npm install -g @instana/collector.
  • With @instana/collector installed, you are ready to prepare your edgemicro installation for Instana. Execute the following command:
    instana-instrument-edgemicro-cli
  • This executable is provided by @instana/collector and should be in your path when you have installed the package globally. If your shell is not set up to find executables from globally installed npm packages, you can also fall back to execute $(npm root -g)/../../bin/instana-instrument-edgemicro-cli.
  • This command should print when it is done.
    Done: The edgemicro module has been statically instrumented for Instana tracing and metrics collection.

Note: This procedure (in particular, calling instana-instrument-edgemicro-cli) needs to be repeated when edgemicro is re-installed or updated to a newer version. It is not harmful to execute it multiple times for the same edgemicro installation. The executable is smart enough to recognize that the installation has already been instrumented, and it will update the existing instrumentation, if necessary. The procedure would also need to be repeated if the location of the package @instana/collector changes, but not when that package is updated to a newer version in place.

Advanced Usage

The executable usually needs no arguments since it is able to find a globally installed edgemicro installation. However you can optionally provide the location of edgegateway (and also of @instana/collector) as arguments:

instana-instrument-edgemicro-cli [edgemicro_path [instana-collector-path]]

Examples:

# let Instana figure out the paths
instana-instrument-edgemicro-cli

# specify the edgemicro path
instana-instrument-edgemicro-cli /path/to/edgemicro

# also specify the @instana/collector path`
instana-instrument-edgemicro-cli /path/to/edgemicro /path/to/@instana/collector

To find out where the edgemicro package is installed:

  • Execute the command npm root -g to find out where the global node_modules folder is located. Let's assume this prints /usr/local/lib/node_modules. If the edgemicro package has been installed globally, it should be in the directory /usr/local/lib/node_modules/edgemicro, which is the installation location that we are looking for.
  • Additionally, execute the command ls -l $(which edgemicro) to find out which executable is actually used when using the edgemicro command on the command line. The output might be something like:
    ls -l $(which edgemicro)

       lrwxrwxrwx 1 user group 01 Jan 19 01:23 /usr/local/bin/edgemicro -> ../lib/node_modules/edgemicro/cli/edgemicro
  • This verifies that that the edgemicro package installed in /usr/local/lib/node_modules/edgemicro is the one that is being used when using the edgemicro command.

I see unexpected Instana log output, what is up with that?

As a side effect of this instrumentation, you might see log output from @instana/collector also when running other edgemicro commands, for example edgemicro stop, edgemicro reload, edgemicro version etc. This is expected and can be safely ignored.

See Also