hs-sql-agent
2.0.2
Docs 2.0.2
Documentation version
2.0.2 Latest
2.0.2 Latest
Docs Administration

Audit

Query, summarize, export, and retain hs-sql-agent 2.0.1 audit records from the Admin control plane.

Search Filter events by action, result, actor, time range, database, MCP key, tool, and keyword.
Export Export the filtered audit set as CSV or JSON with a dedicated export permission.
Retention Inspect policy, dry-run the cutoff, then execute Archive or Purge explicitly.

The audit surface is the control-plane record of security and runtime activity. It is designed for investigation and operational review rather than as the primary application log stream.

Audit record shape

A 2.0.1 audit item can include:

AreaFields
identityActorType, ActorId, IpAddress, UserAgent
eventEventId, Action, Target, Detail, Result, CreatedAt
request/sessionRequestId, SessionId
SQL scopeAccessKeyId, DbManagementId, DatabaseName, ToolName, Operation
executionDurationMs, ReturnedRows, AffectedRows
DML/errorApprovalStatus, ErrorCategory, Definition

Not every event populates every field. Administrative account changes, MCP SQL execution, DML approval events, and runtime delivery activity naturally carry different context.

Filter audit events

GET /api/runtime/audit supports pagination and these filters:

  • action
  • keyword
  • from / to
  • result
  • actor
  • dbManagementId
  • accessKeyId
  • toolName

The default page is 1 with 20 records per page.

Daily summary

GET /api/runtime/audit/daily-summary returns daily activity aggregation. The default request covers 7 days, making it useful for spotting broad changes before drilling into individual records.

Export

Audit export is a separate authorization capability:

OperationPermission
query / summary / retention status/runtime/audit → view
export CSV or JSON/runtime/audit → export
retention dry-run / execute/runtime/audit → edit

The export endpoint accepts format=csv or format=json. 2.0.1 rejects export sets over 100,000 rows instead of attempting an unbounded download.

Retention workflow

The runtime retention policy reports whether retention is enabled, the configured day count, mode, and scheduled UTC hour.

Use the operator flow:

  1. Inspect the active retention policy.
  2. Run the dry-run endpoint to see the cutoff and matching row count.
  3. Confirm the expected mode and volume.
  4. Execute retention only after review.

Valid 2.0.1 runtime modes are:

  • Archive — write expired records to the configured archive path before deleting them from the Admin database;
  • Purge — delete expired records without creating that archive.

If AUDIT_RETENTION_DAYS=0, automatic retention is disabled and explicit retention execution is rejected.

Audit and telemetry are complementary

Audit records answer who did what, against which governed resource, with what result. Metrics and traces answer runtime health and performance questions. Use Operability and Observability for those surfaces.