proposal: Add Hook/Interceptor for `go` Statement (Goroutine Start)

[tzvatot]

Proposal: Add Hook/Interceptor for go Statement (Goroutine Start)

Abstract

This proposal suggests adding a mechanism to observe, log, or monitor every invocation of a goroutine via the go statement. This would allow developers to instrument goroutine creation for observability and debugging purposes, without needing to refactor codebases extensively.

Background & Motivation

Goroutines are a central feature of Go, offering lightweight concurrency. However, because go is a language keyword and not a function, there is no standard way to intercept or observe the spawning of goroutines.

The inability to intercept go calls limits:

• Runtime observability of concurrent behavior
• Accurate logging and tracing of goroutine life cycles
• Debugging tools that need visibility into all concurrent flows
• Runtime enforcement of policies related to goroutine usage (e.g., limits, tags, priorities, etc.)

Inspired by projects such as openshift-online/async-routine, this proposal aims to bring similar capabilities into the language or standard tooling in a first-class way.

Proposal

Introduce a mechanism—either at the language, compiler, or runtime level—that enables registering a hook function which is invoked on every goroutine creation.

The hook function might take the following form:

type GoroutineStartHook func(func())

func RegisterGoroutineStartHook(hook GoroutineStartHook)

When registered, the Go runtime (or compiler-generated code) would wrap every goroutine call:

go func() {
    // original code
}()

Would behave as:

go runtime.invokeGoroutineStartHook(func() {
    // original code
})

Where invokeGoroutineStartHook would call the registered hook function, which can decide how to instrument, log, or even conditionally block execution.

Compatibility

• Backwards compatible: Existing code that doesn’t register a hook will behave exactly as today.
• Tooling-friendly: Hook registration could be used via build tags, environment variables, or initialization code in main packages.

Alternatives Considered

• Wrapping go calls manually in a helper function (Go(func())) — this does not scale and requires pervasive code changes. Does not work for 3rd party imports.
• Static analysis or source code instrumentation — useful, but not as robust or flexible as runtime-level interception.
• Debuggers or profilers — provide observability but not programmable hooks or live instrumentation.
• Introduction of a new, experimental package, perhaps named runtime/intercept or similar, that provides a mechanism to register a global interceptor function for go routine creation. If adopted, can be used as a standard mechinism to spawn go routines with the ability to intercept.

Use Cases

• Observability: Log every goroutine with context (file, line, stack).
• Tracing: Connect goroutine creation to a distributed trace.
• Debugging: Detect goroutines that never terminate or take too much time to execute.
• Security: Monitor or block goroutines based on policy.

Risks & Downsides

• Performance overhead: Every go statement incurs a hook invocation. This must be optional and optimized when disabled.
• Complexity: Adds indirection to goroutine start-up, which must be minimal and well-tested.
• Semantic expectations: Developers may expect go to be zero-cost. This breaks that assumption when hooks are enabled.

Prior Art

• async-routine: Provides a wrapper around goroutines that enables timeboxing, observability, and monitoring.
• JVM / CLR: Many managed runtimes allow thread start interception or instrumentation via AOP tools or runtime hooks.

Implementation Notes

The feature could be implemented at the compiler level (cmd/compile) by wrapping goroutine calls with a runtime dis

[seankhliao]

I think this goes against Go's design for clarity and simplicity.

if you really wanted, you can do rewrites with toolexec. I don't see this as something to be natively supported.

[tzvatot]

I think this goes against Go's design for clarity and simplicity.

if you really wanted, you can do rewrites with toolexec. I don't see this as something to be natively supported.

Thanks for the feedback!

Would you mind elaborating on how exactly this proposal goes against Go’s design?

While I agree that interception adds some complexity, I’d argue that the current simplicity of using go to spawn goroutines comes with a significant tradeoff: there is no built-in way to monitor, trace, or block potentially problematic goroutines — such as those that leak, run too long, or deadlock.

In production systems, these issues can lead to resource exhaustion or outages, and developers often end up building their own wrappers to compensate. However, such solutions only work for in-house code and cannot cover goroutines started by third-party libraries. This limitation not only makes observability difficult, but also risks reducing Go's appeal for large-scale, production-grade systems where runtime insight is critical.

I understand that rewrites with toolexec are technically possible, but that approach adds fragility, limits maintainability, and is not a viable solution for 3rd party code.

Curious to hear your thoughts — especially if there’s a design principle I’m overlooking.

[rittneje]

I don't think it is possible to detect that a particular goroutine has deadlocked in general. Isn't that the halting problem?

"Run too long" is highly context-dependent, so I don't see how you could conclude such a thing in a generic hook. And even if you did, what recourse can you take? You can't kill a goroutine. And killing the entire binary would be quite drastic.

Leaks are in a similar boat. I don't see how a generic wrapper could determine this with certainty.

Monitoring and tracing would presumably need the context.Context. But I don't see where your proposed hook would get that from.

[tzvatot]

don't think it is possible to detect that a particular goroutine has deadlocked in general. Isn't that the halting problem?

"Run too long" is highly context-dependent, so I don't see how you could conclude such a thing in a generic hook. And even if you did, what recourse can you take? You can't kill a goroutine. And killing the entire binary would be quite drastic.

Leaks are in a similar boat. I don't see how a generic wrapper could determine this with certainty.

You're absolutely right that we can't prove a goroutine is deadlocked in the general case — that would indeed fall into halting problem territory. Similarly, what qualifies as "running too long" can be highly context-dependent.

But the intention here isn’t to make absolute judgments. Rather, the goal is to enable instrumentation and observability so developers can define their own heuristics based on their application’s context.

If we could capture metadata like the package, file, and line number where a goroutine was launched — along with a stack trace or runtime state — then developers could monitor and flag goroutines that appear stuck or long-running based on their own thresholds. For example, if a goroutine has been blocked on a mutex or channel for 5 minutes, that’s a strong signal something is wrong, even if it’s not a formal deadlock.

The key point is that today, Go provides no runtime facility to even observe this — we’re forced to guess or manually wrap goroutines, which doesn’t scale or cover third-party code. A generic hook wouldn't prescribe behavior, but would empower developers to apply policies appropriate to their context.
This kind of tooling is incredibly useful in production environments where silent goroutine leaks can bring down systems without any visibility. The ability to monitor and reason about runtime behavior — even if imperfect — is far better than flying blind.

Monitoring and tracing would presumably need the context.Context. But I don't see where your proposed hook would get that from.

That’s a fair point — most meaningful monitoring or tracing requires context.Context to propagate deadlines, cancellation, or trace IDs.

The generic hook proposed here wouldn’t be able to extract a context from arbitrary goroutine functions — but we could support it in a few ways:

• Opt-in API: We could encourage patterns like goctx.Start(ctx, func(ctx context.Context) { ... }), where the context is passed explicitly. The hook would then receive that context as part of its metadata.
• Metadata struct: The hook could receive a GoRoutineMeta struct, which includes the caller location, stack trace, and (optionally) a context if available.
• Partial visibility is better than none: While not every goroutine will provide a context, many modern ones do — and this mechanism would make it possible to monitor and trace those, which today is difficult or impossible without pervasive wrapping.

This wouldn't replace structured use of context.Context — rather, it complements it by allowing better tooling, especially around goroutines created deep in the stack or by third-party libraries.

[oriAdler]

I support this proposal. In production, goroutine leaks are really hard to trace, especially when Go is used deep inside third-party libraries or scattered across a large codebase. Since there’s no way to intercept goroutine creation, you can’t build meaningful diagnostics without rewriting code.

I get that adding hooks goes against Go’s simplicity, but in this case, I think the tradeoff is worth it. An opt-in hook would make it much easier to catch leaks in real systems.

[rhysh]

If we could capture metadata like the package, file, and line number where a goroutine was launched — along with a stack trace or runtime state — then developers could monitor and flag goroutines that appear stuck or long-running based on their own thresholds. For example, if a goroutine has been blocked on a mutex or channel for 5 minutes, that’s a strong signal something is wrong, even if it’s not a formal deadlock.

This sounds like the goroutine profile with debug=2. For each goroutine, that will show the current call stack and the line number that created the goroutine. For goroutines that have been blocked for multiple minutes, the output will include the number of minutes the goroutine has been blocked. (Note that debug=2 does a slower / more expensive profile than debug=0 and debug=1.) See for example https://go.dev/play/p/JSSp52GRtuU. Its output includes

goroutine 3 [chan receive, 2 minutes]:
main.main.func1()
	/tmp/sandbox3848967920/prog.go:15 +0x19
created by main.main in goroutine 1
	/tmp/sandbox3848967920/prog.go:14 +0x66

there is no built-in way to monitor, trace, or block potentially problematic goroutines — such as those that leak, run too long, or deadlock.

Rather, the goal is to enable instrumentation and observability

The key point is that today, Go provides no runtime facility to even observe this — we’re forced to guess or manually wrap goroutines, which doesn’t scale or cover third-party code.

you can’t build meaningful diagnostics without rewriting code.

The Go runtime has built-in tooling to trace a program's execution. It includes details of which goroutines created which others, when/where they blocked, what allowed them to run again, etc. It's a live log of ongoing behavior, so it doesn't describe events that took place before the program enabled the execution trace. It's also hard to use! But it describes the behavior of all goroutines in a program, across all packages, without source-level modification. See the runtime/trace package for a starting point.

It might also help to approach this from an "experience report" perspective: describing the problems you've encountered that are hard to solve. Thank you for adding some of those details in the comments.

[AlexVulaj]

+1 to this proposal, particularly for the case of more intuitive timeboxing when creating go routines. I'm also in favor of explicitly passing in a context similar to how NewAsyncRoutine functions in the referenced async-routine project.

[tzvatot]

This sounds like the goroutine profile with debug=2. For each goroutine, that will show the current call stack and the line number that created the goroutine. For goroutines that have been blocked for multiple minutes, the output will include the number of minutes the goroutine has been blocked. (Note that debug=2 does a slower / more expensive profile than debug=0 and debug=1.

You're right that goroutine profile with debug=2 provides file and line number information — but I’d argue that it’s not sufficient for production-grade observability, especially at scale.

• Raw stack traces aren't structured: The output is plain text intended for human debugging, not for reliable parsing or integration with monitoring systems. Scraping and interpreting these traces in real time across thousands of goroutines is error-prone and inefficient.

• Snapshot-only: The goroutine profile provides a point-in-time snapshot. There’s no way to subscribe to lifecycle events (e.g., "goroutine started" or "goroutine blocked for >5 min") or track goroutine behavior over time without repeatedly polling and parsing the stack trace output.

• No correlation or metadata: There’s no built-in way to attach metadata (e.g., request ID, context, component name) or correlate goroutines with application-level concepts. That makes it very difficult to reason about runtime behavior in a structured way.

What I’m proposing is not to replace debug=2, but to complement it with a lightweight, structured interception mechanism that enables tooling and observability platforms to get meaningful, machine-readable insights in real time — without relying on fragile scraping or runtime hacks.

The Go runtime has built-in tooling to trace a program's execution. It includes details of which goroutines created which others, when/where they blocked, what allowed them to run again, etc. It's a live log of ongoing behavior, so it doesn't describe events that took place before the program enabled the execution trace. It's also hard to use! But it describes the behavior of all goroutines in a program, across all packages, without source-level modification. See the runtime/trace package for a starting point.

runtime/trace is definitely a powerful tool, and it's great for visualizing goroutine lifecycles, blocking events, and scheduling behavior. However, it has some practical limitations — especially in the context of observability and control in large applications:

• No interception: runtime/trace provides passive visibility into what’s happening in the runtime, but it doesn’t allow interception or enforcement. You can’t, for example, hook into the moment a goroutine is created or flag it if it exceeds a certain runtime duration.

• Limited insight into third-party code: While we can instrument our own code with trace.WithRegion, context.Context, or other structured annotations, we have no control over goroutines created by third-party libraries. That’s a major gap, as these libraries may spawn goroutines we can’t observe, manage, or annotate meaningfully.

• Heavyweight and episodic: runtime/trace is designed for short, intensive debugging sessions — not continuous, lightweight monitoring in production. It typically requires enabling tracing at startup, writing to a file, and post-processing the trace offline.

My proposal is meant to provide a lightweight, real-time interception mechanism that complements tools like runtime/trace by allowing developers to observe and optionally track goroutine creation — including those from third-party packages — with consistent metadata.

[lucasponce]

I share the motivation for this request.

The Golang ecosystem is growing, and companies are building more complex software with the Go language.

I do see this related to the "no_goroutine_id" statement in the Go language:
https://go.dev/doc/faq#no_goroutine_id

I'd like to know if the Go community can progress in this direction (using this request as a motivation and/or inspiration for the problem).

It would be great to have native capabilities to identify where the code is running [1], and potentially and optionally introduce more "aspects" in the lifecycle (as described in this request).

The benefit of having a native design will help Golang users from designing N frameworks to solve similar problems in an "ad-hoc" manner; meanwhile, having a unified approach supported by the community will help to lead how these frameworks should go.

[1]

Thread.currentThread().getId()

[RamLavi]

+1.
Having a standard way to log or see every go call would make it a lot easier to debug tricky concurrency issues and generally understand what our complex apps are doing under the hood, without developers having to add a bunch of manual tracking code all over the place.
I would however take extra notice to see that such a mechanism doesn't change runtime performance greatly.

[yaacov]

Having a standard way to log or see every go call would make it a lot easier to debug tricky

I would also like an opt-in way to turn on a way to debug/log leaking go routines that is standard.
It is very easy in the "real world" to create go routine leaks and debugging them is hard, especially if the leaking go routine are in a 3rd party code you can't wrap or log manually.

I would however take extra notice to see that such a mechanism doesn't change runtime

I would like this tool to be "opt in" , so it will be ignored except if users explicitly turn in on on.
My concerns are:
a. this debug tool should not change compiled binaries unless explicitly turned on
b. this tool should not replace correct usage of context to prevent routine leaks

[Lir10]

👍 +1, this would be super helpful for tracing and debugging goroutine issues at scale. Native support > workarounds like wrapping or static analysis. Would love to see this land.