Go + Echo

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

Echo 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 Echo middleware package and add it to your router:

package main

import (
    "net/http"

    "github.com/labstack/echo/v4"
    dbg "github.com/ephem-sh/debugger/packages/debugger-go/middleware/echo"
)

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

    e := echo.New()
    e.Use(dbg.Middleware(9877))

    e.GET("/", func(c echo.Context) error {
        log.Info("home page hit")
        return c.JSON(http.StatusOK, map[string]any{"status": "ok"})
    })

    e.Start(":9877")
}

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. e.Use(dbg.Middleware(9877)) — capture HTTP requests and start the session

What gets captured

The middleware and logger capture two categories of data:

• HTTP requests — method, path, status code, and latency for every request. Captured after next(c) returns.
• slog calls — any log.Info(), log.Error(), log.Warn(), or log.Debug() call in your handlers. Captured via the logger returned by dbg.Logger().

Note: Echo's internal logger output is not captured by the debugger middleware. Echo v4 uses its own logger interface that differs from slog. HTTP requests and slog calls in your handlers are captured.

Verify

Start your server:

go run .

The terminal shows the session ID:

> @ephem-sh/debugger: session bbdaa1

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 echo middleware package exports three functions:

Middleware(port int) echo.MiddlewareFunc

Returns an Echo middleware that creates the debugger session, starts the IPC bridge, and captures every HTTP request. The port parameter is metadata only.

If the debugger fails to start, Middleware prints a warning to stderr and returns a no-op handler.

Logger() *slog.Logger

Returns a *slog.Logger that writes to both os.Stdout and the debugger store. Safe to call before or after Middleware().

Close()

Stops the IPC bridge and cleans up resources.

Production safety

The debugger middleware runs unconditionally. Guard it with an environment variable for production:

e := echo.New()
if os.Getenv("DEBUG") == "1" {
    e.Use(dbg.Middleware(9877))
}

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(e)  // e is your echo.Echo

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/echo.