Actuators: Types, Operation, Selection, and Control

Spring Boot Actuator HTTP Trace Endpoint

Learn how to enable, expose, secure, and use Spring Boot Actuator's httptrace endpoint, inspect recent HTTP exchanges, protect sensitive data, and migrate to httpexchanges.

Spring Boot Actuator's historical httptrace endpoint provides an in-memory view of recent HTTP exchanges handled by an application. It is useful for checking what request reached an instance and what response that instance returned.

This endpoint is primarily a lightweight diagnostic tool. It is not a replacement for durable access logs, distributed tracing, auditing, or application performance monitoring.

What an HTTP trace is useful for

An HTTP trace is a retained record of a recently handled HTTP request and its response. A record can include data such as the time of the exchange, HTTP method, URI, remote address, selected headers, response status, and response headers.

Typical uses include:

• Debugging a local Spring Boot application.
• Checking whether a request reached the expected application instance.
• Validating an API request and its response during development.
• Investigating a recent 401, 403, 404, or 500 response.
• Comparing the actual request path and method with the security or controller configuration.

HTTP tracing compared with other observability tools

Endpoint identity and availability

Spring Boot Actuator is the Spring Boot module that exposes management and operational endpoints. The historical endpoint ID is httptrace, normally available below the management base path as /actuator/httptrace.

Its availability depends on several independent conditions:

1. The Actuator starter must be on the classpath.
2. The application must use a supported servlet or reactive web stack integration.
3. The endpoint must be enabled in the Spring Boot version being used.
4. The endpoint must be exposed over HTTP.
5. Security rules must permit the caller to access it.

The default management base path is commonly /actuator, but it can be customized. A separate management port can also place Actuator endpoints on a different port from application traffic. A management address can restrict which network interface accepts management requests.

In later Spring Boot releases, HTTP exchange support uses the endpoint ID httpexchanges and the repository abstraction HttpExchangeRepository. The historical httptrace name and HttpTraceRepository should not be assumed to work in every release. Always check the documentation and configuration metadata for the exact Spring Boot version in your project.

For general endpoint exposure concepts, see Spring Boot Actuator.

Dependencies and prerequisites

You need a Spring Boot web application and the Actuator starter. Use the dependency format appropriate for your build tool.

Maven

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

Gradle

implementation 'org.springframework.boot:spring-boot-starter-actuator'

The web request must reach the application before an exchange can be recorded. Calling the management endpoint before sending any application request can therefore produce an empty collection.

The integration used to collect exchanges depends on the application type. A servlet application and a reactive WebFlux application use different web infrastructure, so verify that the selected Spring Boot release supports the relevant stack and repository integration.

Enabling and exposing the endpoint

Endpoint enablement means that an Actuator endpoint is active in the application. Web exposure means that an enabled endpoint is reachable through an HTTP management route. These are separate settings.

For versions that support the historical endpoint name, a narrow YAML configuration can look like this:

management:
  endpoints:
    web:
      exposure:
        include: health,info,httptrace
  endpoint:
    httptrace:
      enabled: true

The equivalent newer endpoint may use httpexchanges instead:

management:
  endpoints:
    web:
      exposure:
        include: health,info,httpexchanges
  endpoint:
    httpexchanges:
      enabled: true

Do not copy both configurations blindly. The endpoint ID, enablement property, repository type, and available options depend on the Spring Boot generation.

Management path, port, and address

If the base path is customized, the URL changes accordingly:

management.endpoints.web.base-path=/management

With that setting, the historical endpoint would normally be addressed as /management/httptrace, subject to version and exposure rules.

A separate management port can isolate Actuator traffic:

management.server.port=9090

A management address can further restrict network access:

management.server.address=127.0.0.1

Use a narrow exposure list. Broad exposure, such as including every endpoint, can reveal configuration, environment, mappings, metrics, or other operational data. You can also review the environment endpoint, configuration properties endpoint, and mappings endpoint when diagnosing related configuration issues, but protect them carefully.

Collecting HTTP exchanges

In older Spring Boot versions, an HttpTraceRepository supplies recorded HTTP traces. The standard InMemoryHttpTraceRepository stores a bounded number of records in application memory.

In-memory behavior has important consequences:

• Records are local to one application instance.
• Records are lost when that instance restarts.
• Capacity is limited; old entries are removed as new entries arrive.
• A load balancer can send the application request and the management request to different instances.
• The repository is not a durable historical data store.

A custom repository is appropriate when you need a different capacity, filtering, header redaction, or controlled external persistence. In newer releases, use the version-matching HttpExchangeRepository abstraction instead of the older interface.

@Bean
HttpTraceRepository httpTraceRepository() {
  return new InMemoryHttpTraceRepository();
}

This is a conceptual older-version sketch, not a universal configuration. Confirm the interface and implementation names for your Spring Boot release before compiling it.

External persistence adds obligations: define retention, restrict access, encrypt data where appropriate, remove secrets, and handle privacy and regulatory requirements. Moving traces to a database or log platform does not make sensitive headers safe by itself.

Reading the endpoint response

The endpoint generally returns a JSON collection of exchanges. The exact JSON shape and field set vary by Spring Boot generation, web stack, repository implementation, and inclusion settings.

A sanitized response may conceptually contain records like this:

{
  "traces": [
    {
      "timestamp": "2026-08-25T10:15:30.123Z",
      "request": {
        "method": "GET",
        "uri": "http://localhost:8080/api/orders",
        "remoteAddress": "127.0.0.1",
        "headers": {
          "accept": ["application/json"]
        }
      },
      "response": {
        "status": 200,
        "headers": {
          "content-type": ["application/json"]
        }
      }
    }
  ]
}

Depending on the version, names or nesting may differ. Treat this example as a guide to the information categories, not as a guaranteed schema.

• Timestamp: helps identify the exchange among several recent calls.
• Method: distinguishes operations such as GET, POST, and DELETE.
• URI: identifies the requested path and sometimes query information.
• Remote address: can help identify the calling network peer, but may represent a proxy rather than the original client.
• Request headers: show selected client metadata when enabled.
• Response status: confirms whether the call produced a success, redirect, client error, or server error.
• Response headers: show selected server metadata when enabled.

To correlate a client call with a record, compare the method, path, approximate timestamp, and status code. If multiple instances exist, also confirm the instance that handled the request.

Practical example: inspect a recent API call

1. Start the application with Actuator and the appropriate endpoint configuration.
2. Send a request to an application endpoint, for example GET /api/orders.
3. Call the management endpoint on the same instance.
4. Find the entry whose method, URI, timestamp, and response status match the request.

curl http://localhost:8080/api/orders
curl -u ops-user:password http://localhost:8080/actuator/httptrace

For a newer Spring Boot release, the second command may instead be:

curl -u ops-user:password http://localhost:8080/actuator/httpexchanges

Never place a real password in shell history or shared command output. Prefer a secure credential mechanism for operational access.

Header inclusion, privacy, and secret handling

Trace data can contain sensitive request and response metadata. Headers may reveal authorization tokens, cookies, session identifiers, personal data, tenant information, internal hostnames, or confidential business details.

Older Spring Boot versions may support the management.trace.http.include property for selecting categories such as request headers, response headers, cookies, remote address, session ID, authorization header, and time taken. Supported values and behavior vary by release.

management:
  trace:
    http:
      include: time-taken,request-headers,response-headers

Select only the categories needed for the diagnostic task. In particular, do not enable authorization headers, cookies, session IDs, or broad header capture merely for convenience.

For custom repositories or surrounding infrastructure, use allowlists, value masking, and explicit redaction before storage. Redaction should cover common credential formats and application-specific secrets. HTTP traces are not a secure audit record: they are mutable, bounded diagnostics and may omit events or sensitive context needed for formal auditing.

Security and operational use

Protect the endpoint with Spring Security and grant access only to an operational role. A conceptual authorization rule should distinguish the management route and require a role such as ACTUATOR or OPS; the exact matcher syntax depends on the Spring Security version and management path.

• Expose only the required endpoint.
• Use a separate management port or restricted management address where practical.
• Require authentication and an operational role.
• Test both authorized and unauthorized requests.
• Ensure security matchers use the actual base path, port, and endpoint ID.
• Review captured data before enabling it in production.

This endpoint is generally best suited to development, local debugging, and controlled support procedures. Public production exposure can disclose request paths, network information, headers, and error behavior.

Version compatibility and migration

The transition from httptrace to httpexchanges is a compatibility boundary, not merely a preferred spelling. Defaults, available fields, endpoint response shape, and configuration options can differ.

Migration checklist

1. Identify references to /actuator/httptrace.
2. Identify HttpTraceRepository, InMemoryHttpTraceRepository, and older trace properties.
3. Check the target Spring Boot release's endpoint ID and repository abstraction.
4. Change the endpoint exposure and enablement settings to the version-appropriate names.
5. Update Spring Security matchers and operational roles.
6. Update monitoring scripts, health checks, support runbooks, and automated tests.
7. Send a known request and confirm that the new endpoint reports the expected exchange.

Troubleshooting

The endpoint returns 404

• Confirm that spring-boot-starter-actuator is present.
• Check whether the endpoint is enabled.
• Check whether it is included in web exposure.
• Verify the management base path, port, and address.
• Confirm whether the application uses httpexchanges instead of httptrace.
• If safely available, inspect the management root endpoint to see which endpoints are exposed.

The endpoint returns 401 or 403

• Spring Security may protect Actuator endpoints.
• The caller may lack the required management role.
• The security matcher may target a different base path or endpoint ID.
• Test with an authorized operations account and review endpoint-specific authorization rules.

The response is empty or omits the request

• Send and complete a known request before reading the repository.
• Ensure the request and management call reach the same application instance.
• Check load-balancer routing, proxy behavior, and instance identity.
• Consider whether a restart cleared the repository or a small capacity replaced the entry.
• Verify that the web stack and Spring Boot release support the assumed collection mechanism.

Expected headers or timing data are absent

• The inclusion category may not be configured.
• The property name or allowed value may differ in the current release.
• A custom repository may deliberately filter the field.
• Do not enable sensitive headers only to make debugging easier.

Sensitive data appears in trace output

• Restrict the endpoint immediately and remove unnecessary inclusion settings.
• Add allowlisting, masking, or redaction before storage.
• Review retention and incident-response procedures for data already captured.
• Check whether a proxy, log collector, or external repository also received the data.

Exam-relevant notes

• httptrace is the historical Actuator endpoint ID; later releases use httpexchanges.
• Endpoint enablement and HTTP web exposure are separate concepts.
• HttpTraceRepository is the older repository abstraction; HttpExchangeRepository is the newer terminology.
• The default repository is bounded and in memory, so data is lost on restart and is local to an instance.
• Management base path, management port, and security rules can all change how the endpoint is reached.
• Trace records can contain secrets and personal data; restrict access and redact sensitive values.
• Verify behavior against the exact Spring Boot version rather than assuming properties and JSON fields are interchangeable.