Skip to content
Volidator Docs

log()

log() encrypts a single audit event and sends it to the ingestion worker. It returns true if the event was accepted, false if it was not. It does not throw on network errors.

Signature

Section titled “Signature”
async log(payload: LogPayload): Promise<boolean>

LogPayload

Section titled “LogPayload”
Name Type Required Description
actor string | ReferencePayload Yes (or actorId) Identifier of the user or system that performed the action. If listed in referenceKeys, must be a { id: string, pii: string } object.
actorId string Yes (or actor) Alias for actor. Supports plain strings only.
action string Yes The action performed. Use dot notation: invoice.download, user.delete.
target string | ReferencePayload No The resource the action was performed on. If listed in referenceKeys, must be a { id: string, pii: string } object.
targetId string No Alias for target. Supports plain strings only.
tenant string | ReferencePayload No The organization/tenant identifier the action was scoped to. If listed in referenceKeys, must be a { id: string, pii: string } object.
tenantId string No Alias for tenant. Supports plain strings only.
metadata Record<string, any> No Arbitrary key-value pairs. Encrypted with the payload. Values for keys listed in referenceKeys must be { id: string, pii: string } objects.
context TelemetryContext No Manual telemetry context. Use this if not passing req.
telemetry TelemetryConfig No Per-log telemetry override. Merges with the instance config.
req any No HTTP request object. The SDK extracts IP, user-agent, and headers from it.

ReferencePayload

Section titled “ReferencePayload”
type ReferencePayload = {
  id: string;   // The non-sensitive identifier stored in the database (e.g. "usr_123")
  pii: string;  // The sensitive value used ONLY for computing the blind index (e.g. "[email protected]")
};

Return value

Section titled “Return value”

true if the ingestion worker returned a 2xx status. false on any error or non-2xx response.

Error behavior

Section titled “Error behavior”

log() catches all network errors internally and returns false. It logs the error message to console.error with a [Volidator] prefix.

To handle failures in your code:

const ok = await volidator.log({
  actor: session.userId,
  action: 'file.upload',
  target: fileId,
  req: request,
});


if (!ok) {
  // Log to your own error tracker or retry queue
}

Examples

Section titled “Examples”

Minimal log:

await volidator.log({
  actor: 'user_123',
  action: 'invoice.download',
});

Log with request context:

await volidator.log({
  actor: session.userId,
  action: 'settings.update',
  target: 'account_settings',
  metadata: { fields: ['email', 'timezone'] },
  req: request,
});

Log with per-request telemetry override:

await volidator.log({
  actor: session.userId,
  action: 'export.download',
  target: exportId,
  req: request,
  telemetry: { preset: 'full' },
});

Log with Reference-Based Redaction (JIT Hydration):

Assuming 'actor' and 'metadata.email' are configured in referenceKeys:

await volidator.log({
  actor: { id: 'usr_890', pii: '[email protected]' },
  action: 'patient.view',
  metadata: {
    email: { id: 'usr_890', pii: '[email protected]' },
    source: 'web_portal', // Not in referenceKeys, passes through raw
  },
});

Payload Validation & Sanitization

Section titled “Payload Validation & Sanitization”

To ensure high performance, safety, and compatibility, the SDK automatically applies several validation and soft truncation limits before encrypting and transmitting the payload:

  • Field Capping: Top-level string fields (actor, action, target, tenant) are automatically truncated to a maximum of 255 characters (with ... appended if truncated).
  • User-Agent String: If user-agent tracking is enabled, the userAgent string is truncated to a maximum of 1,000 characters.
  • Metadata Depth: Custom metadata object depth is restricted to a maximum of 5 levels (deeper nested objects are replaced with "[Truncated - Depth Exceeded]" to prevent parser exhaustion).
  • Metadata Size Limit: The total serialized size of the metadata object cannot exceed 10KB (10,240 bytes). If the custom metadata object is larger than 10KB, the log() call will throw a validation error.
Section titled “Related”