IPC Endpoints

v0.5.8 Litestream exposes IPC (Inter-Process Communication) endpoints via a Unix domain socket. These endpoints allow local tools and scripts to query database status and collect profiling data without exposing an HTTP port.

Socket Path#

The IPC socket is created at:

/var/run/litestream.sock

The socket is automatically created when Litestream starts replication and removed on shutdown.

Endpoints#

GET /txid#

Returns the current transaction ID for a database.

Query parameters:

Example:

$ curl --unix-socket /var/run/litestream.sock \
    "http://localhost/txid?path=/path/to/my.db"
{"txid":42}

/debug/pprof/*#

Standard Go pprof endpoints for runtime profiling. These allow you to collect CPU profiles, heap snapshots, and goroutine dumps without running a separate HTTP server.

CPU profile:

$ curl --unix-socket /var/run/litestream.sock \
    http://localhost/debug/pprof/profile > cpu.pprof

Heap profile:

$ curl --unix-socket /var/run/litestream.sock \
    http://localhost/debug/pprof/heap > heap.pprof

Goroutine dump:

$ curl --unix-socket /var/run/litestream.sock \
    "http://localhost/debug/pprof/goroutine?debug=2"

Available pprof paths:

Use go tool pprof to analyze collected profiles:

go tool pprof cpu.pprof
go tool pprof heap.pprof

See Also#

• Configuration Reference - Complete configuration options
• Metrics - Prometheus metrics reference