# HTTP instrumentation configuration

## Capturing HTTP request and response headers

You can configure the agent to capture predefined HTTP headers as span
attributes, according to the
[semantic convention](/docs/specs/semconv/http/http-spans/). Use the following
properties to define which HTTP headers you want to capture:

<div class="config-option">
<details>
  <summary title="Expand to view environment variable">
    <span class="label">System property</span>:
      <code>otel.instrumentation.http.client.capture-request-headers</code>
  </summary>
  <span class="label">Environment variable</span>:
    <code>OTEL_INSTRUMENTATION_HTTP_CLIENT_CAPTURE_REQUEST_HEADERS</code>
</details>

<span class="label">Description</span>:
A comma-separated list of HTTP header names. HTTP client instrumentations will
capture HTTP request header values for all configured header names.
</div>


<div class="config-option">
<details>
  <summary title="Expand to view environment variable">
    <span class="label">System property</span>:
      <code>otel.instrumentation.http.client.capture-response-headers</code>
  </summary>
  <span class="label">Environment variable</span>:
    <code>OTEL_INSTRUMENTATION_HTTP_CLIENT_CAPTURE_RESPONSE_HEADERS</code>
</details>

<span class="label">Description</span>:
A comma-separated list of HTTP header names. HTTP client instrumentations will
capture HTTP response header values for all configured header names.
</div>


<div class="config-option">
<details>
  <summary title="Expand to view environment variable">
    <span class="label">System property</span>:
      <code>otel.instrumentation.http.server.capture-request-headers</code>
  </summary>
  <span class="label">Environment variable</span>:
    <code>OTEL_INSTRUMENTATION_HTTP_SERVER_CAPTURE_REQUEST_HEADERS</code>
</details>

<span class="label">Description</span>:
A comma-separated list of HTTP header names. HTTP server instrumentations will
capture HTTP request header values for all configured header names.
</div>


<div class="config-option">
<details>
  <summary title="Expand to view environment variable">
    <span class="label">System property</span>:
      <code>otel.instrumentation.http.server.capture-response-headers</code>
  </summary>
  <span class="label">Environment variable</span>:
    <code>OTEL_INSTRUMENTATION_HTTP_SERVER_CAPTURE_RESPONSE_HEADERS</code>
</details>

<span class="label">Description</span>:
A comma-separated list of HTTP header names. HTTP server instrumentations will
capture HTTP response header values for all configured header names.
</div>


These configuration options are supported by all HTTP client and server
instrumentations.

> **Note**: The property/environment variable names listed in the table are
> still experimental, and thus are subject to change.

## Capturing servlet request parameters

You can configure the agent to capture predefined HTTP request parameters as
span attributes for requests that are handled by the Servlet API. Use the
following property to define which servlet request parameters you want to
capture:

<div class="config-option">
<details>
  <summary title="Expand to view environment variable">
    <span class="label">System property</span>:
      <code>otel.instrumentation.servlet.experimental.capture-request-parameters</code>
  </summary>
  <span class="label">Environment variable</span>:
    <code>OTEL_INSTRUMENTATION_SERVLET_EXPERIMENTAL_CAPTURE_REQUEST_PARAMETERS</code>
</details>

<span class="label">Description</span>:
A comma-separated list of request parameter names.
</div>


> **Note**: The property/environment variable names listed in the table are
> still experimental, and thus are subject to change.

## Configuring known HTTP methods

Configures the instrumentation to recognize an alternative set of HTTP request
methods. All other methods will be treated as `_OTHER`.

<div class="config-option">
<details>
  <summary title="Expand to view environment variable">
    <span class="label">System property</span>:
      <code>otel.instrumentation.http.known-methods</code>
  </summary>
  <span class="label">Environment variable</span>:
    <code>OTEL_INSTRUMENTATION_HTTP_KNOWN_METHODS</code>
</details>

<span class="label">Default</span>: CONNECT,DELETE,GET,HEAD,OPTIONS,PATCH,POST,PUT,TRACE<br>
<span class="label">Description</span>:
A comma-separated list of known HTTP methods.
</div>


## Enabling experimental HTTP telemetry

You can configure the agent to capture additional experimental HTTP telemetry
data.

<div class="config-option">
<details>
  <summary title="Expand to view environment variable">
    <span class="label">System property</span>:
      <code>otel.instrumentation.http.client.emit-experimental-telemetry</code>
  </summary>
  <span class="label">Environment variable</span>:
    <code>OTEL_INSTRUMENTATION_HTTP_CLIENT_EMIT_EXPERIMENTAL_TELEMETRY</code>
</details>

<span class="label">Default</span>: false<br>
<span class="label">Description</span>:
Enables the experimental HTTP client telemetry.
</div>


<div class="config-option">
<details>
  <summary title="Expand to view environment variable">
    <span class="label">System property</span>:
      <code>otel.instrumentation.http.server.emit-experimental-telemetry</code>
  </summary>
  <span class="label">Environment variable</span>:
    <code>OTEL_INSTRUMENTATION_HTTP_SERVER_EMIT_EXPERIMENTAL_TELEMETRY</code>
</details>

<span class="label">Default</span>: false<br>
<span class="label">Description</span>:
Enables the experimental HTTP server telemetry.
</div>


For client and server spans, the following attributes are added:

- `http.request.body.size` and `http.response.body.size`: The size of the
  request and response bodies, respectively.

For client metrics, the following metrics are created:

- [http.client.request.body.size](/docs/specs/semconv/http/http-metrics/#metric-httpclientrequestbodysize)
- [http.client.response.body.size](/docs/specs/semconv/http/http-metrics/#metric-httpclientresponsebodysize)

For server metrics, the following metrics are created:

- [http.server.active_requests](/docs/specs/semconv/http/http-metrics/#metric-httpserveractive_requests)
- [http.server.request.body.size](/docs/specs/semconv/http/http-metrics/#metric-httpserverrequestbodysize)
- [http.server.response.body.size](/docs/specs/semconv/http/http-metrics/#metric-httpserverresponsebodysize)