Go SDK for DuckBug errors, logs, and transactions.
This module follows the DuckBug SDK architecture from duckbug-sdk-spec, while using the real ingest contract from duckbug/backend:
POST /ingest/{projectID}:{key}/errorsPOST /ingest/{projectID}:{key}/errors/batchPOST /ingest/{projectID}:{key}/logsPOST /ingest/{projectID}:{key}/logs/batchPOST /ingest/{projectID}:{key}/transactions
- Go
1.26.10+. Thegodirective ingo.modis the source of truth. The HTTP/2 security fixes ingolang.org/x/netrequire Go 1.26; the minimum uses the current patched 1.26 release. Upgrading from SDK 0.4 also requires upgrading consumers still using Go 1.25. - Every change is validated on that minimum and on the current Go release. The exact versions are the matrix in the CI workflow under
.github/workflows/, and are not repeated here. - Releases are expected to be published via git tags in the
v*format.
go get github.com/duckbugio/duckbug-goTo install a tagged release:
go get github.com/duckbugio/duckbug-go@v0.3.1package main
import (
"context"
"log"
"os"
"strings"
duckbug "github.com/duckbugio/duckbug-go"
)
func main() {
dsn := strings.TrimSpace(os.Getenv("DUCKBUG_DSN"))
if dsn == "" {
log.Fatal("DUCKBUG_DSN is required")
}
duck := duckbug.New(
dsn,
duckbug.WithService("checkout"),
duckbug.WithEnvironment("production"),
)
defer duck.Flush(context.Background())
duck.Log("warning", "payment provider timeout", map[string]any{
"provider": "stripe",
})
if err := doWork(); err != nil {
duck.Quack(err)
}
}This is the smallest useful setup: the SDK only needs a DSN. Environment variable naming is up to your application; DUCKBUG_DSN is just the simplest convention for examples.
If you want richer context, you can optionally pass duckbug.WithService(...), duckbug.WithEnvironment(...), duckbug.WithRelease(...), duckbug.WithServerName(...), custom provider options, or a custom pond.Pond.
package main
import (
"context"
"log/slog"
"net/http"
duckbug "github.com/duckbugio/duckbug-go"
duckbughttp "github.com/duckbugio/duckbug-go/integrations/nethttp"
duckbugslog "github.com/duckbugio/duckbug-go/integrations/slog"
)
func main() {
duck := duckbug.New(
"https://duckbug.io/api/ingest/<projectID>:<publicKey>",
duckbug.WithSensitiveFields("password", "token"),
duckbug.WithEnvironment("production"),
duckbug.WithRelease("checkout@1.2.3"),
duckbug.WithService("checkout"),
)
logger := slog.New(duckbugslog.NewHandler(duck, slog.Default().Handler()))
logger.Warn("checkout degraded", "provider", "stripe")
handler := duckbughttp.Middleware(
duck,
duckbughttp.WithProductionDefaults(),
)(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.WriteHeader(http.StatusNoContent)
}))
_ = handler
duck.Flush(context.Background())
}The middleware records the first final HTTP status. Informational responses can
precede it; status 101 is terminal. Writes and supported flush operations establish
an implicit 200. Streaming and string writes follow the same accounting, and the
wrapper preserves the underlying optional writer interfaces. Put this middleware
outside other response-writer middleware, so controller operations from inner
handlers reach its hooks. An outer writer that exposes controller capabilities
only through Unwrap can let http.ResponseController bypass observation; that
ordering is unsupported and can produce an incorrect recorded status. An outer
writer is compatible only when it directly delegates those capabilities. Verify
the writer order when adopting the middleware in an existing server stack.
Handled-failure snippets contain only bytes accepted by the underlying writer.
responseAcceptedBytes counts those bytes; buffering and HEAD responses mean this
does not prove delivery to the client. Use WithHandled5xxMaxBodyBytes(0) to omit
response snippets while retaining failure status and accepted-byte count.
A panic after a committed response retains that status and does not append a
fallback body. With WithRepanic(true), an uncommitted panic is rethrown for outer
recovery; its future HTTP status is unknown, so the transaction omits the status
measurement. A hijacked connection without an observed status has the same
unknown-status boundary. An ordinary empty handler defaults to 200 on return.
Duckis the main runtime facade.New(dsn, ...)is the shortest setup path for the first-party provider.Quack(err)is the branded manual error capture API.pond.Ripple(...)builds the context/sanitization subsystem.Log(...)is the canonical log capture API.StartTransaction(...)andCaptureTransaction(...)provide the performance/trace ingest surface.
- Sensitive nested fields are masked with
***. - Sensitive header names are masked with
***. - Query/body/session/cookies/files/env are attached in the canonical event model and can be disabled in the DuckBug provider privacy options.
envcapture is disabled by default in the first-party provider.net/httpmiddleware does not read request bodies unless you explicitly enableWithReadBody(true).
- The first-party provider uses a background queue by default, so
Log,Quack,CaptureTransactionandslogbridge calls do not block the hot path on network I/O. - The default transport is tuned for application safety: short connection timeout and no retry storm on the request path.
- Delivery is retried on transport errors,
408,429and every5xx, including status codes this SDK has never been taught about - those are what an edge in front of the installation invents, and dropping the event on the first one would lose it silently.501 Not Implementedis the single exception and is final, because it means the capability is not configured in that DuckBug installation and repeating the request cannot change that. Everything else is decided after one attempt.409 Conflictis not a failure: it means the backend already holds thiseventId, so the result is markedDuplicate,TransportResult.IsSuccess()reports true and the transport failure handler is not called. Every other4xxis reported to the transport failure handler after one attempt. - The retry predicate is identical in
duckbug-go,duckbug-jsandduckbug-php. What a duplicate looks like afterwards is not:duckbug-jsalso treats409as success, whileduckbug-phphands it to its failure handler because itsisSuccess()requires2xx. All three agree on not retrying it. - Retries are opt-in here:
WithMaxRetriesdefaults to0, because this transport can run inline in the caller's request path.duckbug-jsandduckbug-phpdefault to2. Flush(...)waits for the provider queue and sends any buffered log/error batches, so it should be called on graceful shutdown.
logger := slog.New(duckbugslog.NewHandler(duck, slog.Default().Handler()))
logger.Info("checkout started", "requestId", "req-123")By default the SDK captures WARN+ from slog. To lower the threshold:
logger := slog.New(
duckbugslog.NewHandler(
duck,
slog.Default().Handler(),
duckbugslog.WithMinLevel(slog.LevelInfo),
),
)import (
"os"
duckbugzap "github.com/duckbugio/duckbug-go/integrations/zap"
"go.uber.org/zap"
"go.uber.org/zap/zapcore"
)
observerCore := zapcore.NewCore(
zapcore.NewJSONEncoder(zap.NewProductionEncoderConfig()),
zapcore.AddSync(os.Stdout),
zapcore.InfoLevel,
)
logger := zap.New(duckbugzap.NewCore(duck, observerCore)).With(zap.String("service", "api"))
logger.Warn("checkout degraded", zap.String("provider", "stripe"))import (
"os"
duckbugzerolog "github.com/duckbugio/duckbug-go/integrations/zerolog"
"github.com/rs/zerolog"
)
logger := zerolog.New(duckbugzerolog.NewWriter(duck, os.Stdout)).
With().
Timestamp().
Str("service", "api").
Logger()
logger.Warn().Str("provider", "stripe").Msg("checkout degraded")handler := duckbughttp.Middleware(
duck,
duckbughttp.WithCaptureTransactions(true),
duckbughttp.WithTransactionSampleRate(0.10),
)(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
duck.LogContext(r.Context(), "info", "request received", map[string]any{
"path": r.URL.Path,
})
w.WriteHeader(http.StatusNoContent)
}))The first-party DuckBug provider supports:
- async non-blocking enqueue with bounded in-memory queue
- batching with explicit
Flush(...)and periodic background flush - single-shot
transactionsingest - safe-by-default transport timeouts and configurable retry/backoff
beforeSendmutation/drop hook- transport failure hook
- privacy controls for request sections and
env
Transactions mirror the current DuckBug backend and PHP SDK shape:
- required payload fields:
traceId,spanId,transaction,op,startTime,endTime,duration - optional fields:
eventId,parentSpanId,status,context,measurements,spans,release,environment,dist,platform,serverName,service,requestId,user,sdk,runtime,extra - duplicate transaction ingest is treated as idempotent success by the backend
Example:
tx := duck.StartTransaction("GET /checkout", "http.server")
span := tx.StartChild("db.query", "select order")
span.SetData(map[string]any{
"sql": "select * from orders where id = ?",
})
span.Finish("ok")
tx.AddMeasurement("db.rows", 1, "")
tx.Finish("ok")
duck.CaptureTransaction(tx)Implemented in this iteration:
- core runtime for
errors,logs, andtransactions - branded
Duck/Quack/pond.Ripple - first-party DuckBug provider
slog,zap, andzerologbridgesnet/httpmiddleware compatible withchi- schema copies and tests against the current payload contract for
errorsandlogs - transaction payload tests aligned with
duckbug/backendandduckbug-php
- Push a semver-style tag like
v0.2.0. - The release workflow re-runs module checks and creates a GitHub Release.
- Consumers install the module through the standard Go module mechanism via
go get.