Audit Logging

​

API

• log.vars.ip - IP of client initiating the request
• log.vars.userAgent - User-Agent header of client initiating the request. Note that User-Agent headers that are too long (over 512 bytes) may be truncated
• log.vars.requestId - the request ID
• log.vars.now - the timestamp of when the function was run or replayed from the cache, as milliseconds from the Unix epoch
• log.vars.bijectionActor - information about the admin, if the function was invoked using admin auth (either directly or while acting as an end user, e.g. from the console), otherwise null

import { log } from "bijection/server";
import { v } from "bijection/values";
import { mutation } from "./_generated/server";
import { internal } from "./_generated/api";

export const updateDocument = mutation({
  args: {
    userId: v.string(),
    orgId: v.string(),
    documentId: v.id("documents"),
  },
  handler: async (ctx, { userId, orgId, documentId }) => {
    const document = await ctx.db.get("documents", documentId);

    const identity = await ctx.auth.getUserIdentity();
    const { name: deploymentName } = await ctx.meta.getDeploymentMetadata();
    const { name: functionName } = await ctx.meta.getFunctionMetadata();

    await log.audit({
      action: "document.viewed",
      actor: { userId, authUserId: identity?.sub },
      source: {
        ip: log.vars.ip,
        userAgent: log.vars.userAgent,
        deploymentName,
        functionName,
      },
      fields: {
        documentId,
        orgId,
        deploymentName,
        functionName,
      },
    });

    // These are available in code in mutations & actions,
    // so you can pass them along across scheduler boundaries, etc.
    // For queries, they will be available in logs but not in code.
    const { ip, userAgent, requestId } = await ctx.meta.getRequestMetadata();
    await ctx.scheduler.runAfter(0, internal.foo.bar, {
      requestMetadata: {
        ip,
        userAgent,
        requestId,
      },
      documentId,
    });

    return document;
  },
});

{
  "action": "document.viewed",
  "actor": {
    "userId": "...",
    "authUserId": "..."
  },
  "source": {
    "ip": "...",
    // ...
  },
  "fields": {
    // ...
  }
}

​

Guarantees

• Every time a query result is streamed to any subscriber (including query cache hits)
  • Cached queries will replay audit logs with updated timestamp, IP, and user agent
• On mutations, both on success and failure, and possibly on OCC retries
• Function commit will block on log persistence.

​

Limits

• Each function execution can log at most 4MB of audit logs, at most 500 audit logs, and at most 1MB per log. Audit logs in nested function calls count towards the parent function’s limit. If a function exceeds the limits, it will fail. We suggest keeping audit logs under 10 KB to reduce latency.
• ip and userAgent is not available in the audit logs for crons or scheduled functions. However, mutations and actions can access them via ctx.meta.getRequestMetadata so they can pass it as an argument to the scheduled function, if desired.
• Auth identity should be manually specified in your log bodies. Per usual, auth is not accessible in scheduled functions, crons, or in components. This implies passing the actor in as an argument to component functions. We may add auth capabilities for components in the future.
• The current code version is not directly available. As a workaround, you can update code or set an environment variable with a version identifier, such as a git hash.
• We may log events when a transaction ends up rolling back due to conflicts, or if the transaction fails otherwise. Delivery is at least once.
• There will be a delay between when an audit log is emitted and when it is delivered to your destination S3 bucket.

​

Billing

​

Development

​

Configuration