PingGateway 2024.9

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.

During debugging, consider using a CaptureDecorator to capture the entity and context of requests and responses. However, increased logging consumes resources, such as disk space, and can cause performance issues. In production, reduce logging by disabling the CaptureDecorator properties captureEntity and captureContext, or setting maxEntityLength.

For information about using default or custom logging, refer to Manage 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 the Content-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 is true.

If the captured entity is bigger than maxEntityLength, everything up to maxEntityLength 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 or OutOfMemoryError errors. Setting maxEntityLength 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 and x-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 Filters and 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 is capture.

The capture point(s) are either a single string, or an array of strings. The strings are documented here in lowercase, but are not 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
    }
}

Do not 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"
}

More information

org.forgerock.openig.decoration.capture.CaptureDecorator