# Go

> Structured logs from your Go services, with a log/slog handler. Standard library only.

Source: https://docs.lyrelog.com/sdks/go

<SdkHeader name="Go" />

The module is `go.lyrelog.com/lyrelog`. It needs Go 1.24 or later and
has no dependencies.

<Callout type="info">
Internal preview: this package isn't published yet. Until it is, `go get go.lyrelog.com/lyrelog`
fails: the repository is private and has no release yet.
</Callout>

## Install [#install]

```bash
go get go.lyrelog.com/lyrelog
```

## Start [#start]

```go
import "go.lyrelog.com/lyrelog"

client, err := lyrelog.New(lyrelog.Config{
	APIKey:   "lyr_srv_...", // a server key, or read it from your own config
	Platform: "api",
})
if err != nil {
	log.Fatal(err) // only for a bad config: logging itself never fails
}
defer client.Close() // sends what is left (waits at most 5 s)
```

Use a server key, `lyr_srv_...`, from the project's **API keys** page (**Send events from a
server**). It is a secret: keep it in your server's environment, never in an app or a web page.
Its events are [verified](/concepts/verification), and one address has no daily share of
the month. An ingest key, `lyr_ing_...`, works too, but its events aren't verified.

Only `APIKey` is required: without it `New` returns an error and a `nil` client. A `nil`
`*Client` does nothing, so code can log before (or without) one. `Endpoint` defaults to
`https://ingest.lyrelog.com`; it is the base URL, and a pasted `/v1/events:batch` path is
removed.

`log.Fatal` and `os.Exit` skip deferred calls, so `defer client.Close()` never runs after them.
In `main`, return an exit code from a function that does the work:

```go
func main() { os.Exit(run()) }

func run() int {
	client, err := lyrelog.New(lyrelog.Config{APIKey: os.Getenv("LYRELOG_KEY")})
	if err != nil {
		fmt.Fprintln(os.Stderr, err) // client is nil and does nothing: carry on without it
	}
	defer client.Close() // runs before os.Exit
	// ...
	return 0
}
```

In a serverless function (AWS Lambda), call `client.Flush(ctx)` before the handler returns: the
runtime may freeze the process before the next send.

## Log events [#log-events]

One method per level: `Trace`, `Debug`, `Info`, `Notice`, `Warning`, `Error`, `Critical`, or
`Log(level, message, ...)`. Details are options: `lyrelog.Category`, `lyrelog.Attrs`,
`lyrelog.Payload` and `lyrelog.User`.

```go
client.Info("checkout_done", lyrelog.Attrs{"plan": "pro", "latency_ms": 412})
client.Error("payment_failed",
	lyrelog.Category("billing"),
	lyrelog.Attrs{"code": "card_declined"},
	lyrelog.Payload(map[string]any{"response": body}),
)
```

Attributes can be strings, numbers, booleans, `nil`, string slices and nested maps (4 levels).
Names with dots are rewritten with `_`. Several `Attrs` options merge, a later key wins.
A `Payload` is encoded with `encoding/json`: pass `json.RawMessage` for bytes that already are
JSON (a plain `[]byte` arrives as a base64 string).

## Loggers for each area [#loggers-for-each-area]

```go
billing := client.Logger("billing")
billing.Warning("invoice_retry", lyrelog.Attrs{"attempt": 2})
```

## Users [#users]

```go
client.SetUser("u_123") // attached to every following event
client.SetUser("")      // clear it
```

A server handles many people at once: set the user on each event with
`lyrelog.User(id)`, which replaces the one from `SetUser` for that event.

## The slog handler [#the-slog-handler]

Send `log/slog` records to Lyrelog:

```go
logger := slog.New(lyrelog.NewSlogHandler(client, &lyrelog.SlogOptions{Category: "app"}))
logger.Info("order_shipped", "order_id", id, "category", "fulfillment")
```

- The record's message is the event's message, its time the event's time; attributes and groups
  become nested attributes.
- A top-level `category` string attribute sets the area (and isn't sent as an attribute);
  without one the handler's `Category` is used.
- Levels: `Debug-4` and below is `trace`, `Debug` is `debug`, `Info` is `info`, between `Info` and
  `Warn` is `notice`, `Warn` is `warning`, `Error` is `error`, `Error+4` and above is `critical`.
- `SlogOptions.Level` adds a minimum on top of the client's; `AddSource` adds a `source`
  attribute with the caller's function, file and line. Build with `go build -trimpath` so the
  file holds module paths rather than your build machine's directories.

To keep printing to the terminal as well, send each record to both handlers. On Go 1.26 or later,
`slog.NewMultiHandler` does it:

```go
logger := slog.New(slog.NewMultiHandler(
	slog.NewTextHandler(os.Stderr, nil),
	lyrelog.NewSlogHandler(client, &lyrelog.SlogOptions{Category: "app"}),
))
slog.SetDefault(logger)
```

## A net/http middleware [#a-nethttp-middleware]

There is no built-in middleware. This one records every request as `http_request_served` in the
`http` area, at info, warning for a 4xx and error for a 5xx, with the route pattern rather than
the path, so ids don't explode the cardinality:

```go
func logRequests(client *lyrelog.Client, next http.Handler) http.Handler {
	httpLog := client.Logger("http")
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		start := time.Now()
		recorder := &statusRecorder{ResponseWriter: w, status: http.StatusOK}
		next.ServeHTTP(recorder, r)
		level := lyrelog.LevelInfo
		switch {
		case recorder.status >= 500:
			level = lyrelog.LevelError
		case recorder.status >= 400:
			level = lyrelog.LevelWarning
		}
		httpLog.Log(level, "http_request_served", lyrelog.Attrs{
			"method":      r.Method,
			"route":       r.Pattern, // set by http.ServeMux (Go 1.23+), e.g. "GET /users/{id}"
			"status":      recorder.status,
			"duration_ms": time.Since(start).Milliseconds(),
		})
	})
}

type statusRecorder struct {
	http.ResponseWriter
	status int
}

func (s *statusRecorder) WriteHeader(code int) {
	s.status = code
	s.ResponseWriter.WriteHeader(code)
}

// Unwrap lets http.ResponseController reach the original writer (Flush, deadlines).
func (s *statusRecorder) Unwrap() http.ResponseWriter { return s.ResponseWriter }

// http.ListenAndServe(":8080", logRequests(client, mux))
```

`r.Pattern` is empty for a request no route matched.

## Errors [#errors]

```go
if err := charge(ctx, order); err != nil {
	client.CaptureError(err, lyrelog.Category("billing"), lyrelog.Attrs{"order_id": order.ID})
}
```

The event is `exception`, level `error`, with `error_type` and `error_message` in the
attributes and, in the payload, the error's chain (each wrapped error) and the stack. A
`nil` error logs nothing. `Logger.CaptureError` does the same with the logger's category. The
level is always `error`: for another one, log the error yourself with `Log`.

## Panics [#panics]

The SDK doesn't recover panics. `net/http` recovers a handler's panic and only prints it, so
record it in a middleware, outside the one above:

```go
func recoverPanics(client *lyrelog.Client, next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		defer func() {
			v := recover()
			if v == nil {
				return
			}
			if v == http.ErrAbortHandler {
				panic(v)
			}
			err, ok := v.(error)
			if !ok {
				err = fmt.Errorf("panic: %v", v)
			}
			client.CaptureError(err, lyrelog.Category("http"),
				lyrelog.Attrs{"handled": false, "mechanism": "panic", "route": r.Pattern})
			http.Error(w, http.StatusText(http.StatusInternalServerError), http.StatusInternalServerError)
		}()
		next.ServeHTTP(w, r)
	})
}

// http.ListenAndServe(":8080", recoverPanics(client, logRequests(client, mux)))
```

The stack in the payload is taken where the panic was recovered, so it still shows the frames
that panicked. A panic in a goroutine of your own crashes the program before anything is sent:
recover it in that goroutine the same way.

## Environments and platform [#environments-and-platform]

`Environment` defaults to the `LYRELOG_ENVIRONMENT` environment variable (lowercased), else
`production`. `Platform` defaults to `go`. Set either in the config:

```go
client, err := lyrelog.New(lyrelog.Config{
	APIKey:      "lyr_srv_...",
	Environment: "staging",
	Platform:    "worker",
})
```

Both must be lowercase letters, digits, `-` and `_`, up to 32, starting with a letter or digit.
An invalid `Config.Environment` or `Config.Platform` makes `New` return an error; an invalid
`$LYRELOG_ENVIRONMENT` is reported to `ErrorLog` and replaced by `production`, so a typo in a
deploy never stops a service.
`Release` defaults to the main module's version from the build info, and `AppID` to the main
module's path.

## Consent [#consent]

Consent is for apps that run on someone's device. A server SDK sends what it is given.

## Flush and stop [#flush-and-stop]

```go
err := client.Flush(ctx) // send what's queued now
client.Close()           // flush (up to CloseTimeout) and stop
```

`Flush` sends everything queued before the call and waits for it or for `ctx`. It returns:

- `nil` when everything reached the server;
- `ctx.Err()` if the context ended first;
- `ErrUnauthorized` after a `401` or `403` (the client stops sending until the process restarts
  and keeps its queue);
- an error saying a batch was refused and dropped (the rest was still sent);
- an error saying delivery failed and will be retried, with the events kept. Inside a
  `Retry-After` the server asked for, `Flush` returns this at once and sends nothing;
- `ErrClosed` after `Close`.

`Close` waits at most `CloseTimeout` for the last flush and returns the same values; events still
unsent then are dropped and counted in `Stats().Dropped`. After `Close`, log calls do nothing.

`client.Stats()` returns `Queued` (waiting, including a batch being retried), `Sent` (accepted by
the server), `Rejected` (lines the server refused, never resent) and `Dropped` (by the client:
queue overflow, a refused batch, or left at `Close`).

## In development and tests [#in-development-and-tests]

Without an `APIKey`, `New` returns an error and a `nil` client, and a `nil` client does nothing:
the same code runs in tests and on a laptop without a key, as in the `run` example above. The
slog handler over a `nil` client drops every record.

To see what a test logs, pass an `HTTPClient` whose `Transport` records the requests, or point
`Endpoint` at an `httptest.Server` (plain `http://` is allowed for loopback addresses).

## Verified events [#verified-events]

A verified event is one that can't have been sent by someone who copied the public ingest key
out of an app or a web page. What that proves, and what it doesn't, is on
[Verified events](/concepts/verification).

Send with a server key, `lyr_srv_...`. Every event it sends is verified (`verified_by` is
`server`) and doesn't count toward the
[daily share of one address](/concepts/verification#the-daily-share-of-one-address). An owner
makes it on the project's **API keys** page, **Send events from a server**, after a recent sign-in
(within 10 minutes), and it is shown once. It is a secret: keep it out of the repository and read
it from the server's environment or secret store.

```go
client, err := lyrelog.New(lyrelog.Config{
	APIKey: os.Getenv("LYRELOG_KEY"), // lyr_srv_..., set in the server's environment
})
```

To check, open the [explorer](/dashboard/explorer): in **Filter**, pick **Verified by** and
**Server key** (the other values are **App Attest** and **Not verified**). An opened event says it under
**Context**, in its **Sender** line: **Verified, server key**, or **Not verified, public key**.

Events sent with an ingest key, `lyr_ing_...`, or a full-access key, `lyr_adm_...`, arrive
unverified: anyone holding a public key could have sent the same, and they count toward the daily
share. A verified event proves who sent it, not that what it says is true.

See [Verified events](/concepts/verification) for who verifies what and the daily share.

## Configuration [#configuration]

| Field | Default | Meaning |
|---|---|---|
| `Endpoint` | `https://ingest.lyrelog.com` | The base URL; a pasted `/v1/...` path is removed. Plain `http://` only for localhost |
| `APIKey` | required | The project's server key (`lyr_srv_...`), or an ingest key |
| `Environment` | `$LYRELOG_ENVIRONMENT`, else `production` | Any valid name |
| `Platform` | `go` | `api`, `worker`... |
| `Release` | the module version | Sent as `resource.app_version` |
| `AppID` | the module path | Sent as `resource.app_id` |
| `MinimumLevel` | `LevelDebug` | Events below it are dropped before queueing |
| `FlushInterval` | 5 s | How often the background goroutine sends |
| `MaxQueue` | 10,000 | Oldest dropped beyond it, counted in `Stats().Dropped` |
| `MaxQueueBytes` | 16 MiB | The same cap, in bytes |
| `CloseTimeout` | 5 s | How long `Close` waits for the last flush |
| `HTTPClient` | 30 s timeout | The client that sends batches. Redirects are never followed, even with your own client |
| `ErrorLog` | stderr, once | Receives the SDK's own diagnostics, each starting with `lyrelog: `. Without it, only the first refused key or dropped batch (once) and the quota warning are printed to stderr. Don't point it at a logger that feeds this client |

## Delivery and limits [#delivery-and-limits]

- One background goroutine batches up to 500 events or 512 KiB, gzipped; a full batch is sent
  right away. Safe for concurrent use.
- Retries with full jitter (1 s doubling to 5 min), honoring `Retry-After` (seconds or a date),
  resending the same bytes. Any other 4xx drops the batch; a 3xx drops it and logs a warning.
- Values under keys whose name is or ends with `authorization`, `cookie`, `password`, `token`,
  `secret`, `apikey` and the rest of the [shared list](/sdks#what-every-sdk-does-for-you)
  become `"[redacted]"` before queueing: in attributes and the payload, at any depth (maps,
  structs by their JSON names, slices, `http.Header`), before anything is cut. `Config.RedactKeys`
  replaces the list and an empty, non-nil slice turns it off; to add to it,
  `RedactKeys: append(lyrelog.DefaultRedactKeys(), "pin")`.
- When a Free organization has used its month's events, the server answers `429`. The events
  stay in memory and go out once the server takes them again, up to `MaxQueue`. The client
  logs one warning to `ErrorLog` (or stderr) and says nothing more until a batch is accepted.
- Context: `os_name` is `runtime.GOOS`, `app_build` the VCS revision when the binary has one, and
  the install and session ids are per process.
- Limits are applied before queueing: past 200 leaves attributes are dropped and counted in
  `lyrelog_dropped_attrs`, dots in names become `_` (`http.status` is `http_status`), errors,
  times, durations and `Stringer`s become strings, structs their JSON form, NaN `null`. A payload
  over 64 KiB becomes `{"lyrelog_truncated": true, "bytes": N, "preview": "..."}` with its first
  KiB. One event's attributes are capped at 256 KiB encoded, and an event that can't fit in a
  512 KiB batch is dropped and counted.
- Printing a `Config` or a `*Client` with `fmt` hides the API key.