---
title: CaptureDecorator
description: Captures request and response messages in SLF4J logs, named in this format:
component: pinggateway
version: 2026
page_id: pinggateway:reference:CaptureDecorator
canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/CaptureDecorator.html
revdate: 2025-06-02T18:01:47Z
section_ids:
  CaptureDecorator-usage-decorator: Decorator Usage
  CaptureDecorator-usage-object: Decorated Object Usage
  CaptureDecorator-example: Examples
  CaptureDecorator-example-entity: Log the entity
  CaptureDecorator-example-noentity: Don't log the entity
  CaptureDecorator-example-context: Log the context
  CaptureDecorator-example-entity-req-resp: Log requests and responses with the entity
  CaptureDecorator-example-transformed: Capture transformed requests and responses
  CaptureDecorator-example-json: Capture the context as JSON
  CaptureDecorator-moreinfo: More information
---

# CaptureDecorator

Captures request and response messages in SLF4J logs, named in this format:

```none
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 `CaptureDecorator` to capture and log details of requests and responses.Be aware increased logging consumes resources, such as disk space, and can cause performance issues.In production deployments, avoid setting `"captureEntity": true`. This causes PingGateway to log the entire body, including sensitive data. Usually, `"captureContext": true` logs sufficient information to debug problems. If it isn't needed, reduce logging further by setting `"captureContext": false`. |

You can find more information about using default or custom logging in [Managing PingGateway logs](../maintenance-guide/logging.html).

## Decorator Usage

```json
{
  "name": string,
  "type": "CaptureDecorator",
  "config": {
    "captureEntity": configuration expression<boolean>,
    "captureContext": configuration expression<boolean>,
    "maxEntityLength": configuration expression<number>,
    "masks": object
  }
}
```

* `"captureEntity"`: *configuration expression<[boolean](preface.html#definition-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](AdminHttpApplication.html), 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](preface.html#definition-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](preface.html#definition-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](preface.html#definition-object), optional*

  The configuration to mask the values of headers and attributes in the logs.

  ```json
  {
    "masks": {
      "headers": [ pattern, ... ],
      "trailers": [ pattern, ... ]
      "attributes": [ pattern, ... ]
      "mask": [ configuration expression<string>, ... ]
    }
  }
  ```

  * `"headers"`: *array of [patterns](preface.html#definition-pattern), 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`:

    ```json
    "headers": ["X-OpenAM-.*"]
    ```

    Default: None

  * `"trailers"`: *array of [patterns](preface.html#definition-pattern), optional*

    The case-insensitive name of one or more trailers whose value to mask in the logs.

    The following value masks trailers called `Expires`:

    ```json
    "trailers": ["Expires"]
    ```

    Default: None

  * `"attributes"`: *array of [patterns](preface.html#definition-pattern), optional*

    The case-insensitive name of one or more attributes whose value to mask in the logs.

    Default: None

  * `"mask"`: *configuration expression<[string](preface.html#definition-string)>, optional*

    Text to replace the masked header value or attribute value in the logs.

    Default: `*****`

## Decorated Object Usage

```json
{
    "name": string,
    "type": string,
    "config": object,
    decorator name: capture point(s)
}
```

* `"name"`: *[string](preface.html#definition-string), required except for inline objects*

  The unique name of the decorated object.

* `"type"`: *[string](preface.html#definition-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](Filters.html) and [PingGateway handlers](Handlers.html).

* `"config"`: [object](preface.html#definition-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 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:

```json
{
    "name": "capture",
    "type": "CaptureDecorator",
    "config": {
        "captureEntity": true
    }
}
```

### Don't log the entity

The following example decorator is configured not to log the entity:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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](../_attachments/apidocs/org/forgerock/openig/decoration/capture/CaptureDecorator.html)