---
title: CaptureDecorator
description: Configure the CaptureDecorator to capture HTTP request and response messages, entities, and context in PingGateway SLF4J logs, with header masking support
component: pinggateway
version: 2024.11
page_id: pinggateway:reference:CaptureDecorator
canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/CaptureDecorator.html
llms_txt: https://docs.pingidentity.com/pinggateway/llms.txt
docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md
revdate: 2026-06-02T09:47:34Z
superseded_by: https://docs.pingidentity.com/pinggateway/2026/reference/CaptureDecorator.html
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.

|   |                                                                                                                                                                                                                                                                                                                                                                      |
| - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|   | 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`. |

You can find more information about using default or custom logging in [Manage 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 [Filters](Filters.html) and [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)