Interface: Trace
Defined in: internal/trace/Trace.ts:48
Trace -- the audit log of every model call
About
The black-box recorder: what was sent, what came back, what it cost, what the checks said.
One entry per model call, written by the LLMClient through record with the request, the result, the usage and the
list-price cost; the gateway adds through annotate what it knows after its checks: the KB chunk ids, the issues, the
prompt template and its version. Helper calls (memory, query rewrite, guardrail judge, embedding) are entries of their own
ETraceKind. query serves an audit or debugging page; delete and anonymizeByUser are the forgetting side (D54, D119).
Tenant-scoped: every method takes the tenant, nothing crosses it.
Sits between the LLMClient and the orchestration, which write, and the host's ITraceRepository, which stores.
Who needs it
The LLMClient after every call; the orchestration (annotateTraces, deleteThreads, forgetUser); the host, as
gateway.trace, for its audit pages. Constructed once from IAIGatewayConfig.trace; a host replaces it through
IAIGatewayDeps.trace.
What needs
ITraceConfig.repository: the host's adapter.
Pitfalls
The entry holds the request as sent and the raw result: system prompts, tool outputs, the user's text. A repository that
must not keep them drops request and result in save; query returns them raw, so the host checks who may read before
it calls.
Implements
Methods
annotate()
annotate(
__namedParameters):Promise<void>
Defined in: internal/trace/Trace.ts:91
annotate -- adds what the gateway knows to an entry
About
The LLMClient recorded the call; the checks that came after are written here.
Loads the entry, merges the chunk ids (a set, no duplicates), appends the issues and notes the template key and version
when given, then saves it. Throws 5372588039586 / 404 for an entry the tenant does not have.
Who needs it
annotateTraces of the orchestration, after the output check of an ask or a run and for the judge entries of every
check (D73).
Parameters
__namedParameters
chunkIds
string[]
issues
IIssue[]
templateKey?
The template the request was rendered from, and its version.
templateVersion?
number
tenantId
string
traceId
string
Returns
Promise<void>
Implementation of
ITrace.annotate
anonymizeByUser()
anonymizeByUser(
__namedParameters):Promise<number>
Defined in: internal/trace/Trace.ts:216
anonymizeByUser -- keeps a user's entries as an audit skeleton
About
The numbers stay, the words go.
GDPR pseudonymisation (D54): userId becomes the pseudonym, request and result are removed; usage, cost, model, kind,
chunk ids, issues and dates stay. Returns how many entries were changed.
Who needs it
forgetUser for AIGateway.anonymizeUserData.
Parameters
__namedParameters
pseudonym
string
tenantId
string
userId
string
Returns
Promise<number>
Implementation of
ITrace.anonymizeByUser
delete()
delete(
__namedParameters):Promise<number>
Defined in: internal/trace/Trace.ts:184
delete -- removes the entries of threads
About
Hard delete: the audit of a deleted thread goes with it.
The listed thread ids, or "all" for every entry of the tenant, the ones without a thread included; narrowed to one user
when userId is given (D119). Returns how many entries went.
Who needs it
deleteThreads of the gateway's delete; forgetUser for AIGateway.deleteUserData (D54).
Parameters
__namedParameters
tenantId
string
threadIds
userId?
string
Returns
Promise<number>
Implementation of
ITrace.delete
query()
query(
__namedParameters):Promise<ITraceEntry[]>
Defined in: internal/trace/Trace.ts:149
query -- the entries of a tenant, filtered and paged
About
"Why did it say that, what did it cost": the audit page's read.
Passes the filters (ITraceFilters: user, thread, kind, dates) and the page (skip, limit) to the repository and returns
the entries as stored, request and result included.
Who needs it
The host, as gateway.trace.query, for its audit and debugging pages; the tests, to read what a call did.
Parameters
__namedParameters
filters
limit
number
skip
number
tenantId
string
Returns
Promise<ITraceEntry[]>
Implementation of
ITrace.query
record()
record(
__namedParameters):Promise<void>
Defined in: internal/trace/Trace.ts:65
record -- writes the entry of one model call
About
The call already happened; a lost entry is logged, never thrown.
Saves the entry the LLMClient built (save inserts or replaces by id). When the repository throws, the error is
logged and the call goes on: the answer belongs to the user, the audit gap to the server log.
Who needs it
LLMClient.account, after every complete and embed, also for a failed or aborted call.
Parameters
__namedParameters
entry
Returns
Promise<void>
Implementation of
ITrace.record