--- title: Logging & Debugging description: Retrieve active expectations, recorded requests, logs, and metrics from MockServer to diagnose matching failures and integration issues. layout: page pageOrder: 5 section: 'General' subsection: true sitemap: priority: 0.7 changefreq: 'monthly' lastmod: 2019-11-10T08:00:00+01:00 ---

If your expectations are not matching requests, see the Troubleshooting Matching guide for a step-by-step debugging checklist and common pitfalls.

MockServer supports the following features to simplify debugging

A UI to easily view logs, active expectations, received requests and proxied requests
Retrieve the following items:
- active expectations
- recorded expectations
- recorded requests
- recorded requests and responses
- logs
- metrics
Configurable log level
A debug mismatch endpoint to programmatically analyze why requests don't match expectations
Clear and simple log messages for all actions
JSON Schema validation of all requests to the REST API, with clear failure messages
Clear failure messages when verifying requests (that support "show difference" in IntelliJ)

The simplest way to debug MockServer is to use the UI to view logs, requests and expectations

Retrieving Active Expectations

It is possible to retrieve the active expectations, as show below in the code examples.

Expectations are returned in the order they have been added. The expectations are returned can be filter using a request matcher.

Expectation[] activeExpectations = new MockServerClient("localhost", 1080)
    .retrieveActiveExpectations(
        request()
    );

var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080)
    .retrieveActiveExpectations({})
    .then(
        function (activeExpectations) {
            console.log(JSON.stringify(activeExpectations));
        },
        function (error) {
            console.log(error);
        }
    );

See REST API for full JSON specification

curl -v -X PUT "http://localhost:1080/mockserver/retrieve?type=ACTIVE_EXPECTATIONS"

See REST API for full JSON specification

Expectation[] activeExpectations = new MockServerClient("localhost", 1080)
    .retrieveActiveExpectations(
        request()
            .withPath("/some/path")
            .withMethod("POST")
    );

var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080).retrieveActiveExpectations({
    "path": "/some/path",
    "method": "POST"
}).then(
    function (activeExpectations) {
        console.log(JSON.stringify(activeExpectations));
    },
    function (error) {
        console.log(error);
    }
);

See REST API for full JSON specification

curl -v -X PUT "http://localhost:1080/mockserver/retrieve?type=ACTIVE_EXPECTATIONS" -d '{
    "path": "/some/path",
    "method": "POST"
}'

See REST API for full JSON specification

String activeExpectations = new MockServerClient("localhost", 1080)
    .retrieveActiveExpectations(
        request()
            .withPath("/some/path")
            .withMethod("POST"),
        Format.JAVA
    );

curl -v -X PUT "http://localhost:1080/mockserver/retrieve?type=ACTIVE_EXPECTATIONS&format=JAVA" -d '{
    "path": "/some/path"
}'

See REST API for full JSON specification

String activeExpectations = new MockServerClient("localhost", 1080)
    .retrieveActiveExpectations(
        request()
            .withPath("/some/path")
            .withMethod("POST"),
        Format.JSON
    );

var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080).retrieveActiveExpectations({
    "path": "/some/path",
    "method": "POST"
}).then(
    function (activeExpectations) {
        console.log(JSON.stringify(activeExpectations));
    },
    function (error) {
        console.log(error);
    }
);

See REST API for full JSON specification

curl -v -X PUT "http://localhost:1080/mockserver/retrieve?type=ACTIVE_EXPECTATIONS&format=JSON" -d '{
    "path": "/some/path"
}'

See REST API for full JSON specification

{% include_subpage _includes/retrieve_code_example.html %}

Request Forwarding Timings

When MockServer forwards a request (in proxy mode or via a forward action), the response includes a timing field containing connection, time-to-first-byte, and total round-trip timing information. This is included in retrieved request-response pairs and can be used to monitor upstream service latency or detect connectivity issues during testing.

The timing object contains:

connectionTimeInMillis — the time taken to establish the TCP connection (and TLS handshake, if HTTPS) to the upstream server
timeToFirstByteInMillis — the time from the start of the request until the first byte of the response is received (connect time plus the upstream server's processing time)
totalTimeInMillis — the total time from sending the request to receiving the complete response

Example response with timing information (as returned by the retrieve request-response API):

{
    "httpRequest": {
        "method": "GET",
        "path": "/api/users"
    },
    "httpResponse": {
        "statusCode": 200,
        "body": "...",
        "timing": {
            "connectionTimeInMillis": 15,
            "timeToFirstByteInMillis": 85,
            "totalTimeInMillis": 142
        }
    }
}

Timings are available when retrieving recorded request-response pairs via the REST API:

curl -v -X PUT "http://localhost:1080/mockserver/retrieve?type=REQUEST_RESPONSES&format=JSON"

For a detailed guide on using these timing fields to diagnose slow or intermittently slow upstream services — including HAR export with timing breakdowns, slow-request flagging, and Prometheus latency percentiles — see Network Latency Debugging.

Retrieving Recorded Logs

MockServer and the proxy record log messages for all major actions, including:

adding expectations
matching requests
executing actions (response, forward, callback & error)
returning responses
forwarded requests and responses when MockServer is used as a proxy - both the request sent to the destination server and the actual response received are logged
clearing logs, expectations & recorded requests
resetting logs, expectations & recorded requests

Note: When MockServer is used as a proxy (forwarding requests to destination servers), the logs include both the original request and the actual response received from the destination server. These are logged with type FORWARDED_REQUEST and can be filtered in the dashboard or retrieved programmatically.

It is possible to retrieve the recorded log messages, as show below in the code examples.

Log messages are returned in the order they have been recorded, and which log messages are returned can be filter using a request matcher.

String logMessages = new MockServerClient("localhost", 1080)
    .retrieveLogMessages(
        request()
    );

var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080)
    .retrieveLogMessages({})
    .then(
        function (logMessages) {
            // logMessages is a String[]
            console.log(logMessages);
        },
        function (error) {
            console.log(error);
        }
    );

See REST API for full JSON specification

curl -v -X PUT "http://localhost:1080/mockserver/retrieve?type=LOGS"

See REST API for full JSON specification

String logMessages = new MockServerClient("localhost", 1080)
    .retrieveLogMessages(
        request()
            .withPath("/some/path")
            .withMethod("POST")
    );

var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080)
    .retrieveLogMessages({
        "path": "/some/path",
        "method": "POST"
    })
    .then(
        function (logMessages) {
            // logMessages is a String[]
            console.log(logMessages);
        },
        function (error) {
            console.log(error);
        }
    );

See REST API for full JSON specification

curl -v -X PUT "http://localhost:1080/mockserver/retrieve?type=LOGS" -d '{
    "path": "/some/path",
    "method": "POST"
}'

See REST API for full JSON specification

String[] logMessages = new MockServerClient("localhost", 1080)
    .retrieveLogMessagesArray(
        request()
            .withPath("/some/path")
    );

var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080)
    .retrieveLogMessages({
        "path": "/some/path"
    })
    .then(
        function (logMessages) {
            // logMessages is a String[]
            console.log(logMessages);
        },
        function (error) {
            console.log(error);
        }
    );

See REST API for full JSON specification

Retrieving Metrics

It is possible to retrieve MockServer metrics as a JSON object containing counts for each metric. Metrics must be enabled by setting metricsEnabled to true.

The available metrics include request counts, expectation match counts, action counts, and WebSocket connection counts.

curl -X PUT "http://localhost:1080/mockserver/retrieve?type=METRICS"

String metrics = new MockServerClient("localhost", 1080)
    .retrieveMetrics();

Metrics are also available in Prometheus format via the GET /mockserver/metrics endpoint when metrics are enabled.

Retrieving & Updating Configuration

The current runtime configuration can be retrieved and updated via the REST API.

curl -X GET "http://localhost:1080/mockserver/configuration"

curl -X PUT "http://localhost:1080/mockserver/configuration" \
  -H "Content-Type: application/json" \
  -d '{"logLevel": "DEBUG", "maxExpectations": 5000}'

Only the properties included in the request body are updated; all other properties retain their current values.

// retrieve current configuration
String config = new MockServerClient("localhost", 1080)
    .retrieveConfiguration();

// update configuration
new MockServerClient("localhost", 1080)
    .updateConfiguration("{\"logLevel\": \"DEBUG\"}");

Logging

All interactions with the MockServer are logged including setting up expectations, matching expectations, clearing expectations and verifying requests. The log can be particularly helpful when trying to debug why a test is failing or expectations are not being matched.

The following information is logged:

WARN - exceptions, errors
INFO - all interactions with the MockServer including setting up expectations, matching expectations, clearing expectations and verifying requests
DEBUG - all matcher results, including when specific matchers fail (such as HeaderMatcher)
TRACE - low level details or exceptions that aren't usually considered an error

The TRACE level logging results in a lot of verbose logging but can be very helpful to debug why a complex matcher (such as the JSON Schema matcher) is not matching.

To disable logging the following options can be used:

-Dmockserver.logLevel=OFF - to disable logging from the MockServer and Proxy classes
-Droot.logLevel=OFF - to disable all logging from all other classes

The following sections explain how to configure logging when running MockServer via:

JUnit 4 @Rule, JUnit 5 Test Extension or Java API (i.e. maven or gradle project)
Command Line
Maven Plugin
npm module or Grunt plugin

Configuring logging for JUnit 4 @Rule, JUnit 5 Test Extension or Java API (i.e. maven or gradle project)

MockServer uses SL4J for logging so if MockSever is being launched using the JUnit 4 @Rule, the JUnit 5 Test Extension, ClientAndServer or directly using the org.mockserver.netty.MockServer the project launching MockServer needs to configure the logging output by configuring SLF4J. MockServer relies on a SLF4J binding being on the classpath for logs to be output. The simplest approach is to use the Java Logger SLF4J binding.

In MockServer the Java Logger SLF4J binding is only an optional dependency. Therefore, when MockServer is added as a dependency to a Maven or Gradle project it does not pull in the Java Logger binding transitively.

If no existing SLF4J logger binding exists no logs will be output and the following error will be displayed by SLF4J:

SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.

If this happens the simplest way to output logs for MockServer is to add the Java Logger SLF4J binding as a dependency. For example, in Maven this would be as follows:

<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-jdk14</artifactId>
    <version>1.7.29</version>
</dependency>

It is possible to configure the logger using a configuration file by specifying the java.util.logging.config.file system property, as follows.

-Djava.util.logging.config.file=/path/to/example_logging_configuration.properties

It is possible to configure the logger programmatically, for example, as follows.

ConfigurationProperties.logLevel("DEBUG");
String loggingConfiguration = "" +
    "handlers=org.mockserver.logging.StandardOutConsoleHandler\n" +
    "org.mockserver.logging.StandardOutConsoleHandler.level=ALL\n" +
    "org.mockserver.logging.StandardOutConsoleHandler.formatter=java.util.logging.SimpleFormatter\n" +
    "java.util.logging.SimpleFormatter.format=%1$tF %1$tT  %3$s  %4$s  %5$s %6$s%n\n" +
    ".level=" + javaLoggerLogLevel() + "\n" +
    "io.netty.handler.ssl.SslHandler.level=WARNING";
LogManager.getLogManager().readConfiguration(new ByteArrayInputStream(loggingConfiguration.getBytes(UTF_8)));

Configuring logging via the Command Line

When running MockServer directly from the command line the command line argument -logLevel can be used to set the log level, as follows:

java -jar ~/Downloads/mockserver-netty-{{ site.mockserver_version }}-no-dependencies.jar -serverPort 1080 -logLevel DEBUG

Alternatively a system property mockserver.logLevel can be used to set the log level, as follows:

java -Dmockserver.logLevel=INFO -jar ~/Downloads/mockserver-netty-{{ site.mockserver_version }}-no-dependencies.jar -serverPort 1080

Configuring Java Logger

When running MockServer from the command line it relies on the Java Logger java.util.logging.Logger in addition to controlling the log level of MockServer using -logLevel the underlying logging framework can be configured (overriding the default configuration) by specifying the System Property java.util.logging.config.file or java.util.logging.config.class as detailed in the LogManager JavaDoc.

The MockServer github repository contains an example Java Logger configuration file (which would be configured using java.util.logging.config.file).

The default logging configuration can be overridden as follows:

java -Djava.util.logging.config.file=/path/to/example_logging_configuration.properties -jar ~/Downloads/mockserver-netty-{{ site.mockserver_version }}-no-dependencies.jar -serverPort 1080 -logLevel DEBUG

Configuring logging via the Maven Plugin

The mockserver-maven-plugin provides a logLevel settings that can be used to define the log level for all MockServer classes, as follows:

<plugin>
     <groupId>org.mock-server</groupId>
     <artifactId>mockserver-maven-plugin</artifactId>
     <version>{{ site.mockserver_version }}</version>
     <configuration>
        <serverPort>1080</serverPort>
        <logLevel>DEBUG</logLevel>
     </configuration>
     <executions>
         <execution>
             <id>process-test-classes</id>
             <phase>process-test-classes</phase>
             <goals>
                 <goal>runForked</goal>
             </goals>
         </execution>
         <execution>
             <id>verify</id>
             <phase>verify</phase>
             <goals>
                 <goal>stopForked</goal>
             </goals>
         </execution>
     </executions>
 </plugin>

Configuring logging via the npm module

When running MockServer using the mockserver-node Grunt plugin and Node.js (npm) module the verbose option can be used to enable INFO level logging and the trace option can be used to enable TRACE level logging.

It is generally recommended to enable verbose which should provide the correct amount of information, trace is only required for very low level debugging.

var mockserver = require('mockserver-node');

mockserver
    .start_mockserver({
        serverPort: 1080,
        verbose: true,
        trace: true
    })
    .then(
        function () {
            console.log("started MockServer");
        },
        function (error) {
            console.log(JSON.stringify(error));
        }
    );

Configuring logging via the Grunt plugin

When running MockServer using the mockserver-node as a Grunt plugin module the verbose option can be used to enable INFO level logging and the trace option can be used to enable TRACE level logging. The --verbose command line flag can also be used to enable the mockserver-node verbose option from the command line.

It is generally recommended to enable verbose which should provide the correct amount of information, trace is only required for very low level debugging.

grunt.initConfig({
        start_mockserver: {
            options: {
                serverPort: 1080,
                verbose: true,
                trace: true
            }
        },
        stop_mockserver: {
            options: {
                serverPort: 1080
            }
        }
});

grunt.loadNpmTasks('mockserver-node');