Go
zharp-go-lib sends your slog records, panics and errors, and traces every request your Go service handles.
This SDK is new, and its API may still change before 1.0. Requires Go 1.26 or later.
It is a thin layer over the official OpenTelemetry Go SDK: zharp.Init sets up the exporters, resource, W3C trace context and baggage propagation and a log/slog bridge, and registers the global providers — so any OpenTelemetry instrumentation in your app is sent too.
Install
go get github.com/zharp-io/zharp-go-lib
Initialize
In main:
import (
"context"
zharp "github.com/zharp-io/zharp-go-lib"
)
func main() {
shutdown := zharp.Init(zharp.Config{
Key: "zpk_…",
Service: "checkout-api",
Environment: "production",
})
defer shutdown(context.Background())
// … your server
}Leave fields empty to read them from the environment. Init never panics: without a key it prints one line and sends nothing, and the returned shutdown does nothing. Call shutdown before the program exits; it sends what is left.
Then wrap your router — one line, and Go has no automatic instrumentation, so it is how requests get their user, session and trace (and, unless tracing is off, a span):
net/http
http.ListenAndServe(":8080", zharp.Handler(mux))Gin
go get github.com/zharp-io/zharp-go-lib/zharpgin router := gin.Default() router.Use(zharpgin.Middleware())
Echo
go get github.com/zharp-io/zharp-go-lib/zharpecho e := echo.New() e.Use(zharpecho.Middleware())
Gin and Echo (v4) are separate modules, so the core module doesn't pull them in.
Logs
After Init, every slog line written during a request ends with the request's ids: trace_id=… span_id=… (two fields with a JSON handler). Use the …Context variants so the line knows its request. Where the Zharp agent reads your app's output, it brings those lines in and Zharp links each one to its request — one copy, nothing sent twice. The zap, logrus and zerolog modules stamp their lines the same way; plain fmt.Println and the log package can't be stamped. LogCorrelation: zharp.Bool(false) turns the stamp off.
Where nothing reads the output — serverless, a host without the agent — set Logs: zharp.Bool(true) (or ZHARP_LOGS=true) and the SDK sends the lines itself. Errors and zharp.Log are always sent.
slog.InfoContext(ctx, "Order placed", "order_id", 42) // printed as before, and sent with the request's trace zharp.Log.Info(ctx, "Order placed", "order_id", 42) // to Zharp only: Debug, Info, Warn, Error, Fatal
KeepSlogDefault: true leaves slog.Default alone; zharp.SlogHandler() gives you the handler to use yourself.
Logs only
If you only want logs, turn tracing off. Logs, errors, and the user and session they belong to are still sent; no spans are recorded and no trace headers are added to outgoing requests. A request from a Zharp front end is still read, so its logs keep the caller's user, session and trace ID.
shutdown := zharp.Init(zharp.Config{
Key: "zpk_…",
Service: "checkout-api",
DisableTracing: true,
})
defer shutdown(context.Background())Or leave the code as it is and set ZHARP_TRACING=false in the environment.
The logs show on the Logs page under the service name, and on the app's Logs tab with the user and session of each line. The key comes from an app — see Get a key. To add tracing later, remove the option; nothing else changes.
Errors
A panic in a request is reported as an unhandled error — zharp.Handler answers it with a 500, and Gin and Echo keep their own recovery — and so is an error a Gin or Echo handler returns that ends in a 5xx. Report one yourself with CaptureError:
if err := charge(ctx, order); err != nil {
zharp.CaptureError(ctx, err, "order_id", order.ID) // reported as handled
}Go has no global panic hook. Defer zharp.Recover() at the top of main and of each goroutine:
func main() {
shutdown := zharp.Init(zharp.Config{ /* … */ })
defer shutdown(context.Background())
defer zharp.Recover() // reports a panic, sends it, and panics again
go func() {
defer zharp.Recover()
work()
}()
}Readable stack traces
Nothing to upload: the stacks this SDK sends already name your functions, files and lines, and issues are grouped by them.
Tracing
Each request through the wrapped router becomes a span named by its route — GET /orders/{id} — continuing the caller's trace. Outgoing requests get a span and pass the trace on through Zharp's transport:
client := &http.Client{Transport: zharp.Transport(nil)}
req, _ := http.NewRequestWithContext(ctx, "GET", "https://payments.example.com/charge", nil)
resp, err := client.Do(req) // a span in the request's trace, with traceparent sent onDatabase calls aren't traced by the SDK; add an OpenTelemetry instrumentation for your driver and its spans join the trace.
ctx, span := zharp.Tracer().Start(ctx, "render invoice")
defer span.End()
zharp.SetTag("region", "eu-west") // on every span and log afterRequest and response bodies
Off by default. Turn it on to see what a request sent and what came back, shown under the request in the trace: incoming requests through zharp.Handler, zharpgin and zharpecho, and outgoing calls through zharp.Transport.
zharp.Init(zharp.Config{
Key: "zpk_…",
Service: "checkout-api",
// failed requests only; Mode: zharp.BodiesAll for every one
CaptureBodies: &zharp.CaptureBodies{},
})
// or ZHARP_CAPTURE_BODIES=errors in the environment, or, with more control:
CaptureBodies: &zharp.CaptureBodies{
Mode: zharp.BodiesAll,
MaxSize: 64 << 10,
RedactKeys: []string{"dateOfBirth"},
URLs: []string{"api.example.com"},
},- Failed requests only (status 400 and above, or no response) by default; every request with the "all" mode.
- Text (JSON, forms, XML, plain text) is kept up to 32 KB, up to 128 KB with the size option.
- Every field name is kept. A file in an upload shows as
[file photo.png · image/png · 240 KB], an inline image as[image/png · 24 KB], a body that isn't text as[binary · application/pdf · 1.2 MB]or[event stream]. File contents are never sent. - Your app reads and sends exactly what it did before.
- Gzip and deflate bodies are inflated first.
- Echo: an error your handler returns is written after the span ends, so that request's body is captured but not its error response — unless echo-otel's
OnNextErrorwrites it inside the span.
Values under keys that look secret — password, token, secret, apiKey, authorization, cookie, card, cvv, ssn and similar — are replaced with [Filtered] in your process, before anything is sent. The field stays; only its value is hidden, and under a secret object such as card each value inside is hidden and its keys kept. Anything else, such as names and email addresses, is sent as it is: add those keys to RedactKeys.
Whether or not bodies are on, secret-looking values in URL query strings (?token=, key, sig, password …) are recorded as [Filtered].
User context
Requests from the Zharp browser and mobile SDKs carry the user and session in baggage; the wrapped router puts them on every span and log of the request. When the server knows better:
ctx = zharp.SetUser(ctx, zharp.User{ID: account.ID}) // this request's user, when the server knows betterOptions
| Config field | Environment | Default |
|---|---|---|
CaptureBodies | ZHARP_CAPTURE_BODIES | off; errors or all. See Request and response bodies. |
Key | ZHARP_KEY | — (nothing is sent without one) |
Service | ZHARP_SERVICE, OTEL_SERVICE_NAME | The last part of the main module's path |
Environment | ZHARP_ENVIRONMENT | none |
Release | ZHARP_RELEASE | none |
Logs | ZHARP_LOGS | false; zharp.Bool(true) sends what the app logs. See Logs. |
LogCorrelation | ZHARP_LOG_CORRELATION | true: lines logged in a request end with trace_id=… span_id=… |
DisableTracing | ZHARP_TRACING=false | false; true is logs only |
SampleRate | ZHARP_SAMPLE_RATE | 1 — share of traces kept; logs and errors are always sent |
KeepSlogDefault | — | false: slog.Default also sends to Zharp |
| — | ZHARP_DISABLED | true starts nothing |
- Telemetry is batched every 5 seconds, gzip-compressed and retried by the OpenTelemetry exporters.
zharp.Flush(ctx)sends now — at the end of a job or a serverless call.
Troubleshooting
Nothing arrives
On the app's setup page (Applications → the app → settings → Setup instructions), the verify step shows the first event as soon as it lands, and Send a test event checks the key on its own. If the test event arrives but your app's don't, the SDK isn't starting or isn't reaching Zharp:
- Is
initcalled, and before the code you expect to see? Without a key, the SDK starts nothing and says so once. - Does the service name match? With an app key everything goes to that app whatever it says; with a workspace key,
servicedecides the app — see Keys. - Data is sent in batches every few seconds. A process that exits straight away should call
flushfirst. - Logs and errors arrive but no traces? Check that tracing isn't turned off — see Logs only.
- Is the router wrapped? Without
zharp.Handleror the middleware, there are logs and errors but no requests. - Do your logs use the
…Contextvariants? Without the context, a log has no trace or user.
401 or 403
Ingest answers 401 when the key is missing, mistyped, revoked or rolled, and 403 when the request comes from an origin or IP address the key doesn't allow. Neither is retried: the SDK warns once and drops what was refused, and it never throws into your code. Copy the key again from the app's settings.