Policy Tracing and Explainability¶

Privacera PolicySync connectors emit structured audit events that explain how policies are loaded, applied, and enforced on target data services. These events give administrators and security teams a granular, auditable view of grant and revoke operations, changelog execution, loader statistics, and long-running work progress.

PolicySync writes events to the policysync_audit stream. Audit Server indexes them into Apache Solr by default and can forward the same JSON payloads to Amazon SQS, Amazon SNS, or object storage (Amazon S3, Azure Blob, Google Cloud Storage) when those destinations are configured.

What you can trace¶

Area	Event types	What it shows
Access decisions	`ACCESS`	Each grant or revoke (or identity lifecycle step) after the connector executes it on the target service
Policy batches	`CHANGELOG`, `POLICY_RESPONSE`	Changelog lifecycle and per-policy ACL rollups for Ranger policy updates
Background sync	`LOADER`	Resource, principal, permission, tag, and audit loader statistics at fixed intervals or on demand
Long-running work	`PROGRESS`	Incremental progress while a large changelog or loader processes many items

Event destinations¶

Destination	Configuration
Apache Solr (default)	Audit Server; query from Privacera Portal or Solr directly
Amazon SQS	Send audits to Amazon SQS
Amazon SNS	Send audits to Amazon SNS
Object storage	Send audits to S3, Send audits to GCS
Multiple sinks	Connector audit output destinations

Handler requirement for external sinks

PolicySync audit handler V2 must be enabled when routing connector events to SQS or object storage. See Connector audit output destinations.

For Ranger plugin access audits (distinct from PolicySync connector tracing), see Audit log JSON format.

Event JSON format¶

The same JSON payload shape is used when Audit Server indexes events into Solr and when events are forwarded to Amazon SQS, Amazon SNS, or object storage.

Wire contract¶

Topic	Contract
Wire format	One JSON object per event; UTF-8
Naming	Property names use camelCase
Enum-like values	String literals such as `eventType`, `status`, and `changeLogType` use a fixed vocabulary: UPPERCASE with underscores (for example `RANGER_POLICIES`, `COMPLETED`). If a transport lowercases or aliases them, normalize before comparison
Extensibility	Unknown root keys and `extraInfo` keys may appear. Ignore or store them unless you explicitly handle them

Event types¶

`eventType`	Description
`ACCESS`	Grant or revoke on data resources, or per-step identity events (user or group lifecycle, membership)
`CHANGELOG`	Changelog-driven policy or ACL batch execution; `extraInfo.policies` and/or completion stats
`LOADER`	Statistics about resource, principal, permission, tag, or audit loading from the target service or Ranger
`PROGRESS`	Progress updates for long-running changes (resource or permission processing)
`POLICY_RESPONSE`	Per-policy summary after a Ranger policies changelog completes
`CONFIG_CHANGE`	Connector configuration change notification (when enabled)

Common fields¶

All event types include these fields.

Field	Type	Description
`eventType`	String	`ACCESS`, `CHANGELOG`, `LOADER`, `PROGRESS`, `POLICY_RESPONSE`, or `CONFIG_CHANGE`. Always uppercase
`evtTime`	String	Event timestamp. ISO 8601 (for example `2025-11-14T01:31:00.170Z`) or `yyyy-MM-dd HH:mm:ss` depending on the emitter
`timeTakenMs`	Integer	Wall-clock duration in milliseconds for the work unit this event represents
`status`	String	Lifecycle state; uppercase. See Status
`msg`	String	Optional human-readable detail (for example failure or skip reason)
`connectorType`	String	Connector family (for example `Lakeformation`, `databricks-unity-catalog`)
`connector`	String	Connector instance name or identifier
`extraInfo`	Object	Optional metadata; shape depends on `eventType`
`uuid`	String	Optional document identifier when assigned by the sink

Status¶

Value	Typical meaning
`QUEUED`	Accepted or scheduled; execution not yet started
`STARTED`	Execution has begun
`RUNNING`	Execution in progress
`PROCESSING`	Progress pipeline processing state
`COMPLETED`	Finished successfully
`FAILED`	Finished with error
`SKIPPED`	No change applied (nothing to do, or intentionally bypassed)

Changelogs and `changeLogType`¶

PolicySync records work in changelogs. For each stream of updates it maintains a changelog and applies deltas to the target service.

Common `changeLogType` values¶

Canonical changeLogType strings use UPPERCASE with underscores. Privacera may add new values in future releases.

`changeLogType`	Role
`RANGER_POLICIES`	Policy changes from the portal; delta vs store; update ACLs in the service
`SERVICE_RESOURCES`	Service resource loader detected a delta; update ACLs
`RANGER_PRINCIPALS`	Delta while loading users, groups, or roles from Ranger; reconcile principals in the service
`SERVICE_PRINCIPALS`	Delta while loading principals from the service; reconcile back and refresh ACLs
`SERVICE_PERMISSIONS`	Service permission loader detected a delta vs the service; update ACLs
`RANGER_TAGS`	Ranger tag metadata pipeline; tag-related ACL refresh
`RANGER_ROLES`	Ranger roles and related Ranger changelog stream

Correlating `changeLogId`¶

When an event includes changeLogId, use these rules together with ACCESS and CHANGELOG events:

Rule	Detail
Scope	A `changeLogId` applies to one PolicySync connector instance only
Global uniqueness	Not guaranteed across deployments; two instances may independently emit the same id
Safe correlation	Use `connector` (instance identifier) together with `changeLogId`

Type-specific fields¶

`POLICY_RESPONSE`¶

Emitted once per policy when a RANGER_POLICIES changelog completes. Per-policy ACL rollups live in extraInfo.aclsExecuted; the CHANGELOG completion event carries id and version summaries only.

Field	Type	Description
`changeLogId`	String or Integer	Changelog run id on this connector instance
`changeLogType`	String	Changelog type (typically `RANGER_POLICIES`)
`policyId`	String or Integer	Policy identifier
`policyVersion`	String or Integer	Policy version
`policyLabel`	String	Correlation or trace label
`policyName`	String	Policy name

`extraInfo.aclsExecuted`¶

Field	Type	Description
`total`	Integer	ACL operations considered
`applied`	Integer	Successfully applied
`failed`	Integer	Failed
`skipped`	Integer	Skipped
`timeTakenMS`	Integer	Time spent on ACL execution for this policy, in milliseconds. Some emitters may use `timeTakenMs`; treat as equivalent after normalizing keys

`ACCESS`¶

Emitted after a grant or revoke (or identity operation) is executed on the target service.

Field	Type	Description
`changeLogId`	String or Integer	Required. Changelog run id on this connector instance
`changeLogType`	String	Required. One of the common `changeLogType` values
`policyId`	Integer or Array	Policy identifier, or list when several Ranger policies merge into one operation
`policyVersion`	String or Array	Policy version(s), aligned with `policyId`
`policyName`	String	Policy name
`policyType`	String	Policy type (typically `access`)
`policyLabel`	String	Correlation or trace label
`resourceType`	String	Data resource (`table`, `schema`, …) or identity object (`user`, `group`, …)
`resource`	String	Resource path or principal identifier
`permission`	String	Data permission (`select`, `insert`, …) or connector-defined operation
`action`	String	`grant` or `revoke` for ACLs; identity verbs such as `create`, `update`, `add_member`, `remove_member` where applicable
`cmd`	String	Optional command executed
`cmdType`	String	Command channel: `sql` or `api`
`actor`	String	User, group, or role name
`actorType`	String	`USER`, `ROLE`, or `GROUP`
`ondemandTaskId`	String or Integer	Optional. Present when the event originates from an event-driven on-demand task

Typical field mapping (connector-specific)¶

Connector	`permission`	`resource`	`actor` / `actorType`	`cmd`
Lake Formation	e.g. `select`	Table path (`<account>/<region>/<database>/<table>`)	IAM role ARN (`ROLE`)	Grant line as executed
Databricks Unity Catalog	e.g. `execute`	`catalog/schema/table`	e.g. `account users` (`GROUP`)	`GRANT …` SQL statement

`CHANGELOG`¶

Field	Type	Description
`changeLogId`	String or Integer	Changelog run id on this connector instance
`changeLogType`	String	Changelog type

`extraInfo` for `CHANGELOG`¶

Field	Type	Description
`policies`	Array	Optional. One entry per policy in the changelog execution summary
`principals`	Object	Optional. User, group, or role update counts
`resources`	Object	Optional. Resource sync counts (aggregate or by type)
`policiesChunkIndex`	Integer	Optional. 1-based index when completion is split across multiple events
`policiesChunkCount`	Integer	Optional. Total number of completion chunks
`policiesTotalCount`	Integer	Optional. Total policies in the full completion

Each element of extraInfo.policies[]:

Field	Type	Description
`id`	String	Policy identifier
`version`	String	Policy version
`label`	String	Correlation or trace label
`name`	String	Policy name
`aclsExecuted`	Object	ACL rollup (same shape as extraInfo.aclsExecuted; omitted on Solr completion summaries that only carry `id` and `version`)

Each principal kind under extraInfo.principals (users, groups, roles):

Field	Type	Description
`found`	Integer	Principals found
`added`	Integer	Principals added
`updated`	Integer	Principals updated
`deleted`	Integer	Principals deleted

`LOADER`¶

Field	Type	Description
`changeLogId`	String or Integer	Loader run id on this connector instance
`changeLogType`	String	Loader pipeline type (for example `SERVICE_RESOURCES`)
`loaderType`	String	Data being loaded. See loaderType values
`ondemandTaskId`	Integer	Optional. Present when the loader starts from an event-driven task
`triggerFrom`	String	How the loader started: `CONFIG_CHANGE`, `SCHEDULED`, or `EVENT`

`loaderType` values¶

Value	Meaning
`LOAD_SERVICE_RESOURCES`	Service resource loader
`LOAD_SERVICE_PERMISSIONS`	Service permission loader
`LOAD_SERVICE_PRINCIPALS`	Service principal loader
`LOAD_RANGER_PRINCIPALS`	Ranger principal loader
`LOAD_SERVICE_AUDITS`	Service audit loader
`LOAD_SERVICE_TAGS`	Service tag loader
`LOAD_SERVICE_TAG_RECONCILE`	Service tag reconcile loader
`LOAD_SERVICE_TAGS_PERMISSIONS`	Service tag permissions loader
`LOAD_RANGER_TAGS_PERMISSIONS`	Ranger tag permissions loader
`RECOVERY_STATE`	Internal RocksDB recovery lifecycle

`extraInfo` for `LOADER`¶

Field	Type	Description
`resources`	Object	Resource sync summary, keyed by resource type
`tags`	Object	Tag sync summary, keyed by tag type
`resourcesNotInSync`	Integer	Resources not in sync with Ranger policies (permission loader)
`totalTimeTakenMs`	Integer	Total loader duration
`users`, `groups`, `roles`	Object	Principal scan counts (`found`, `updated`, `ignored`) for service principal loader

Each resource or tag type under extraInfo.resources or extraInfo.tags:

Field	Type	Description
`found`	Integer	Items found
`added`	Integer	Items added
`updated`	Integer	Items updated
`deleted`	Integer	Items deleted

`PROGRESS`¶

Field	Type	Description
`changeLogId`	String or Integer	Progress context changelog id
`changeLogType`	String	Progress context changelog type

`extraInfo.progress`¶

Field	Type	Description
`total`	Integer	Cumulative items processed so far
`sinceLastReport`	Integer	Items processed since the previous progress report

Example events¶

`POLICY_RESPONSE`¶

JSON
{
  "eventType": "POLICY_RESPONSE",
  "evtTime": "2025-11-14T01:31:00.170Z",
  "timeTakenMs": 100,
  "status": "COMPLETED",
  "msg": "Applied Ranger policy policy1.",
  "connectorType": "Lakeformation",
  "connector": "Lakeformation-instance1",
  "changeLogId": 22576,
  "changeLogType": "RANGER_POLICIES",
  "policyId": 1,
  "policyVersion": 3,
  "policyLabel": "correlationId",
  "policyName": "policy1",
  "extraInfo": {
    "aclsExecuted": {
      "total": 10,
      "applied": 10,
      "failed": 0,
      "skipped": 0,
      "timeTakenMS": 120
    }
  }
}

`ACCESS` — Lake Formation (table SELECT grant)¶

JSON
{
  "eventType": "ACCESS",
  "evtTime": "2025-11-14T01:31:00.170Z",
  "timeTakenMs": 100,
  "status": "COMPLETED",
  "msg": "",
  "connectorType": "Lakeformation",
  "connector": "Lakeformation-instance1",
  "changeLogId": 22576,
  "changeLogType": "RANGER_POLICIES",
  "policyId": 1,
  "policyVersion": 111,
  "policyName": "policyname",
  "policyType": "access",
  "policyLabel": "correlationId",
  "resourceType": "table",
  "resource": "975xxxxxx/us-west-1/db1/table1",
  "permission": "select",
  "action": "grant",
  "cmd": "Granted SELECT on table 975xxxxxx/us-west-1/db1/table1 for Role arn:aws:iam::975xxxxxx:role/lf-consumer-role-2",
  "cmdType": "api",
  "actor": "arn:aws:iam::975xxxxxx:role/lf-consumer-role-2",
  "actorType": "ROLE",
  "extraInfo": {}
}

`ACCESS` — Databricks Unity Catalog (schema EXECUTE grant)¶

JSON
{
  "eventType": "ACCESS",
  "evtTime": "2025-11-14T01:31:00.170Z",
  "timeTakenMs": 50,
  "status": "COMPLETED",
  "msg": "",
  "connectorType": "databricks-unity-catalog",
  "connector": "databricks-unity-catalog-instance1",
  "changeLogId": 22576,
  "changeLogType": "RANGER_POLICIES",
  "policyId": 1,
  "policyVersion": 111,
  "policyName": "policyname",
  "policyType": "access",
  "policyLabel": "correlationId",
  "resourceType": "schema",
  "resource": "catalog1/schema1",
  "permission": "execute",
  "action": "grant",
  "cmd": "GRANT EXECUTE ON SCHEMA `catalog1`.`schema1` TO `account users`;",
  "cmdType": "sql",
  "actor": "account users",
  "actorType": "GROUP",
  "extraInfo": {}
}

`CHANGELOG` — Lake Formation¶

JSON
{
  "eventType": "CHANGELOG",
  "evtTime": "2025-11-14T01:31:00.170Z",
  "timeTakenMs": 100,
  "status": "SKIPPED",
  "msg": "skipped because of this",
  "connectorType": "Lakeformation",
  "connector": "Lakeformation-instance1",
  "changeLogId": 22576,
  "changeLogType": "RANGER_POLICIES",
  "extraInfo": {
    "policies": [
      {
        "id": "1",
        "version": "3"
      },
      {
        "id": "2",
        "version": "3"
      }
    ]
  }
}

Large policy updates

For very large RANGER_POLICIES completions, PolicySync may split extraInfo.policies across multiple CHANGELOG events and add chunk metadata. See CHANGELOG completion audit size limits.

`LOADER` — service resource loader¶

JSON
{
  "eventType": "LOADER",
  "evtTime": "2025-11-14T01:31:00.170Z",
  "timeTakenMs": 100,
  "status": "COMPLETED",
  "msg": "Resource loader completed",
  "connectorType": "Lakeformation",
  "connector": "Lakeformation-instance1",
  "changeLogId": 22576,
  "changeLogType": "SERVICE_RESOURCES",
  "loaderType": "LOAD_SERVICE_RESOURCES",
  "triggerFrom": "SCHEDULED",
  "extraInfo": {
    "resources": {
      "catalog": {
        "found": 110,
        "added": 11,
        "updated": 12,
        "deleted": 12
      },
      "database": {
        "found": 110,
        "added": 11,
        "updated": 12,
        "deleted": 12
      }
    },
    "totalTimeTakenMs": 100
  }
}

`PROGRESS`¶

JSON
{
  "eventType": "PROGRESS",
  "evtTime": "2025-11-14T01:31:00.170Z",
  "timeTakenMs": 100,
  "status": "PROCESSING",
  "msg": "",
  "connectorType": "Lakeformation",
  "connector": "Lakeformation-instance1",
  "changeLogId": 22576,
  "changeLogType": "RANGER_POLICIES",
  "extraInfo": {
    "progress": {
      "total": 200,
      "sinceLastReport": 100
    }
  }
}

Policy Tracing and Explainability¶

What you can trace¶

Event destinations¶

Event JSON format¶

Wire contract¶

Event types¶

Common fields¶

Status¶

Changelogs and changeLogType¶

Common changeLogType values¶

Correlating changeLogId¶

Type-specific fields¶

POLICY_RESPONSE¶

extraInfo.aclsExecuted¶

ACCESS¶

Typical field mapping (connector-specific)¶

CHANGELOG¶

extraInfo for CHANGELOG¶

LOADER¶

loaderType values¶

extraInfo for LOADER¶

PROGRESS¶

extraInfo.progress¶

Example events¶

POLICY_RESPONSE¶

ACCESS — Lake Formation (table SELECT grant)¶

ACCESS — Databricks Unity Catalog (schema EXECUTE grant)¶

CHANGELOG — Lake Formation¶

LOADER — service resource loader¶

PROGRESS¶

Changelogs and `changeLogType`¶

Common `changeLogType` values¶

Correlating `changeLogId`¶

`POLICY_RESPONSE`¶

`extraInfo.aclsExecuted`¶

`ACCESS`¶

`CHANGELOG`¶

`extraInfo` for `CHANGELOG`¶

`LOADER`¶

`loaderType` values¶

`extraInfo` for `LOADER`¶

`PROGRESS`¶

`extraInfo.progress`¶

`POLICY_RESPONSE`¶

`ACCESS` — Lake Formation (table SELECT grant)¶

`ACCESS` — Databricks Unity Catalog (schema EXECUTE grant)¶

`CHANGELOG` — Lake Formation¶

`LOADER` — service resource loader¶

`PROGRESS`¶