aicoded.dev

Telemetry: logs and traces

An app logs with Go's log/slog and records trace spans with telemetry.Start. The framework already records a span for every request, statement, file, mail and call, and ties each log line to its trace. None of it may hold personal data.

Logs

app.Main makes the default slog logger write JSON lines to standard output, with the trace_id and span_id of the context on every line that has one. Log with the context:

slog.InfoContext(ctx, "user added")
slog.InfoContext(ctx, "report sent", "rows", len(rows))

Spans

The framework records these spans:

Span Attributes For
HTTP GET, HTTP POST, … http.path every request the app serves, including its live connection
sql.query, sql.exec, sql.begin db.operation every statement; see the SQL database
filestore.<operation> store every file store operation; see file stores
mailer.send, mailer.list, … every mail call; see mail
rpc.call rpc.app, rpc.method every call to another app; see calls between apps

A call to another app carries the trace, so the called app's spans join the caller's trace.

To time your own work, start a span with the context, and end it:

ctx, span := telemetry.Start(ctx, "users.add")
span.SetAttr("photos", strconv.Itoa(len(photos)))
defer span.End()

addUser in the people example, which Deps.AddUser calls, records the error that ends it:

defer func() {
	if err != nil {
		span.RecordError(err)
	}
	span.End()
}()

aicoded dev keeps each app's last 10000 spans and shows them on the Traces page of the dev UI, as a tree with their timing, attributes and errors, and through the traces and trace tools of aicoded mcp. Exporting the spans to the company's tools comes later, and so do metrics.

On the platform

On the platform, the runner sends each app's output lines and spans to the platform's store, which keeps them 30 days, marked with the app's organisation, name, release and environment, preview or production, whatever the app sets. A line that is JSON keeps its level, trace and span; any other line counts as INFO. You read them with your sign-in, for an app you own:

One read covers at most 7 days and 1000 rows, and the platform writes it to its audit log: who read which app, the range and the filters, never the rows. On the platform, secret values are not hidden from the logs: never log one.

No personal data

Logs and spans reach more tools and more people than the app's data does. Never put personal data in them: no form values, names, logins, email addresses, uploaded file names or message texts, and no secret.

See also

Markdown · Source on GitHub · framework f46741f