Moesif NGINX module

Native NGINX module written in C to monitor and analyze API traffic in Moesif advanced analytics platform

This C module is for advanced use cases. Moesif recommends the Lua plugin for both Open Source and Plus variants.

How it works?

This low overhead module captures API request/response headers and body and periodically posts to Moesif servers. The module provides several options, explained below, to be able to choose which API’s data is captured and what part of API headers/body can be sent to Moesif.

How to install

1. Install the Moesif module

Download pre-build binaries from Releases, place them into ./modules sub-directory of nginx.

Assuming standard NGINX plus deployment, create a symlink for the module as shown below.

sudo ln -s /etc/nginx/modules/ngx_moesif_http_filter_module_1.19.0.so /etc/nginx/modules/ngx_http_moesif_filter_module.so

2. Edit your `nginx.conf`

Add the following line at the beginning of nginx.conf _If you’re unsure of the installation path, you can find it via: find / -name "moesif" -type d.

load_module modules/ngx_http_moesif_filter_module.so;

Also, edit your nginx.conf file to add the Moesif Plus plugin:

http{
    moesif  on;
    moesif_application_id your-moesif-application-id
    ...
    server {
        server_name acmeinc.com;
        
        location /api {
            proxy_pass 127.0.0.1:8080
        }
    }
}

3. Reload NGINX

Reload the NGINX config with the command nginx -s reload

Alternatively, you can install this module manually with the Nginx source, see the installation instructions

Configuration

You can modify your configuration to install on specific services or to add additional data to the logged API calls such as User Id or Metadata.

Example:

http{
    # turn on Moesif  function
    moesif  on;
    moesif_application_id  your-moesif-application-id;  # required field
    moesif_sync_interval 1;  # optional field to configure how often API data is sent, defaults to 2 seconds
    moesif_events_cache_size 50;  # optional field to configure events cache size, defaults to 25
    moesif_metadata type http;    # optional metadata
    ...
    server {
        server_name example.com;
        
        moesif_metadata server east-1; #optional metadata

        location /loc1 {
                #moesif data is captured since moesif is on at a global level
            moesif_user_id_header  X-USER-ID;
            moesif_company_id_header X-COMPANY_ID;
            moesif_api_version_header X-API-VERSION; 
            moesif_api_weight  1;
            ...    
            proxy_pass 127.0.0.1:8080
        }
        
        location /loc2 {
            moesif  off;  # moesif disabled. No API events captured at this location  
            ...
     
        }
        
        location /loc3 {
            moesif  on;
            moesif_skip_body on; # body is not captured at this location
            moesif_metadata api mgmt; #optional metadata, all the metadata above is inherited
            ...
     
        }
        
    }

}

Directives

moesif_application_id

syntax: moesif_application_id <application_id>

default: -

context: http

Your Moesif Application Id can be found in the Moesif Portal.

You can always find your Moesif Application Id at any time by logging into the Moesif Portal, click on the top right menu, and then clicking Installation.

moesif_events_cache_size

syntax: moesif_events_cache_size <cache_size>

default: cache_size 25

context: http

Sets the cache_size as unsigned number. This is used to determine internal cache size module uses to save events.

moesif_sync_interval

syntax: moesif_sync_interval <seconds>

default: moesif_sync_interval 2

context: http

Specifies the interval events are synced to Moesif. Defaults to 2 seconds.