> ## Documentation Index
> Fetch the complete documentation index at: https://moeck.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Logs & State

> Retrieve recorded requests, active expectations, and logs via the REST API. Clear or reset state between tests. Persist expectations to survive restarts.

MockServer maintains internal state that you can inspect, clear, and persist:

* **Recorded requests** — every request received since MockServer last started or was reset
* **Active expectations** — all currently registered expectations
* **Recorded expectations** — expectations captured from proxied traffic
* **Logs** — all internal log events

## Log levels

The log level controls how much detail MockServer records. Set it using the `mockserver.logLevel` property or `MOCKSERVER_LOG_LEVEL` environment variable.

| Level   | What it includes                                                                                                                                             |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `TRACE` | Low-level details, full request/response content, and verbose matcher internals. Generates a large volume of output.                                         |
| `DEBUG` | All matcher results including which specific matchers failed (e.g. a particular header value mismatch). Useful when debugging why a request is not matching. |
| `INFO`  | All interactions: expectations created, requests matched, expectations cleared, verifications run. (Default)                                                 |
| `WARN`  | Exceptions and errors only.                                                                                                                                  |
| `ERROR` | Critical errors only.                                                                                                                                        |
| `OFF`   | No logging.                                                                                                                                                  |

Change the log level at runtime without restarting MockServer:

<CodeGroup>
  ```java Java theme={null}
  ConfigurationProperties.logLevel("DEBUG");
  ```

  ```bash System property theme={null}
  -Dmockserver.logLevel=DEBUG
  ```

  ```bash Environment variable theme={null}
  MOCKSERVER_LOG_LEVEL=DEBUG
  ```

  ```bash Command line flag theme={null}
  java -jar mockserver.jar -serverPort 1080 -logLevel DEBUG
  ```
</CodeGroup>

<Tip>
  Use `DEBUG` when debugging why an expectation is not matching. Use `INFO` for normal operation. Use `OFF` only if logging overhead is a concern and you have no need to inspect state.
</Tip>

## Retrieving recorded requests

Retrieve all requests MockServer has received since it last started or was reset:

<CodeGroup>
  ```java Java theme={null}
  HttpRequest[] requests = new MockServerClient("localhost", 1080)
      .retrieveRecordedRequests(
          request()
      );
  ```

  ```bash curl theme={null}
  curl -X PUT "http://localhost:1080/mockserver/retrieve?type=REQUESTS"
  ```
</CodeGroup>

Filter by request properties to retrieve only matching requests:

<CodeGroup>
  ```java Java theme={null}
  HttpRequest[] requests = new MockServerClient("localhost", 1080)
      .retrieveRecordedRequests(
          request()
              .withPath("/api/users")
              .withMethod("POST")
      );
  ```

  ```bash curl theme={null}
  curl -X PUT "http://localhost:1080/mockserver/retrieve?type=REQUESTS" \
    -d '{"path": "/api/users", "method": "POST"}'
  ```
</CodeGroup>

## Retrieving active expectations

Retrieve all currently registered expectations:

<CodeGroup>
  ```java Java theme={null}
  Expectation[] expectations = new MockServerClient("localhost", 1080)
      .retrieveActiveExpectations(
          request()
      );
  ```

  ```bash curl theme={null}
  curl -X PUT "http://localhost:1080/mockserver/retrieve?type=ACTIVE_EXPECTATIONS"
  ```
</CodeGroup>

Filter by request matcher to retrieve only expectations that match certain request properties:

<CodeGroup>
  ```java Java theme={null}
  Expectation[] expectations = new MockServerClient("localhost", 1080)
      .retrieveActiveExpectations(
          request()
              .withPath("/some/path")
              .withMethod("POST")
      );
  ```

  ```bash curl theme={null}
  curl -X PUT "http://localhost:1080/mockserver/retrieve?type=ACTIVE_EXPECTATIONS" \
    -d '{"path": "/some/path", "method": "POST"}'
  ```
</CodeGroup>

## Retrieving recorded logs

Retrieve the log messages MockServer has recorded:

<CodeGroup>
  ```java Java theme={null}
  String logMessages = new MockServerClient("localhost", 1080)
      .retrieveLogMessages(
          request()
      );
  ```

  ```bash curl theme={null}
  curl -X PUT "http://localhost:1080/mockserver/retrieve?type=LOGS"
  ```
</CodeGroup>

Filter logs to only those related to a specific path:

<CodeGroup>
  ```java Java theme={null}
  String logMessages = new MockServerClient("localhost", 1080)
      .retrieveLogMessages(
          request()
              .withPath("/api/users")
      );
  ```

  ```bash curl theme={null}
  curl -X PUT "http://localhost:1080/mockserver/retrieve?type=LOGS" \
    -d '{"path": "/api/users"}'
  ```
</CodeGroup>

## Clearing state

Clear state selectively using the `type` parameter. This is useful between tests to remove expectations or logs without fully resetting MockServer.

| Type           | What is cleared                                                         |
| -------------- | ----------------------------------------------------------------------- |
| `all`          | Recorded requests, active expectations, recorded expectations, and logs |
| `log`          | Recorded requests and log entries only                                  |
| `expectations` | Active and recorded expectations only                                   |

### Clear all state matching a request path

<CodeGroup>
  ```java Java theme={null}
  new MockServerClient("localhost", 1080).clear(
      request()
          .withPath("/api/users")
  );
  ```

  ```bash curl theme={null}
  curl -X PUT "http://localhost:1080/mockserver/clear" \
    -d '{"path": "/api/users"}'
  ```
</CodeGroup>

### Clear only logs for a specific path

<CodeGroup>
  ```java Java theme={null}
  new MockServerClient("localhost", 1080).clear(
      request()
          .withPath("/api/users"),
      ClearType.LOG
  );
  ```

  ```bash curl theme={null}
  curl -X PUT "http://localhost:1080/mockserver/clear?type=log" \
    -d '{"path": "/api/users"}'
  ```
</CodeGroup>

### Clear only expectations for a specific path

<CodeGroup>
  ```java Java theme={null}
  new MockServerClient("localhost", 1080).clear(
      request()
          .withPath("/api/users"),
      ClearType.EXPECTATIONS
  );
  ```

  ```bash curl theme={null}
  curl -X PUT "http://localhost:1080/mockserver/clear?type=expectations" \
    -d '{"path": "/api/users"}'
  ```
</CodeGroup>

<Note>
  When `logLevel` is set to `DEBUG`, clear operations mark log entries as deleted rather than removing them. This keeps the UI's log history intact so you can still debug interactions that occurred before the clear.
</Note>

## Resetting all state

Reset removes all recorded requests, all active expectations, all recorded expectations, and all logs:

<CodeGroup>
  ```java Java theme={null}
  new MockServerClient("localhost", 1080).reset();
  ```

  ```bash curl theme={null}
  curl -X PUT "http://localhost:1080/mockserver/reset"
  ```
</CodeGroup>

<Warning>
  Reset is irreversible. All state is discarded immediately. If you need to recover expectations, persist them first (see below).
</Warning>

## Persisting expectations

By default, expectations exist only in memory and are lost when MockServer restarts. Enable persistence to write expectations to a JSON file that MockServer reloads on startup.

### Enable persistence

<Steps>
  <Step title="Set the persistence properties">
    <CodeGroup>
      ```bash Environment variables theme={null}
      MOCKSERVER_PERSIST_EXPECTATIONS=true
      MOCKSERVER_PERSISTED_EXPECTATIONS_PATH=mockserverExpectations.json
      MOCKSERVER_INITIALIZATION_JSON_PATH=mockserverExpectations.json
      ```

      ```bash System properties theme={null}
      java \
        -Dmockserver.persistExpectations=true \
        -Dmockserver.persistedExpectationsPath=mockserverExpectations.json \
        -Dmockserver.initializationJsonPath=mockserverExpectations.json \
        -jar mockserver.jar -serverPort 1080
      ```

      ```properties Property file theme={null}
      mockserver.persistExpectations=true
      mockserver.persistedExpectationsPath=mockserverExpectations.json
      mockserver.initializationJsonPath=mockserverExpectations.json
      ```
    </CodeGroup>
  </Step>

  <Step title="Confirm the file is reused on restart">
    Set `persistedExpectationsPath` and `initializationJsonPath` to the same file so MockServer both writes to and reads from the same location. On each restart, MockServer loads expectations from this file before accepting requests.
  </Step>
</Steps>

MockServer updates the persistence file automatically whenever expectations are added, cleared, or expire. To watch the initialization file for external changes and reload expectations without restarting:

```properties theme={null}
mockserver.watchInitializationJson=true
```