https://github.com/moesif/moesif-nginx-plugin

Last synced: 8 months ago
JSON representation

Host: GitHub
URL: https://github.com/moesif/moesif-nginx-plugin
Owner: Moesif
Created: 2020-08-26T21:56:57.000Z (about 5 years ago)
Default Branch: master
Last Pushed: 2021-02-26T03:46:37.000Z (over 4 years ago)
Last Synced: 2025-01-05T21:12:02.439Z (9 months ago)
Size: 128 KB
Stars: 0
Watchers: 4
Forks: 1
Open Issues: 0
Metadata Files:
- Readme: README.md

Awesome Lists containing this project

README

# 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](https://www.moesif.com/docs/server-integration/nginx-openresty/) 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](https://github.com/Moesif/moesif-nginx-plugin/tree/master/modules/),
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`.

```nginx
load_module modules/ngx_http_moesif_filter_module.so;
```

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

```nginx
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](#build-from-source)*

## 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:

```nginx
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 \*

**default:** *-*

**context:** *http*

Your Moesif Application Id can be found in the [_Moesif Portal_](https://www.moesif.com/).

You can always find your Moesif Application Id at any time by logging
into the [_Moesif Portal_](https://www.moesif.com/), click on the top right menu,
and then clicking _Installation_.

moesif_events_cache_size
--------------------
**syntax:** *moesif_events_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 \*

**default:** *moesif_sync_interval 2*

**context:** *http*

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

moesif
--------------------
**syntax:** *moesif on | off*

**default:** *moesif off*