Clear documentation on when spans for HTTP requests are captured

[OliverRM]

Is there an existing issue for this?

• I have checked for existing issues https://github.com/getsentry/sentry-javascript/issues
• I have reviewed the documentation https://docs.sentry.io/
• I am using the latest SDK release https://github.com/getsentry/sentry-javascript/releases

How do you use Sentry?

Sentry Saas (sentry.io)

Which SDK are you using?

@sentry/node

SDK Version

10.32.1

Framework Version

Node v24.11.1

Link to Sentry event

No response

Reproduction Example/SDK Setup

The (documentation on Automatic Instrumentation)[https://docs.sentry.io/platforms/javascript/guides/node/tracing/instrumentation/automatic-instrumentation/] notes:

The Sentry SDK will automatically capture spans for the following: [...] Outgoing HTTP requests [...]

This suggests to me, that Sentry will capture spans for http requests, regardless of how I make the request. Especially, it makes me believe there is not more setup required but enabling tracing, at least when using common ways of sending HTTP requests like fetch or axios. Furthermore, I did not find any documentation that objects this assumption. But reality proved me wrong.

Steps to Reproduce

Consider the following code example:

import * as Sentry from "@sentry/node";

Sentry.init({
  dsn: "put your dsn here",
  debug: true,
  tracesSampleRate: 1.0,
});

// Does not capture any spans
console.log("--- Fetching sentry.io without span...");
await fetch("https://sentry.io/welcome/").then((res) => res.text());

// Captures data.on-request and http.client
console.log("--- Fetching sentry.io with span...");
await Sentry.startSpan(
  { op: "data.web-request", name: "Fetch sentry.io" },
  () => fetch("https://sentry.io/welcome/").then((res) => res.text())
);

// Axios: Only captures data.on-request span, not http.client
import axios from "axios";
console.log("--- Fetching sentry.io with axios and span...");
await Sentry.startSpan(
  { op: "data.on-request", name: "Get sentry.io using axios" },
  async () => { await axios.get("https://sentry.io"); }
);

Expected Result

I expect spans for all three HTTP requests to be captured, resulting in the following tree:

• http.get
• data.web-request Fetch sentry.io
  • http.get
• data.web-request Get sentry.io using axios
  • http.get (or something similar)

Actual Result

But only once the http request got captured, resulting in the following tree

• (Nothing captured during first request)
• data.web-request Fetch sentry.io
  • http.get
• data.web-request Get sentry.io using axios
  • (Nothing but my manual span got captured)

Here the full log:

Sentry Logger [log]: Initializing Sentry: process: 80138, thread: main.
Sentry Logger [log]: Cleared AI provider skip registrations
Sentry Logger [log]: Integration installed: InboundFilters
Sentry Logger [log]: Integration installed: FunctionToString
Sentry Logger [log]: Integration installed: LinkedErrors
Sentry Logger [log]: Integration installed: RequestData
Sentry Logger [log]: Integration installed: NodeSystemError
Sentry Logger [log]: Integration installed: Console
Sentry Logger [log]: Integration installed: OnUncaughtException
Sentry Logger [log]: Integration installed: OnUnhandledRejection
Sentry Logger [log]: Integration installed: ContextLines
Sentry Logger [log]: Integration installed: LocalVariablesAsync
Sentry Logger [log]: Integration installed: Context
Sentry Logger [log]: Integration installed: ChildProcess
Sentry Logger [log]: Integration installed: ProcessSession
Sentry Logger [log]: Integration installed: Modules
Sentry Logger [log]: Integration installed: Http
Sentry Logger [log]: Integration installed: NodeFetch
Sentry Logger [log]: Integration installed: Express
Sentry Logger [log]: Integration installed: Fastify
Sentry Logger [log]: Integration installed: Graphql
Sentry Logger [log]: Integration installed: Hono
Sentry Logger [log]: Integration installed: Mongo
Sentry Logger [log]: Integration installed: Mongoose
Sentry Logger [log]: Integration installed: Mysql
Sentry Logger [log]: Integration installed: Mysql2
Sentry Logger [log]: Integration installed: Redis
Sentry Logger [log]: Integration installed: Postgres
Sentry Logger [log]: Integration installed: Prisma
Sentry Logger [log]: Integration installed: Hapi
Sentry Logger [log]: Integration installed: Koa
Sentry Logger [log]: Integration installed: Connect
Sentry Logger [log]: Integration installed: Tedious
Sentry Logger [log]: Integration installed: GenericPool
Sentry Logger [log]: Integration installed: Kafka
Sentry Logger [log]: Integration installed: Amqplib
Sentry Logger [log]: Integration installed: LruMemoizer
Sentry Logger [log]: Integration installed: LangChain
Sentry Logger [log]: Integration installed: LangGraph
Sentry Logger [log]: Integration installed: VercelAI
Sentry Logger [log]: Integration installed: OpenAI
Sentry Logger [log]: Integration installed: Anthropic_AI
Sentry Logger [log]: Integration installed: Google_GenAI
Sentry Logger [log]: Integration installed: PostgresJs
Sentry Logger [log]: Integration installed: Firebase
Sentry Logger [log]: SDK initialized from ESM
Sentry Logger [log]: @opentelemetry/api: Registered a global for diag v1.9.0.
Sentry Logger [log]: @opentelemetry/api: Registered a global for trace v1.9.0.
Sentry Logger [log]: @opentelemetry/api: Registered a global for propagation v1.9.0.
Sentry Logger [log]: @opentelemetry/api: Registered a global for context v1.9.0.
--- Fetching sentry.io without span...
Sentry Logger [log]: Recording is off, propagating context in a non-recording span
--- Fetching sentry.io with span...
Sentry Logger [log]: [Tracing] Starting sampled root span
  op: data.web-request
  name: Fetch sentry.io
  ID: 6f861431b1b5a585
Sentry Logger [log]: [Tracing] Inheriting parent's sampled decision for GET: true
Sentry Logger [log]: [Tracing] Starting sampled span
  op: < unknown op >
  name: GET
  ID: 694fb2da65c6ad53
  parent ID: 6f861431b1b5a585
  root ID: 6f861431b1b5a585
  root op: data.web-request
  root description: Fetch sentry.io
Sentry Logger [log]: [Tracing] Finishing "< unknown op >" span "GET" with ID 694fb2da65c6ad53
Sentry Logger [log]: [Tracing] Finishing "data.web-request" root span "Fetch sentry.io" with ID 6f861431b1b5a585
--- Fetching sentry.io with axios and span...
Sentry Logger [log]: [Tracing] Starting sampled root span
  op: data.web-request
  name: Get sentry.io using axios
  ID: 54d126b00ef17e7f
Sentry Logger [log]: SpanExporter exported 2 spans, 0 spans are waiting for their parent spans to finish
Sentry Logger [log]: [Tracing] Finishing "data.web-request" root span "Get sentry.io using axios" with ID 54d126b00ef17e7f
Sentry Logger [log]: SpanExporter exported 1 spans, 0 spans are waiting for their parent spans to finish
Sentry Logger [log]: Flushing outcomes...
Sentry Logger [log]: No outcomes to send

Additional Context

For the first HTTP request, the log actually gives a hint on why no span was captured:

Sentry Logger [log]: Recording is off, propagating context in a non-recording span

I could not find any documentation on this log message, nor why recording is turned off or how to turn it on. For the axios request there is no information in the log at all on why it was not captured, nor does the documentation include information on the use of Sentry and axios.

Being new to Sentry, I can not judge whether this is intended behavior or not but if it is intended I suggest the documentation should be updated to explain under which circumstances Automatic Instrumentation captures spans for HTTP requests.

Priority

_{React with 👍 to help prioritize this issue. Please use comments to provide useful context, avoiding +1 or me too, to help us triage it.}

[linear]

JS-1365

[logaretm]

For tracing to work, there has to be a top-level span, or in other terms, a "traced operation". You can do that with Sentry.startSpan to wrap the whole operation you are doing, and then your fetch and axios calls will be traced.

In top-level the parent span isn't recorded so all nested operations will get dropped. A bit of a gotcha but the docs does show the example in a server environment which would work as expected since the http module would create a top recording span.

Another thing, is to make sure Sentry.init is called before all and any other imports. Your axios import doesn't actually get evaluated after Sentry's init.

In ES modules, all import statements are hoisted and their modules are evaluated before any other code in the importing module runs. The physical position of import statements in your file doesn't affect execution order.

I re-wrote your example into something that would work:

//instrument.js
import * as Sentry from "@sentry/node";

Sentry.init({
  dsn: "DSN",
  sendDefaultPii: true,
  tracesSampleRate: 1.0,
  debug: true,
});

//index.js
import axios from "axios";
import * as Sentry from "@sentry/node";

async function fetchSentry() {
  await fetch("https://sentry.io/welcome/").then((res) => res.text());

  // Axios: Only captures data.on-request span, not http.client
  console.log("--- Fetching sentry.io with axios...");

  await axios.get("https://sentry.io");
}

// Creates a top-level recording span
await Sentry.startSpan('fetch-sentry', fetchSentry);

Then make sure to run it with:

node --import ./instrument.mjs index.mjs

And you should see something like this in your traces: