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))
- The framework logs what goes wrong on its side: an error a hook returned that answers 500, a
refused form token, a page call that failed or a panic. Outside
aicoded devit logs only the error's kinds and codes, never its text; see "No personal data" below. So return an error instead of logging it. aicoded devkeeps each app's last 5000 log lines and shows them on the Logs page of the dev UI and through thelogstool ofaicoded mcp. A line that is not JSON counts asINFO.
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()
telemetry.Startbegins a child of the context's current span, or a new trace, and returns the context that carries the new span: pass it on, so the work inside becomes children of it.SetAttr(key, value)records a string attribute, andRecordError(err)marks the span as failed: with the error's text underaicoded devin environmentdev, and with its kinds and codes anywhere else.Endhands the span to the runner. Calls afterEnddo nothing.
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:
aicoded logs --env productionprints the newest log lines, andaicoded traces --env productionthe newest spans, or with--trace <id>those of one trace; see the tools;- the
logs,tracesandtracetools ofaicoded mcpread the same withenvset toprevieworproduction; see MCP.
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.
- Log that something happened and its outcome, never what a viewer wrote. Count instead of listing: the people example's span holds the number of photos, not their names.
- An error's text can quote a value, such as the duplicate entry a UNIQUE index refuses or the
name of a stored file. So wherever the framework records an error, in its log lines and in
RecordError, it keeps only the error's kinds and codes outsideaicoded dev: E-codes, MySQL error numbers, status codes, the sentinels ofio/fs,database/sqlandcontext, the operation of a file error, and the Go type of any other error. An error of a file store reads likefs.PathError write: fs.ErrNotExist, a duplicate entryMySQL error 1062 (23000), and an error fromerrors.New*errors.errorString. A panic's value is recorded by its Go type. - Under
aicoded devin environmentdev, whose data is made up, the framework records the whole text and the panic's value, so that you and your AI assistant see what went wrong. - The error the app gets back still holds the text. Return it from the hook, page call or
function, or pass it to
RecordError, and the framework records it as above; never log it or put it in a span attribute. aicoded checkrefuses a log line, a print or a span that records a value from outside the app (E-LINT-008): a form value, a URL parameter, the request, the viewer's identity, a value from the database, a mail from the inbox, a stored file, a secret, the input of a page call, of aValidatehook or of a function the app serves to other apps, or another app's answer, and any text, error or struct made from one, a hash included. The code of a template's expressions is checked too. Numbers and booleans carry nothing, so ids, counts, lengths and flags may be logged.- A request span records the path, so a value in a URL, such as a login in
/users/alice, is in the span. Keep data that must not be traced out of URLs.
See also
- aicoded dev: the Logs and Traces pages.
- MCP: the
logs,tracesandtracetools. - people/deps/users.go: a span of its own, with no personal data.