CaptureDecorator
Captures request and response messages in SLF4J logs, named in this format:
org.forgerock.openig.decoration.capture.CaptureDecorator.<decoratorName>.<decoratedObjectName>
If the decorated object isn’t named, the object path is used in the log.
When debugging, use a Be aware increased logging consumes resources, such as disk space, and can cause performance issues. In production deployments, avoid setting |
You can find more information about using default or custom logging in Managing PingGateway logs.
Decorator Usage
{
"name": string,
"type": "CaptureDecorator",
"config": {
"captureEntity": configuration expression<boolean>,
"captureContext": configuration expression<boolean>,
"maxEntityLength": configuration expression<number>,
"masks": object
}
}
"captureEntity"
: configuration expression<boolean>, optional-
A flag for capture of the message entity:
-
true
: Capture the request and response message entity and write it to the logs. The message entity is the body of the HTTP message, which can be a JSON document, XML, HTML, image, or other information.When the message is binary, PingGateway writes a
[binary entity]
.When streaming is enabled in admin.json, the decorator interrupts streaming for the captured request or response until the whole entity is captured.
-
false
: Don’t capture the message entity.
If the
Content-Type
header is set for a request or response, the decorator uses it to decode the request or response messages, and then writes them to the logs. If theContent-Type
header isn’t set, the decorator doesn’t write the request or response messages to the logs.Default:
false
-
"captureContext"
: configuration expression<boolean>, optional-
A flag for capture of contextual data about the handled request, such as client, session, authentication identity, authorization identity, or any other state information associated with the request:
-
true
: Capture contextual data about the handled request.The context is captured as JSON. The context chain is used when processing the request inside PingGateway in the filters and handlers.
-
false
: Don’t capture contextual data about the handled request.
Default:
false
-
"maxEntityLength"
: configuration expression<number>, optional-
The maximum number of bytes that can be captured for an entity. This property is used when
captureEntity
istrue
.If the captured entity is bigger than
maxEntityLength
, everything up tomaxEntityLength
is captured, and an[entity truncated]
message is written in the log.Set
maxEntityLength
to be big enough to allow capture of normal entities, but small enough to prevent excessive memory use orOutOfMemoryError
errors. SettingmaxEntityLength
to 2 GB or more causes an exception at startup.Default: 524 288 bytes (512 KB)
"masks"
: object, optional-
The configuration to mask the values of headers and attributes in the logs.
{ "masks": { "headers": [ pattern, ... ], "trailers": [ pattern, ... ] "attributes": [ pattern, ... ] "mask": [ configuration expression<string>, ... ] } }
"headers"
: array of patterns, optional-
The case-insensitive name of one or more headers whose value to mask in the logs.
The following value masks headers called
X-OpenAM-Username
,X-OpenAM-Password
andx-openam-token
:"headers": ["X-OpenAM-.*"]
Default: None
"trailers"
: array of patterns, optional-
The case-insensitive name of one or more trailers whose value to mask in the logs.
The following value masks trailers called
Expires
:"trailers": ["Expires"]
Default: None
"attributes"
: array of patterns, optional-
The case-insensitive name of one or more attributes whose value to mask in the logs.
Default: None
"mask"
: configuration expression<string>, optional-
Text to replace the masked header value or attribute value in the logs.
Default:
*****
Decorated Object Usage
{
"name": string,
"type": string,
"config": object,
decorator name: capture point(s)
}
"name"
: string, required except for inline objects-
The unique name of the decorated object.
"type"
: string, required except for inline objects, required_-
The class name of the decorated object, which must be either a Filter or a Handler. See also PingGateway filters and PingGateway handlers.
"config"
: object required unless empty-
The configuration of the decorated object, as documented in the object reference page.
- decorator name: capture point(s), optional
-
The decorator name must match the name of the CaptureDecorator. For example, if the CaptureDecorator has
"name": "capture"
, then decorator name iscapture
.The capture point(s) are either a single string, or an array of strings. The strings are documented here in lowercase, but aren’t case-sensitive:
"all"
-
Capture at all available capture points.
"none"
-
Disable capture. If
none
is configured with other capture points,none
takes precedence. "request"
-
Capture the request as it enters the Filter or Handler.
"filtered_request"
-
Capture the request as it leaves the Filter. Only applies to Filters.
"response"
-
Capture the response as it enters the Filter or leaves the Handler.
"filtered_response"
-
Capture the response as it leaves the Filter. Only applies to Filters.
Examples
Log the entity
The following example decorator is configured to log the entity:
{
"name": "capture",
"type": "CaptureDecorator",
"config": {
"captureEntity": true
}
}
Don’t log the entity
The following example decorator is configured not to log the entity:
{
"name": "capture",
"type": "CaptureDecorator"
}
Log the context
The following example decorator is configured to log the context in JSON format, excluding the request and the response:
{
"name": "capture",
"type": "CaptureDecorator",
"config": {
"captureContext": true
}
}
Log requests and responses with the entity
The following example decorator is configured to log requests and responses with the entity, before sending the request and before returning the response:
{
"heap": [
{
"name": "capture",
"type": "CaptureDecorator",
"config": {
"captureEntity": true
}
},
{
"name": "ReverseProxyHandler",
"type": "ReverseProxyHandler",
"capture": [
"request",
"response"
]
}
],
"handler": "ReverseProxyHandler"
}
Capture transformed requests and responses
The following example uses the default CaptureDecorator to capture transformed requests and responses, as they leave filters:
{
"handler": {
"type": "Chain",
"config": {
"filters": [{
"type": "HeaderFilter",
"config": {
"messageType": "REQUEST",
"add": {
"X-RequestHeader": [
"Capture at filtered_request point",
"And at filtered_response point"
]
}
}
},
{
"type": "HeaderFilter",
"config": {
"messageType": "RESPONSE",
"add": {
"X-ResponseHeader": [
"Capture at filtered_response point"
]
}
}
}
],
"handler": {
"type": "StaticResponseHandler",
"config": {
"status": 200,
"headers": {
"Content-Type": [ "text/html; charset=UTF-8" ]
},
"entity": "<html><body><p>Hello world!</p></body></html>"
}
}
}
},
"capture": [
"filtered_request",
"filtered_response"
]
}
Capture the context as JSON
The following example captures the context as JSON, excluding the request and response, before sending the request and before returning the response:
{
"heap": [
{
"name": "capture",
"type": "CaptureDecorator",
"config": {
"captureContext": true
}
},
{
"name": "ReverseProxyHandler",
"type": "ReverseProxyHandler",
"capture": [
"request",
"response"
]
}
],
"handler": "ReverseProxyHandler"
}