Audit Logs Reference

What Audit Logs capture#

Audit Logs answer:

Audit events are not debug logs, traces, metrics, or product analytics. Keep them structured, bounded, durable, and safe for an operator to inspect.

Service registration#

AddSqlOS<TContext>() registers ISqlOSAuditLogService.

builder.Services.AddSqlOS<ExampleAppDbContext>(options =>
{
    options.UseSqlServer(connectionString);
});

Inject the service into server-side application code. Frontends should not write audit rows directly.

app.MapPost("/api/documents/{id}/share", async (
    string id,
    ShareDocumentRequest request,
    ISqlOSAuditLogService auditLogs,
    HttpContext httpContext,
    CancellationToken ct) =>
{
    await auditLogs.RecordAsync(new SqlOSAuditLogRecordRequest(
        Action: "document.shared",
        OrganizationId: request.OrganizationId,
        ApplicationKey: "workspace-web",
        Source: "application",
        Actor: new SqlOSAuditActor("user", request.UserId, request.UserDisplayName),
        Targets:
        [
            new SqlOSAuditTarget("document", id, request.DocumentName)
        ],
        Context: SqlOSAuditContext.FromHttpContext(httpContext),
        Metadata: new Dictionary<string, object?>
        {
            ["result"] = "success",
            ["role"] = request.Role
        },
        IdempotencyKey: $"document:{id}:shared:{request.UserId}:{httpContext.TraceIdentifier}"),
        ct);
 
    return Results.NoContent();
});

Record request#

SqlOSAuditLogRecordRequest

Actor#

SqlOSAuditActor

Targets#

SqlOSAuditTarget

Use multiple targets when one operation affects a hierarchy. For example, an inventory update can target both the location and the inventory_item.

Context#

SqlOSAuditContext.FromHttpContext(httpContext) captures:

• remote IP address
• user agent
• sid claim as session id
• X-Request-ID / X-Request-Id, falling back to HttpContext.TraceIdentifier
• X-Correlation-ID / X-Correlation-Id

Create SqlOSAuditContext manually for background jobs, service accounts, queues, and scheduled maintenance.

Metadata safety#

Metadata must be non-secret. Do not include:

• passwords
• access or refresh tokens
• API keys
• client secrets
• raw authorization headers
• cookies
• private keys
• raw exceptions or stack traces
• full request or response bodies

SqlOS redacts common secret-like metadata keys, but callers are still responsible for sending safe data. Prefer stable fields such as result, reason, counts, role names, and non-sensitive before/after values.

Query request#

SqlOSAuditLogListRequest

Results sort by OccurredAt descending, then IngestedAt descending.

Service methods#

public interface ISqlOSAuditLogService
{
    Task<SqlOSAuditLogRecordResult> RecordAsync(
        SqlOSAuditLogRecordRequest request,
        CancellationToken cancellationToken = default);
 
    Task<SqlOSAuditLogListResult> ListAsync(
        SqlOSAuditLogListRequest request,
        CancellationToken cancellationToken = default);
 
    Task<SqlOSAuditLogEvent?> GetAsync(
        string id,
        CancellationToken cancellationToken = default);
 
    Task<SqlOSAuditLogCsvExportResult> ExportCsvAsync(
        SqlOSAuditLogListRequest request,
        CancellationToken cancellationToken = default);
}

RecordAsync returns Created = false when the idempotency key already exists and the original event is returned.

Dashboard#

The embedded dashboard exposes Audit Logs as a top-level governance page:

/sqlos/admin/audit/logs

Operators can filter by organization, application, source, action, actor, target, result/status metadata, text search, and date range. Selecting a row opens structured details for actor, targets, context, and metadata.

The older AuthServer audit route links into the same central view filtered to source=authserver.

Admin API#

Admin APIs are mounted when you call app.MapSqlOS(). They are protected by the same dashboard authorization as /sqlos/admin: password-mode dashboard sessions, your configured Dashboard.AuthorizationCallback, or your deployment's dashboard-facing proxy/SSO controls. Unauthorized requests return 404.

Default base path:

/sqlos/admin/audit/api

CSV export uses the same filters as listing. It is bounded to 5,000 rows and a maximum 366-day date range. If no dates are supplied, export defaults to the last 30 days.

Retail example#

The Retail example records host-application events with:

ApplicationKey = "northwind-retail"
Source = "application"

Successful chain, location, and inventory mutations appear in /sqlos/admin/audit/logs. Filter by northwind-retail to inspect only Retail events.

See also#

• Add audit logs to your app
• Dashboard
• API Reference