# FastProxy Observability Features: Built-in pprof Profiling and Debug Endpoints

> Explore FastProxy's observability features like built-in pprof profiling and debug endpoints for easy CPU, memory, and goroutine analysis. Enhance your Go application monitoring.

- Repository: [Kingson4Wu/fast_proxy](https://github.com/kingson4wu/fast_proxy)
- Tags: deep-dive
- Published: 2026-03-05

---

**FastProxy exposes runtime profiling data through Go’s standard `net/http/pprof` package, automatically registering `/debug/pprof` endpoints for CPU, memory, goroutine, and block analysis without external dependencies.**

FastProxy, from the `kingson4wu/fast_proxy` repository, includes production-ready observability features that allow operators to introspect running proxy instances. The codebase leverages Go’s built-in pprof tooling to expose diagnostic HTTP endpoints, enabling real-time profiling of resource consumption and concurrency behavior. These capabilities are integrated directly into the proxy binaries and require no additional configuration or third-party agents.

## How FastProxy Implements Observability

### Automatic pprof Handler Registration

Both the inbound and outbound proxy binaries import the Go standard library’s pprof package to enable automatic handler registration. In [`fast_proxy/main/inproxy/inproxy.go`](https://github.com/kingson4wu/fast_proxy/blob/main/fast_proxy/main/inproxy/inproxy.go) and [`fast_proxy/main/outproxy/outproxy.go`](https://github.com/kingson4wu/fast_proxy/blob/main/fast_proxy/main/outproxy/outproxy.go), the blank import activates the side-effect registration of pprof HTTP handlers:

```go
// fast_proxy/main/inproxy/inproxy.go
import _ "net/http/pprof"

// fast_proxy/main/outproxy/outproxy.go  
import _ "net/http/pprof"

```

This import ensures that the `net/http/pprof` init function runs, registering profiling handlers with the default serve mux. FastProxy then adapts these handlers for the fasthttp framework used throughout the project.

### FastHTTP Route Configuration

The central server implementation in [`fast_proxy/main/common/server/server.go`](https://github.com/kingson4wu/fast_proxy/blob/main/fast_proxy/main/common/server/server.go) bridges standard `net/http` pprof handlers to the fasthttp router using an adaptor. The code creates a handler and maps it to the `/debug/pprof` path prefix:

```go
// fast_proxy/main/common/server/server.go
pprofHandler := fasthttpadaptor.NewFastHTTPHandler(fgprof.Handler())
otherHandlers["/debug/pprof"] = pprofHandler

```

Incoming requests are routed based on path prefix matching. When a request path begins with `/debug/pprof`, the server invokes the adapted handler:

```go
if strings.HasPrefix(path, "/debug/pprof") {
    pprofHandler(ctx)
}

```

This implementation exposes the full suite of Go runtime profiling data through the fasthttp server listening on the configured proxy port.

## Available Observability Endpoints

FastProxy exposes the standard Go pprof endpoints under the `/debug/pprof` path. You can access the following runtime profiles:

- **`/debug/pprof/profile`** – CPU profiler (responds after the specified duration)
- **`/debug/pprof/heap`** – Sampling of memory allocations
- **`/debug/pprof/goroutine`** – Stack traces of all current goroutines
- **`/debug/pprof/block`** – Stack traces that led to blocking on synchronization primitives
- **`/debug/pprof/mutex`** – Stack traces of holders of contended mutexes
- **`/debug/pprof/allocs`** – Sampling of past memory allocations
- **`/debug/pprof/threadcreate`** – Stack traces that led to the creation of new OS threads
- **`/debug/pprof/cmdline`** – The command line invocation of the current program
- **`/debug/pprof/symbol`** – Symbol resolution for addresses (used by pprof tool)

## Practical Usage Examples

The following commands demonstrate how to extract profiling data from a running FastProxy instance listening on `localhost:8080`.

### Capture a 10-Second CPU Profile

```bash
go tool pprof -http=:8081 http://localhost:8080/debug/pprof/profile?seconds=10

```

This command downloads the profile and opens an interactive web UI at `http://localhost:8081` for analysis.

### Export a Heap Memory Snapshot

```bash
curl -s http://localhost:8080/debug/pprof/heap > heap.prof
go tool pprof -http=:8082 heap.prof

```

### View Live Goroutine Stacks

```bash
curl http://localhost:8080/debug/pprof/goroutine?debug=2

```

Setting `debug=2` returns the full goroutine stack traces in plain text, useful for detecting deadlocks or leaks.

### Analyze Block Contention

```bash
go tool pprof -http=:8083 http://localhost:8080/debug/pprof/block

```

## Source Code Reference

The observability functionality is concentrated in these specific source files within the `kingson4wu/fast_proxy` repository:

| File | Purpose |
|------|---------|
| [`fast_proxy/main/inproxy/inproxy.go`](https://github.com/kingson4wu/fast_proxy/blob/main/fast_proxy/main/inproxy/inproxy.go) | Blank imports `net/http/pprof` to activate profiling handlers for the inbound proxy. |
| [`fast_proxy/main/outproxy/outproxy.go`](https://github.com/kingson4wu/fast_proxy/blob/main/fast_proxy/main/outproxy/outproxy.go) | Blank imports `net/http/pprof` to activate profiling handlers for the outbound proxy. |
| [`fast_proxy/main/common/server/server.go`](https://github.com/kingson4wu/fast_proxy/blob/main/fast_proxy/main/common/server/server.go) | Configures the fasthttp route `/debug/pprof` and adapts pprof handlers using `fasthttpadaptor`. |
| [`pprof/pprof.sh`](https://github.com/kingson4wu/fast_proxy/blob/main/pprof/pprof.sh) | Convenience shell script for launching pprof analysis against a running instance. |
| [`pprof/wrk.sh`](https://github.com/kingson4wu/fast_proxy/blob/main/pprof/wrk.sh) | Load testing script that can be paired with profiling to analyze performance under stress. |

## Summary

- **Zero-configuration profiling**: FastProxy automatically exposes Go pprof endpoints via `net/http/pprof` imports in both inproxy and outproxy binaries.
- **Fasthttp integration**: The [`common/server/server.go`](https://github.com/kingson4wu/fast_proxy/blob/main/common/server/server.go) file adapts standard HTTP pprof handlers to the fasthttp framework using `fasthttpadaptor`.
- **Comprehensive runtime data**: Access CPU, memory, goroutine, block, and mutex profiles through the `/debug/pprof` route prefix.
- **Standard tooling compatible**: Use `go tool pprof`, `curl`, or browser-based visualization to analyze proxy performance and resource usage.

## Frequently Asked Questions

### What observability protocols does FastProxy support?

FastProxy supports Go’s standard pprof profiling protocol via HTTP endpoints. It does not natively expose Prometheus metrics, OpenTelemetry traces, or structured JSON logs; observability is focused on runtime profiling through the `/debug/pprof` path.

### How do I access profiling data in FastProxy?

Send an HTTP request to the `/debug/pprof/` endpoint on the proxy’s listening port. For interactive analysis, use `go tool pprof -http=:PORT http://<proxy-host>:<port>/debug/pprof/profile` for CPU profiles, or `curl` the heap, goroutine, and block endpoints to save raw data for offline analysis.

### Does FastProxy support Prometheus metrics?

No. Analysis of the `kingson4wu/fast_proxy` source code reveals no Prometheus client library imports or metric exposition endpoints. The repository relies exclusively on Go’s built-in pprof facilities for observability. To export metrics to Prometheus, you would need to implement a custom metrics handler or sidecar.

### Can I disable observability endpoints in production?

The pprof endpoints are registered automatically through the blank import in [`inproxy.go`](https://github.com/kingson4wu/fast_proxy/blob/main/inproxy.go) and [`outproxy.go`](https://github.com/kingson4wu/fast_proxy/blob/main/outproxy.go) and the route configuration in [`server.go`](https://github.com/kingson4wu/fast_proxy/blob/main/server.go). To disable them, you would need to remove the `import _ "net/http/pprof"` lines and delete the `/debug/pprof` route registration from [`common/server/server.go`](https://github.com/kingson4wu/fast_proxy/blob/main/common/server/server.go), then recompile the binaries. There is no configuration flag to disable these endpoints at runtime.