AddAudit
Package Trax.Api.GraphQL.AuditNamespace Trax.Api.GraphQL.AuditSource TraxGraphQLBuilderAuditExtensions.cs
NO WARRANTY. Trax auth is plumbing, not a security product. You are solely responsible for securing systems that use it. See API Security.
Extension method on TraxGraphQLBuilder, declared on TraxGraphQLBuilderAuditExtensions, that registers the GraphQL audit pipeline: a bounded channel, a background writer, a HotChocolate diagnostic listener, the sink TSink and a redactor.
Signature
public static TraxGraphQLBuilder AddAudit<TSink>(
this TraxGraphQLBuilder builder,
Action<TraxAuditOptions>? configure = null
)
where TSink : class, ITraxAuditSink;Parameters
| Parameter | Type | Description |
|---|---|---|
TSink | type argument | The ITraxAuditSink that receives the entries. |
builder | TraxGraphQLBuilder | The builder AddTraxGraphQL passes to its callback. |
configure | Action<TraxAuditOptions>? | Sets TraxAuditOptions. Omitted, every option keeps its default. |
Returns
The same TraxGraphQLBuilder, for chaining.
Behavior
Every GraphQL request is recorded as a TraxAuditEntry, including one a gate refuses: a refused train, query model or operations call is an entry with Success = false and the caller's scheme-qualified PrincipalId. A socket refused at connection_init and a failed event of an accepted subscription are recorded too. The request thread never waits on the sink.
The options are validated when the host starts. A value out of range refuses startup with an OptionsValidationException naming the option; the rules are on TraxAuditOptions.
Throws ArgumentNullException when builder is null.
Registered services
| Service | Lifetime | Purpose |
|---|---|---|
TraxAuditChannel | Singleton | Bounded channel between the listener and the writer. Counts dropped entries. |
TraxGraphQLAuditListener | Singleton, added to the schema as a diagnostic event listener | Builds an entry for each request and offers it to the channel. |
TraxAuditWriter | Hosted service | Drains the channel in batches and calls the sink, with retries. On shutdown it writes every accepted entry within the host's shutdown timeout. |
ITraxAuditSink -> TSink | Scoped | The destination. It is resolved from a new scope for each write attempt, so an IDbContextFactory<T> or a scoped DbContext both work. |
ITraxAuditRedactor -> DefaultAuditRedactor | Singleton, only when none is registered | Records no variables. Register your own ITraxAuditRedactor to record them. |
ISocketRefusalObserver -> TraxSocketRefusalAudit | Singleton | Records a socket refused at connection_init, which never reaches the listener. |
IHttpContextAccessor | Singleton | The listener reads HttpContext.User. |
TimeProvider | Singleton, only when none is registered | TimeProvider.System. |
IValidateOptions<TraxAuditOptions> | Singleton, with ValidateOnStart | Refuses startup when an option is out of range. |
| Disclaimer hosted service | Singleton, registered once | Logs the NO WARRANTY notice at startup. |
Example
services.AddTraxGraphQL(graphql =>
graphql.AddAudit<AuditTableSink>(opts =>
{
opts.ChannelCapacity = 10_000;
opts.BatchSize = 50;
opts.FlushInterval = TimeSpan.FromMilliseconds(500);
})
);See also
- Audit pipeline: what an entry records, drops and shutdown.
- Tune the audit pipeline
- TraxAuditOptions, ITraxAuditSink, ITraxAuditRedactor
- The Auth sample stores entries in a table and serves them to auditors as a gated query model.