Reference

TraxAuditOptions

Package Trax.Api.GraphQL.AuditNamespace Trax.Api.GraphQL.AuditSource TraxAuditOptions.cs, TraxAuditOptionsValidator.cs

NO WARRANTY. Trax auth is plumbing, not a security product. You are solely responsible for securing systems that use it. See API Security.

The options of the audit pipeline, set through AddAudit<TSink>(opts => ...).

Signature

public sealed class TraxAuditOptions

Properties

PropertyTypeDefaultDescription
ChannelCapacityint10_000Most entries the channel holds. When it is full a new entry is dropped and counted in trax.audit.dropped.
BatchSizeint50Most entries handed to the sink in one call.
FlushIntervalTimeSpan500 msLongest the writer waits for a batch to fill before it writes a partial one.
MaxDocumentLengthint65_536A longer document is cut to this length, marked ...[truncated], and followed by [selected fields: ...], every Type.field the operation selects. The list names each schema coordinate once, so its size is bounded by the schema rather than by the request.
MaxOperationNameLengthint256A longer operation name is cut to this length and marked ...[truncated]. The name is whatever the caller sent.
MaxErrorTextLengthint4_096A longer ErrorText is cut to this length and marked ...[truncated]. A request can raise one error per field it selects.
RecordErrorMessagesboolfalseRecords error messages in ErrorText. Off, each error is recorded as CODE at path (<masked> when it has no code) and a pipeline exception as its type name, because a message can quote what the caller sent.
SkipIntrospectionbooltrueDrops introspection operations that succeeded: every top-level selection of the executed operation is __schema, __type or __typename. One that raised an error is recorded.
SkipSubscriptionsbooltrueDrops subscriptions that were accepted (returned a stream). A subscription refused or failed when it subscribes is always recorded, and so is each failed event of an accepted one and each socket refused at connection_init.
DefaultPrincipalIdstring"<anonymous>"The PrincipalId of an entry whose request has no trax:principal-id claim.
MaxRetriesint3Retries a failing sink gets after its first attempt before the batch is dropped, so the default makes 4 attempts in all.
RetryBackoffTimeSpan100 msThe first wait between sink retries. It doubles on each attempt up to MaxRetryBackoff, and each wait is a random point between half and all of that value.
MaxRetryBackoffTimeSpan30 sThe longest wait between two sink retries, whatever the attempt.

Behavior

AddAudit validates the options when the host starts. The host refuses to start, with an OptionsValidationException naming each option out of range, when:

  • ChannelCapacity, BatchSize, MaxDocumentLength, MaxOperationNameLength or MaxErrorTextLength is 0 or less;
  • FlushInterval is zero or less;
  • MaxRetries is below 0 or above 100;
  • MaxRetryBackoff is zero or less, or above one hour;
  • RetryBackoff is negative or above MaxRetryBackoff;
  • DefaultPrincipalId is empty.

Each failure reads TraxAuditOptions.<Option> <rule>; it is <value>. Set it in AddAudit(options => ...).

The writer is single-threaded: while it retries one batch, the channel fills behind it.

Example

services.AddTraxGraphQL(graphql =>
    graphql.AddAudit<AuditTableSink>(opts =>
    {
        opts.ChannelCapacity = 50_000;
        opts.BatchSize = 200;
        opts.FlushInterval = TimeSpan.FromSeconds(2);
        opts.MaxRetries = 15;
    })
);

See also