Setting the Output Destination of Rejection Logs and Metrics
(This feature can be tried with the Pleasanter Extensions Trial.)
Overview¶
This page explains how to set the output destination of the rate limit rejection logs and metrics snapshots. For the overview of the whole function and the operation modes, see "Rate Limit Function". For the way of thinking about threshold adjustment, see "Rate Limit Function: Adjusting Policies and Thresholds".
The log output of the rate limit uses NLog. The output destination and the output format are set in the NLog section of appsettings.json.
With the standard settings, the rejection logs and metrics snapshots are output to files. In environments such as Docker where standard output (stdout) is collected by a log collection platform, you can enable stdout output as needed.
Prerequisites¶
- This feature is available only to subscribers of the following plans of the Annual Support Service.
| Entry | Basic | Basic Plus | Business | Business Plus | Unlimited |
|---|---|---|---|---|---|
| 〇 | 〇 | 〇 |
Logs That Are Output¶
The rate limit handles the following two kinds of logs.
| Logger | Content | Default output destination | Remarks |
|---|---|---|---|
| ratelimitlogs | Details of rejection logs | File | May include the IP, login ID, user ID, tenant ID, request path, and so on. |
| ratelimitmetrics | Aggregated snapshots of rejection counts | File | Counts by policy name, partition type, and mode. Does not include detailed personally identifiable information. |
You can use ratelimitmetrics to check the counts when switching to On after measuring with LogOnly (for details, see "Rate Limit Function: Adjusting Policies and Thresholds").
Enabling the Rate Limit Function¶
The rate limit logs and metrics are output when the mode of the target policy in RateLimit.json is LogOnly or On.
- Open RateLimit.json.
- Set the Mode of the target policy to LogOnly or On.
- Restart Pleasanter.
When the Mode of the target policy is Off, the rate limit logs and metrics are not output even if the NLog settings of appsettings.json are configured.
Configuration File¶
The output destination is set in the NLog section of appsettings.json.
Standard Settings: File Only¶
With the standard settings, nothing is output to stdout, and logs are output only to files.
{
"NLog": {
"rules": [
{
"logger": "console",
"minLevel": "Info",
"writeTo": "logconsole"
},
{
"logger": "syslogs",
"minLevel": "Info",
"writeTo": "csvfile"
},
{
"logger": "mcplogs",
"minLevel": "Info",
"writeTo": "mcplogsfile"
},
{
"logger": "ratelimitlogs",
"minLevel": "Warn",
"writeTo": "ratelimitlogsfile"
},
{
"logger": "ratelimitmetrics",
"minLevel": "Info",
"writeTo": "ratelimitlogsfile"
}
]
}
}
With these settings, logs are output to the following file.
Target for stdout Output¶
To output to stdout, add a Console target to NLog.targets. To use the same JSON format as the file output, specify a layout in the same form as ratelimitlogsfile.
{
"NLog": {
"targets": {
"ratelimitlogsconsole": {
"type": "AsyncWrapper",
"target": {
"type": "Console",
"detectConsoleAvailable": true,
"writeBuffer": true,
"layout": {
"type": "JsonLayout",
"Attributes": [
{
"name": "timestamp",
"layout": "${date:format=O}"
},
{
"name": "level",
"layout": "${level:upperCase=true}"
},
{
"name": "message",
"layout": "${message}"
},
{
"name": "ratelimitlog",
"encode": false,
"layout": {
"type": "JsonLayout",
"includeEventProperties": "true"
}
},
{
"name": "exception",
"encode": false,
"layout": {
"type": "jsonLayout",
"Attributes": [
{
"name": "type",
"layout": "${exception:format=type}"
},
{
"name": "message",
"layout": "${exception:format=message}"
},
{
"name": "stacktrace",
"layout": "${exception:format=tostring}"
}
]
}
}
]
}
}
}
}
}
}
Setting Example 1: Output Only the Counts to stdout¶
This setting sends only the counts to the external log collection platform, and keeps the detailed logs, which include the IP, login ID, and so on, only in files.
{
"NLog": {
"rules": [
{
"logger": "console",
"minLevel": "Info",
"writeTo": "logconsole"
},
{
"logger": "syslogs",
"minLevel": "Info",
"writeTo": "csvfile"
},
{
"logger": "mcplogs",
"minLevel": "Info",
"writeTo": "mcplogsfile"
},
{
"logger": "ratelimitlogs",
"minLevel": "Warn",
"writeTo": "ratelimitlogsfile"
},
{
"logger": "ratelimitmetrics",
"minLevel": "Info",
"writeTo": "ratelimitlogsfile,ratelimitlogsconsole"
}
]
}
}
With this setting, only RateLimitMetricsSnapshot is output to stdout.
Output example:
{"timestamp":"2026-07-09T14:03:00.0000000Z","level":"INFO","message":"RateLimitMetricsSnapshot","ratelimitlog":{"EventType":"RateLimitMetricsSnapshot","WindowStartedAt":"2026-07-09T14:02:00.0000000Z","WindowEndedAt":"2026-07-09T14:03:00.0000000Z","Counts":{"GlobalLimiter_ip_On":18452,"PublicForm_ip_On":211,"General_user_On":37}}}
The keys of Counts are "policy name_partition type_mode" (separated by _). Because of the JSON output specification of NLog, symbols such as "|" cannot be used in keys, so "_" is used as the separator.
Setting Example 2: Output the Details of Rejection Logs and the Counts to stdout¶
This setting also sends the details of the rejection logs to the external log collection platform.
{
"NLog": {
"rules": [
{
"logger": "console",
"minLevel": "Info",
"writeTo": "logconsole"
},
{
"logger": "syslogs",
"minLevel": "Info",
"writeTo": "csvfile"
},
{
"logger": "mcplogs",
"minLevel": "Info",
"writeTo": "mcplogsfile"
},
{
"logger": "ratelimitlogs",
"minLevel": "Warn",
"writeTo": "ratelimitlogsfile,ratelimitlogsconsole"
},
{
"logger": "ratelimitmetrics",
"minLevel": "Info",
"writeTo": "ratelimitlogsfile,ratelimitlogsconsole"
}
]
}
}
With this setting, all of the following are output to stdout.
| EventType | Content |
|---|---|
| RateLimitRejected | Details of requests that were actually rejected |
| RateLimitWouldHaveRejected | Details of requests judged as equivalent to rejection with LogOnly |
| RateLimitMetricsSnapshot | Aggregation of rejection counts at regular intervals |
The detailed logs may include the IP, login ID, user ID, tenant ID, request path, and so on. When sending them to an external platform, check the permissions, retention period, and masking policy of the destination.
Cautions¶
When Running as a Windows Service or on IIS¶
When running as a Windows service or on IIS, we recommend combining file output with a file shipper (software that monitors and forwards log files) rather than stdout.
In this case, keep the standard settings and collect logs/{yyyy}/{MM}/{dd}/ratelimitlogs.json.
Handling of API Keys¶
The keys of the ApiKey partition are masked with SHA-256, and raw API keys are not output to the logs.
However, the detailed logs may include the IP, login ID, user ID, tenant ID, request path, and so on. When outputting detailed logs to stdout, check the access permissions and retention period of the log collection destination.
Applying the Settings¶
After changing the settings, restart Pleasanter.
After the restart, when a request equivalent to a rejection occurs in a LogOnly or On policy, RateLimitMetricsSnapshot is output.
Supported Versions¶
| Supported versions | Body |
|---|---|
| 1.5.6.0 and later | Added the rate limit function |