traffic-manager-agent
v0.0.5
Published
Middleware to monitor patterns in your web app traffic.
Downloads
2
Readme
Traffic Manager Agent
Middleware in your Node application to collect the incoming requests.
Integrating into Node app
First steps
Add agent module to your project's dependencies
npm install traffic-manager-agent --save
After this just follow the instructions to generate accesslog of your application (Apache Common Log Format), send data to Traffic Manager Hub or both.
Basic accesslog
This is enough to get a full access log generated in your application.
Produces Apache Common Log Format (CLF) which can be analysed further with tools readily available.
Just register the middleware before other routes in your app and restart the app.
const TrafficManagerAgent = require('traffic-manager-agent');
const trafficManagerOpts = {
reporters: [
{
type: 'event',
output: 'file',
format: 'apache',
location: `${__dirname}/../accesslog.log`,
},
]
};
const trafficManagerMiddleware = TrafficManagerAgent(trafficManagerOpts);
app.use(trafficManagerMiddleware);
Sending data to Traffic Manager Hub
You can use this module to integrate with Traffic Manager Hub directly.
This is desired when you need more insight into your application's incoming traffic, understand the patterns in it, perform early threat analysis and shape the traffic with customisable rate limiting.
const TrafficManagerAgent = require('traffic-manager-agent');
const trafficManagerOpts = {
reporters: [
{
type: 'frame',
output: 'tmhub',
url: 'https://trafficmanager.example.com',
siteId: '2fb5193d923f4b71ad6a771e8700aa1f',
siteSecret: 'ZSU5M2UyMGE5N2JjNDFmODkxMTVjNWViNjVmY2U0MGY=',
}
]
};
const trafficManagerMiddleware = TrafficManagerAgent(trafficManagerOpts);
app.use(trafficManagerMiddleware);
Settings
trafficManagerOpts
object passed to Traffic Manager Agent middleware can
be used to control reporters as well as some local settings.
These additional settings can be set as properties
of the settings
object in trafficManagerOpts
.
blacklistedIps
- (default:[]
)whitelistedIps
- (default:[]
)perThreadRateLimit
- (default:0
) request limit per user in the specified frame. Useful when you don't need to connect to Traffic Manager Hub and want simple throttling solution.frameDurationSeconds
- (default:60
) duration of the monitoring frame in seconds
These settings will only apply to the agent and the app process in which it's implemented.
To rate limit across multiple instances of your application you'll need to aggregate the results in Traffic Manager Hub (available as a reporter, read more below).
Reporters
You can combine multiple reporters in a single application.
There are two types
of reporters - an event reporter which logs every request
immediately, and a frame reporter which aggregates a full frame before
reporting.
Event reporters
stdout
file
Options:
format
-apache
,short
orjson
filter
- allows selecting messages you want to log, i.e. you can use{ statusCode: 429 }
to produce a "block log"location
- (only forfile
reporter) specifies where the log file will be placed
Frame reporters
stdout
tmhub
stdout
stdout
reporter outputs a summary of a frame in one of two formats:
count-only
or detailed
. Specify it as format
in reporter options.
detailed
format also supports topEntriesLimit
to change how many "top clients"
should be included in the frame summary message.
tmhub
tmhub
is used to link with Traffic Manager Hub which aggregates the frames
from multiple applications and their instances. This allows centralised logging,
enforcement of blocking policies and further analysis of incoming traffic.
It requires the following options:
url
siteId
siteSecret
Combining reporters
You can have a standard accesslog produced for the infrastructure team, console output for developers and a web UI with basic analysis for everyone else.
const TrafficManagerAgent = require('traffic-manager-agent');
const trafficManagerOpts = {
settings: {
frameDurationSeconds: 15,
customBlockedRequestMessage: 'If you think you should not be seeing this message please contact [email protected]'
},
reporters: [
{
type: 'event',
output: 'stdout',
format: 'apache',
filter: { statusCode: 429 } // only log blocked requests
},
{
type: 'event',
output: 'file',
format: 'apache',
location: `${__dirname}/../accesslog.log`
},
{
type: 'frame',
output: 'stdout',
format: 'count-only',
topEntriesLimit: 5
},
{
type: 'frame',
output: 'tmhub',
url: 'https://trafficmanager.example.com',
siteId: '2fb5193d923f4b71ad6a771e8700aa1f',
siteSecret: 'ZSU5M2UyMGE5N2JjNDFmODkxMTVjNWViNjVmY2U0MGY='
}
]
};
const trafficManagerMiddleware = TrafficManagerAgent(trafficManagerOpts);
app.use(trafficManagerMiddleware);