> This page is for version 0.6.0.
> For other versions, use one of these documentation indexes:
> - Main (default): https://docs.nvidia.com/nemo/gym/main/llms.txt
> - 0.7.0: https://docs.nvidia.com/nemo/gym/v0.7.0/llms.txt
> - 0.6.0: https://docs.nvidia.com/nemo/gym/v0.6.0/llms.txt
> - 0.5.1: https://docs.nvidia.com/nemo/gym/v0.5.1/llms.txt
> - 0.5.0: https://docs.nvidia.com/nemo/gym/v0.5.0/llms.txt
> - 0.4.0: https://docs.nvidia.com/nemo/gym/v0.4.0/llms.txt
> - 0.3.0: https://docs.nvidia.com/nemo/gym/v0.3.0/llms.txt
> - 0.2.1: https://docs.nvidia.com/nemo/gym/v0.2.1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo/gym/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo/gym/_mcp/server.

# nemo_gym.server_runtime.request_handling.trace_context

Middleware that reads trace context carried in a request's URL path.

## Module Contents

### Classes

| Name                                                                                                               | Description                                                                                     |
| ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
| [`TraceContextPathMiddleware`](#nemo_gym-server_runtime-request_handling-trace_context-TraceContextPathMiddleware) | Strip `/ng-trace/<traceparent>` from the path and supply it as the inbound `traceparent`. |

### Functions

| Name                                                                                                                               | Description                                                                                         |
| ---------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| [`_restore_trace_segment_on_redirect`](#nemo_gym-server_runtime-request_handling-trace_context-_restore_trace_segment_on_redirect) | Put `/ng-trace/<traceparent>` back into root-relative and same-origin redirect targets.       |
| [`install_trace_context_path`](#nemo_gym-server_runtime-request_handling-trace_context-install_trace_context_path)                 | Install `TraceContextPathMiddleware` outside the instrumentor, which reads headers and path when it |

### Data

[`_ROLLOUT_PREFIX_PATTERN`](#nemo_gym-server_runtime-request_handling-trace_context-_ROLLOUT_PREFIX_PATTERN)

[`_ROLLOUT_PREFIX_RE`](#nemo_gym-server_runtime-request_handling-trace_context-_ROLLOUT_PREFIX_RE)

[`_TRACE_CONTEXT_PATH_RE`](#nemo_gym-server_runtime-request_handling-trace_context-_TRACE_CONTEXT_PATH_RE)

### API

```python
class nemo_gym.server_runtime.request_handling.trace_context.TraceContextPathMiddleware(
    app: starlette.types.ASGIApp
)
```

Strip `/ng-trace/<traceparent>` from the path and supply it as the inbound `traceparent`.

The segment comes from `apply_rollout_prefix`: a model URL an agent hands to a client that
sends no `traceparent` header, such as a harness inside a sandbox. A header the client did
send wins. The segment is stripped whether or not traces are on, so such a URL always routes.

```python
nemo_gym.server_runtime.request_handling.trace_context.TraceContextPathMiddleware.__call__(
    scope: starlette.types.Scope,
    receive: starlette.types.Receive,
    send: starlette.types.Send
) -> None
```

async

```python
nemo_gym.server_runtime.request_handling.trace_context._restore_trace_segment_on_redirect(
    message: starlette.types.Message,
    segment: str,
    request_headers: list[tuple[bytes, bytes]]
) -> starlette.types.Message
```

Put `/ng-trace/<traceparent>` back into root-relative and same-origin redirect targets.

Inserted after a rollout or token-capture prefix (which the capture middleware has already restored)
or at the root; cross-origin targets and targets that already carry a segment are left alone.

```python
nemo_gym.server_runtime.request_handling.trace_context.install_trace_context_path(
    app: fastapi.FastAPI
) -> None
```

Install `TraceContextPathMiddleware` outside the instrumentor, which reads headers and path when it
opens the server span. Same mechanism as `install_request_context_isolation`; call it after
`instrument_app_for_telemetry` and before `install_request_context_isolation`, which stays outermost.

```python
nemo_gym.server_runtime.request_handling.trace_context._ROLLOUT_PREFIX_PATTERN = f'/{re.escape(ROLLOUT_PATH_PREFIX)}/[^/]+(?:/{re.escape(TOKEN_CAPTURE_PATH_SEGME...
```

```python
nemo_gym.server_runtime.request_handling.trace_context._ROLLOUT_PREFIX_RE = re.compile(f'^{_ROLLOUT_PREFIX_PATTERN}(?=/|$)')
```

```python
nemo_gym.server_runtime.request_handling.trace_context._TRACE_CONTEXT_PATH_RE = re.compile(f'^(?P<head>(?:{_ROLLOUT_PREFIX_PATTERN})?)/{re.escape(TRACE_CONTEXT_...
```