Activity log and program log
This page explains the two logs of email-mcp, who reads each one, and the rules for writing to them. Read it before you add an audit entry or a log line. The user view of the first log is in Activity and undo.
email-mcp has two logs that follow different rules. The activity log is a table in the database. The person reads it on the Activity page of the web portal (the local web site of the person). The program log is text on standard error (the stream where a program writes messages about itself). The person who runs the program reads it.
The activity log
The package audit in internal/audit/audit.go keeps the activity
log. Each row is an entry of one of two kinds:
- A call entry is one
tools/callrequest of the agent. The agent is the AI (artificial intelligence) program that calls the tools of email-mcp, and a tool is one action that it can call. Every tool and every outcome has a call entry: a read, a refusal, a call with wrong arguments, and a call of a tool that does not exist. - An action entry is what a use case of
servicedid, or what the person did on a page. A use case is one job of the program for a caller, such as “send this mail”.
One send makes one call entry and one or more action entries: the question, and later the result.
Where the entries come from:
captureininternal/mcpserver/capture.gois a middleware (a function that wraps the handling of every request) of the SDK (software development kit: the official Go library for MCP, the Model Context Protocol). It writes the call entry when a call ends, throughService.RecordToolCallininternal/service/calls.go. It sits outside the tool handler, because the SDK checks the tool name and the arguments before it runs a handler, and only a middleware sees those calls. A call that the program refuses while it stops never reachescapture, so it has no entry.- The use cases write the action entries with
record,finishandrecordOutcomeininternal/service/write.go. The web pages go through the same use cases.
Both end in audit.Log.Record.
The fields of an entry
A tenant is the owner of a set of accounts. To seal a value is to encrypt it with the key of the tenant. Storage and secrets explains how.
| Field | What it holds | How it is stored |
|---|---|---|
Time |
The time from the clock of the log, in whole milliseconds | Plain |
Kind |
call or action |
Plain |
Tenant, Account, Area |
The ids. The account is empty for an entry of the tenant. | Plain |
Client |
The name that the MCP client (the AI app) gave for itself | Plain, cleaned, at most 128 bytes |
TokenID |
The id of the access token of the call, never the token | Plain |
Tool |
The name of the tool, or unknown_tool |
Plain |
Count |
The number of items the call affected | Plain |
Recipients |
The recipients of the envelope, at most 200 | Sealed |
Outcome |
ok, refused, declined, pending_approval or error |
Plain |
Detail |
A short code such as level_too_low |
Plain |
Arguments |
The JSON (JavaScript Object Notation) of the arguments of a call | Sealed |
The table repeats the rules of Detail and the others with CHECK conditions
(rules that the database enforces on each row).
What is kept and what is dropped
- No message content.
omittedArgumentsincapture.golists the arguments that are never kept:body,html_bodyanddata_base64. The entry keeps their size instead. A test makes sure that every argument of every tool is either in the list or not there on purpose. - A call that passed the schema (the description of the arguments that the
tool accepts) keeps its argument values. A long text is cut, with a mark that
says how long it was (
maxArgumentText). Arguments that are very large become a mark with their size (audit.MaxArgumentBytes). - A call that failed the schema keeps only the names and the sizes of its
arguments, up to a small size (
maxRejectedArgumentBytes). The text of a message could be under any name, so the log keeps no value. The name of an unknown tool is text from the agent. It goes in the sealed arguments, and the column holdsunknown_tool. Clientis not trusted. The client chooses its name, and the log watches the client. SoRecordcleans the name: invalid UTF-8 (Unicode Transformation Format, 8 bits) and control, format, line and paragraph separator characters become U+FFFD, and the name is cut to 128 bytes.Recordnever refuses an entry because of the name, because a bad name must never hide an action.Detailis a code, never free text. It has 0 to 64 characters froma-z,0-9and_.Toolis not empty, and it is at most 128 bytes (maxText) of valid UTF-8 with no control, format, line or paragraph separator character.TokenIDhas 0 to 64 characters froma-zand0-9. All three come from the server.Recordrefuses an entry with a bad one (ErrInvalidEntry), and its error never shows a value.
Rules for writers
- A failure to write an entry does not change the answer of the call. The action has happened or was refused, and the agent must learn that. The program log gets a fixed code, the tool and the outcome.
- The write does not stop when the caller leaves, because the action has
happened. It has a time limit of 30 seconds (
storeTimeout), and 5 seconds (callStoreTimeout) for a call entry, which the agent waits for. - A call without a caller has no entry, because a row needs a tenant. The program log gets a fixed code instead.
How long entries stay, and who reads them
App.dailyJobs deletes the entries that are older than 90 days
(auditRetention). The entries of an account go with the account
(ON DELETE CASCADE is a rule that deletes the rows that belong to a deleted
row). The Activity page in internal/web/activity.go calls
audit.Log.List, newest first. It shows 50 entries by default and at most 200,
and at most 4 KiB of the arguments of an entry (maxArgumentsShown; a KiB,
kibibyte, is 1,024 bytes). List
fails if it cannot open the recipients of an entry. It never leaves them out
without a sign. Arguments that it cannot open do not stop the list: List sets
ArgumentsUnreadable on the entry, so one bad row does not hide what the agent
did.
The program log
The program log is slog (the log package of the Go standard library) in text
form, on standard error. app.Open sets it as the default logger, and
Config.LogOutput can change the writer. The writer must never be standard
output. On stdio (standard input and output: the client starts the server and
talks to it through two pipes), standard output carries the MCP protocol, and
any other byte there breaks it.
The log holds ids, counts and fixed codes only. It never holds a secret, a link with a token, an address, a subject, a body, or the text of an error, because that text can hold text from a mail server. Five parts keep this true:
- Fixed codes. A line has a fixed message and a
code, such asaudit_write_failed,pending_end_failedorhttp_server_error. errtype.Chainininternal/errtype/errtype.goreturns the Go type names of an error and of the errors it wraps, at most six. A type name holds no text from the error. The log gets this, never the error.secrets.Secretprints[redacted]. It hides a value in the normal cases only, so keep a secret out of a log line on purpose.- The logger of the SDK is not set. The SDK writes error texts to it.
mcpserver.Newgives it no logger, andOptions.Loggeris a different logger that only gets fixed codes. httpserve.ErrorLogininternal/httpserve/httpserve.gomakes the logger thatnet/httpwrites its own errors to. Such a text can hold a part of a request, so each line becomes one line with the fixed codehttp_server_error.
safe in internal/mcpserver/server.go logs the name of the tool
and a fixed code for a refused caller, a panic, an error with no known text, a
timeout, a failed connection to the mail server and a cancel. It logs a known
refusal nowhere, because the agent gets its text and the activity log has the
entry.
Add a log line
- Use a fixed message and add a fixed
code. - Add only ids, counts, fixed codes and the name of a tool. Never add a secret, an address, a subject, a body, a token or the text of an error.
- For an error, add
errtype.Chain(err). - Keep a secret value in the type
secrets.Secret, and still keep it out of the log line. - Write nothing to standard output.
- If the person should see what happened, add an audit entry too, with a
detailcode.
Related pages
- The send flow
- Storage and secrets
- One tool call, step by step
- Activity and undo in the user manual