Go + Gin

This guide covers adding debugger to a Go API using the Gin web framework. The setup takes three lines of code.

Gin official docs

Prerequisites

• Go 1.21 or later

Install

Add the debugger module to your project:

go get github.com/ephem-sh/debugger/packages/debugger-go

Set up

Import the Gin middleware package and add it to your router:

package main

import (
    "net/http"

    "github.com/gin-gonic/gin"
    dbg "github.com/ephem-sh/debugger/packages/debugger-go/middleware/gin"
)

func main() {
    defer dbg.Close()
    log := dbg.Logger()

    r := gin.New()
    r.Use(gin.Recovery())
    r.Use(dbg.Middleware(8080))

    r.GET("/", func(c *gin.Context) {
        log.Info("home page hit")
        c.JSON(http.StatusOK, gin.H{"status": "ok"})
    })

    r.Run(":8080")
}

Three lines handle all debugger setup:

1. defer dbg.Close() — clean up the IPC bridge on exit
2. log := dbg.Logger() — get a *slog.Logger that writes to both stdout and the debugger store
3. r.Use(dbg.Middleware(8080)) — capture HTTP requests and start the session

What gets captured

The middleware and logger capture three categories of data:

• Gin internal logs — route registration, startup messages, and warnings. Captured via gin.DefaultWriter.
• HTTP requests — method, path, status code, and latency for every request. Captured after c.Next() completes.
• slog calls — any log.Info(), log.Error(), log.Warn(), or log.Debug() call in your handlers. Captured via the logger returned by dbg.Logger().

Verify

Start your server:

go run .

The terminal shows the session ID:

> @ephem-sh/debugger: session d4736a
[GIN-debug] Listening and serving HTTP on :8080

Open another terminal and query:

npx dbg status

pnpm dlx dbg status

bun x dbg status

yarn dlx dbg status

npx dbg server console

pnpm dlx dbg server console

bun x dbg server console

yarn dlx dbg server console

API reference

The gin middleware package exports three functions:

Middleware(port int) gin.HandlerFunc

Returns a Gin middleware that creates the debugger session, starts the IPC bridge, redirects Gin's internal log output, and captures every HTTP request. The port parameter is metadata only — it does not bind to the port.

If the debugger fails to start (for example, the socket is already in use), Middleware prints a warning to stderr and returns a no-op handler. Your application continues to work normally.

Logger() *slog.Logger

Returns a *slog.Logger that writes to both os.Stdout and the debugger store. Safe to call before or after Middleware() — the logger resolves the store lazily on first use.

Use this logger in your route handlers instead of the global slog.Default() to ensure your log output appears in npx dbg server console.

Close()

Stops the IPC bridge and cleans up resources. Call this in a defer at the start of main().

Important: use gin.New()

Use gin.New() instead of gin.Default() when adding the debugger middleware. gin.Default() attaches Gin's built-in Logger middleware which conflicts with the debugger's log capture. Add gin.Recovery() explicitly for panic recovery.

Production safety

The debugger middleware runs unconditionally — there is no automatic dev/production detection in the Go package. We recommend guarding the middleware with an environment variable:

r := gin.New()
r.Use(gin.Recovery())
if os.Getenv("DEBUG") == "1" {
    r.Use(dbg.Middleware(8080))
}

Browser support

If your application serves HTML pages, the debugger can also capture browser-side data (console logs, errors, network requests, cookies, and storage).

1. Register browser routes

After setting up the middleware, register the browser endpoints:

dbg.Routes(r)  // r is your gin.Engine

This registers GET /_/d.js (browser script) and POST /_/d (browser log ingest).

2. Add script tags to your HTML

Include these two script tags before </body> in your HTML templates:

<script>window.__DEBUGGER_INGEST_URL__="/_/d";</script>
<script src="/_/d.js" defer></script>

3. Query browser data

npx dbg browser console

pnpm dlx dbg browser console

bun x dbg browser console

yarn dlx dbg browser console

npx dbg browser errors

pnpm dlx dbg browser errors

bun x dbg browser errors

yarn dlx dbg browser errors

npx dbg browser network

pnpm dlx dbg browser network

bun x dbg browser network

yarn dlx dbg browser network

npx dbg browser cookies

pnpm dlx dbg browser cookies

bun x dbg browser cookies

yarn dlx dbg browser cookies

npx dbg browser storage

pnpm dlx dbg browser storage

bun x dbg browser storage

yarn dlx dbg browser storage

Full example

See the complete working example at examples/go/gin.