Monitoring Apigee Microgateway

Edit online

Learn about 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 local installation method for @instana/collector.

Using edgemicro with @instana/collector

Edit online

In a normal Node.js application, the Instana Node.js collector is enabled by adding the following line to the main entry file of your code base:

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

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.

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 must happen on the machine that runs the edgemicro instance you want to monitor. If you are running edgemicro in a container, complete these steps inside that container. It only needs to be done once after you install the edgemicro package on that machine or container, not every time you want to start edgemicro. The following steps prepare the edgemicro installation for Instana monitoring and tracing:

  • Install the Instana Node.js collector globally on the same machine or in the same container as your edgemicro installation. Make sure that the collector is installed on a file system that your edgemicro installation can access.
  • With @instana/collector installed, you are ready to prepare your edgemicro installation for Instana. Run 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

Edit online

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?

Edit online

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.