HTTP

HTTP tracing is configured with the top-level http option.

Alongside the standard HTTP instrumentation options, Monocle adds few specific features:

• sanitizeUrls to redact sensitive query parameters from URL span attributes
• captureBodies to record request and response payloads on spans

Both features are disabled by default. Configure sanitizeUrls to enable URL sanitization. For body capture, set captureBodies.enabled: true, or opt in per side with incoming.request.enabled, incoming.response.enabled, and so on.

export default defineConfig({
  // ...

  // High-level HTTP tracing options.
  http: {
    // Ignore noisy routes before spans are exported.
    ignoredUrls: ['/internal/*', '/api/ping'],

    // Redact sensitive query params in URL span attributes.
    sanitizeUrls: {
      queryParams: ['code', 'state', 'token', 'id_token', 'session_state'],
      censor: 'REDACTED',
    },

    // Capture request and response payloads on HTTP spans.
    captureBodies: {
      enabled: true,

      // Server-side traffic handled by your Adonis app.
      incoming: {
        request: {
          // Limit the number of bytes stored on the span.
          maxBodySize: 16_384,
        },
        response: {},
      },

      // Client-side traffic instrumented by node:http / node:https.
      outgoing: {
        request: {},
        response: {},
      },

      // Declarative redaction merged with Monocle's built-in safe defaults.
      redact: {
        bodyKeys: ['password', 'token', 'secret'],
        headers: ['authorization', 'cookie'],
        queryParams: ['token'],
        censor: 'REDACTED',
      },

      // Final hook to mutate or replace the captured payload.
      transform: (record) => {
        if (!record.http.url?.includes('/oauth/callback')) return

        record.http.body = { redacted: true }
      },
    },
  },
})

URL sanitization

sanitizeUrls rewrites URL span attributes such as http.url, url.full, http.target, and url.query.

export default defineConfig({
  // ...

  http: {
    sanitizeUrls: {
      queryParams: ['code', 'state', 'id_token', 'session_state'],
    },
  },
})

For example, an OAuth callback like:

/oauth/callback?code=oauth-code&state=oauth-state&id_token=jwt-token

becomes:

/oauth/callback?code=REDACTED&state=REDACTED&id_token=REDACTED

For more control, you can provide a custom sanitize function that takes the full URL object and returns a sanitized string.

export default defineConfig({
  // ...
  http: {
    sanitizeUrls: {
      sanitize: (url) => {
        // Only keep the pathname for OAuth callbacks
        if (url.pathname === '/oauth/callback') return url.pathname

        // Otherwise, keep the full URL
        return url.href
      },
    },
  },
})

Body capture scope

incoming captures traffic handled by your Adonis app:

• incoming.request for the HTTP request body sent to your server
• incoming.response for the HTTP response body returned by your server

outgoing captures traffic created by Node HTTP clients inside your app:

• outgoing.request for the request body your app sends to another service
• outgoing.response for the response body returned by that service

Body capture defaults

captureBodies is opt-in because payload capture can expose sensitive data.

When enabled, Monocle:

• captures application/json and application/x-www-form-urlencoded by default
• stores at most 10_000 bytes per request or response unless you increase maxBodySize
• shows captured payloads in the HTTP Body tab of the trace details view

Redaction order

captureBodies.redact applies declarative redaction rules first.

captureBodies.transform runs after that and lets you mutate or replace the captured payload programmatically.

The declarative redact rules extend Monocle's built-in safe defaults. Common secrets such as password, token, code, access_token, refresh_token, authorization, and many others are redacted automatically even if you do not list them yourself.

Advanced overrides

If you need low-level OpenTelemetry overrides, you can still configure instrumentations["@opentelemetry/instrumentation-http"].

When both are present, the low-level instrumentation config takes priority over the top-level http option.