Documentation
¶
Overview ¶
Package audit carries server audit records through context so that handlers and services can enrich the record the API middleware created, mirroring how attributes are added to the ambient OpenTelemetry span.
The middleware in the api package creates the record, stores it in the request context via WithRecord, and logs it when the request finishes. Deeper layers call RecordFromContext and the nil-safe Add* helpers; when the operation is not audited these are no-ops.
Index ¶
- Constants
- Variables
- func AddParam[T string | bool | int | int64 | []string](rec *model.AuditRecord, key string, val T)
- func ChangedJSONKeys(prev, next any) []string
- func RecordFromContext(ctx context.Context) *model.AuditRecord
- func TruncateID(s string) string
- func TruncateIDs(vals []string) []string
- func WithRecord(ctx context.Context, rec *model.AuditRecord) context.Context
Constants ¶
const ( // KeyCallerPluginID identifies the calling plugin on inter-plugin bridge // routes. It must not be named "plugin_id": the server unconditionally // stamps that parameter with this plugin's own ID when the record is // logged (see PluginAPI.LogAuditRecWithLevel), which would overwrite it. KeyCallerPluginID = "agents.caller_plugin.id" // KeyMCPPluginID identifies the target plugin of an admin operation on a // plugin-backed MCP server. Distinct from KeyCallerPluginID (the actor). KeyMCPPluginID = "agents.mcp_plugin.id" // MetaTraceID is the meta key carrying the OpenTelemetry trace ID of the // request, letting an auditor pivot from an audit record to the full // trace of what happened. MetaTraceID = "trace_id" )
Variables ¶
var ( KeyUserID = string(telemetry.UserID) KeyChannelID = string(telemetry.ChannelID) KeyPostID = string(telemetry.PostID) KeyThreadRootPostID = string(telemetry.ThreadRootPostID) KeyAgentID = string(telemetry.AgentID) KeyAgentName = string(telemetry.AgentName) KeyToolName = string(telemetry.ToolName) KeyToolID = string(telemetry.ToolID) KeyMCPServer = string(telemetry.MCPServer) KeyMCPTool = string(telemetry.MCPTool) )
Parameter keys for object identifiers in audit records. They reuse the attribute key strings from telemetry/attributes.go so audit records and traces share one vocabulary and join without a translation table.
Values must be identifiers only — never prompt content, conversation or channel content, tool arguments/results, tokens, or configuration values.
Functions ¶
func AddParam ¶
AddParam adds an event parameter to rec. It is a no-op when rec is nil so call sites reached outside an audited request (RecordFromContext returned nil) need no guards. Only identifier-shaped values belong here; the type set intentionally excludes maps and arbitrary structs.
func ChangedJSONKeys ¶
ChangedJSONKeys returns the sorted top-level JSON keys whose values differ between prev and next. It exists for audit enrichment of objects that carry secrets or user content: the record may say which fields changed but never what they changed to. Keys present on only one side are reported as changed; a nil prev (or next) marshals to null and behaves as an empty object, so every key of the other side is reported.
func RecordFromContext ¶
func RecordFromContext(ctx context.Context) *model.AuditRecord
RecordFromContext returns the audit record carried by ctx, or nil when the current operation is not audited.
func TruncateID ¶
TruncateID clamps a not-yet-validated identifier for audit recording so an oversized request body cannot pump arbitrary content into the audit log.
func TruncateIDs ¶
TruncateIDs clamps a not-yet-validated identifier list for audit recording: every entry is length-clamped and the list itself is capped, with a marker entry appended when elements were dropped.
func WithRecord ¶
WithRecord returns a context carrying rec. A nil rec returns ctx unchanged.
Types ¶
This section is empty.
Source Files