Control Plane Logs - Formal Documentation

Outcome: You can find Control Plane audit logs by source, search them, and restrict who can view logs. Prerequisites: Access to the Formal console, or an API key with Logs access. See Permissions.

Overview

Every authenticated request to Formal’s is written as an audit log. That includes calls from the , the public API, Terraform, and machine auth such as AWS SigV4. Control Plane logs share the same Logs experience as Connector, Endpoint, and workflow activity. Use the Source filter to switch streams. See Logs for search, aggregations, export, and retention.

Log Sources

Formal tags every log with a source field. Choose a source in the Formal console, or filter with Quickwit (source:control-plane).

Source	`source` value	What it records	Typical producers
Connector	`connector`	Queries, commands, and sessions through Formal Connectors	Connectors proxying Postgres, MySQL, SSH, HTTP, Kubernetes, and more
Endpoint	`desktop`	Traffic through the Formal Endpoint	Endpoint users (for example LLM or HTTP resources)
Control Plane	`control-plane`	Authenticated Control Plane API calls	Console, public API, Terraform, SDKs, machine users
Workflow	`workflow`	Workflow runs and step activity	Workflows

Prefer source over event_type when filtering Control Plane activity. Control Plane logs use source:control-plane and fields under control_plane_request.*. Connector and Endpoint logs use event_type values such as request or session-start.

Log configurations (encryption and policy-input retention) apply to Connector and Endpoint sources only. They do not change Control Plane API audit logs.

What Gets Logged

Formal records a Control Plane log for each authenticated API call after the handler returns. Unauthenticated traffic (for example health checks) is not logged. Each entry includes:

Field	Description
Timestamp	When the API call started
User	Formal user (email, id, type, groups). Machine users may include AWS principal fields
API key	API key id and name when the caller used an API key
Command	RPC or handler name (for example `UpdatePolicy`) and type (`create`, `read`, `update`, `delete`, or `other`)
Service	Service that handled the call (for example `PoliciesService`, `LogsService`)
Method	HTTP method (`GET`, `POST`, and so on)
URL	Connect procedure path or HTTP path
Arguments	Request payload. Fields marked sensitive in the API schema are redacted
IP address	Client IP
Duration	End-to-end request duration
Policy action	Whether Control Plane permissions allowed the call: `allow`, `deny`, or `error`
Error	Error message when the call failed

control_plane_request.policy_action audits whether that API call was allowed. It is separate from who may view logs later (see Permissions for Viewing Logs).

View Control Plane Logs

Open Logs

Go to Logs in the Formal console.

Select Control Plane

Set Source to Control Plane. The table columns switch to command, service, user, method, and policy action.

Inspect an entry

Click a row to open the details panel. Review arguments, identity, and any error.

Verify: Run a Control Plane change (for example update a policy), then confirm a matching row appears under Source → Control Plane.

Search Examples

# All Control Plane audit logs
source:control-plane

# Denied Control Plane API calls
source:control-plane AND control_plane_request.policy_action:deny

# Updates by a specific user
source:control-plane AND control_plane_request.command.type:update AND control_plane_request.user.email:alice@example.com

# Calls against the Policies service
source:control-plane AND control_plane_request.service:PoliciesService

# Machine users authenticated with AWS SigV4
source:control-plane AND control_plane_request.user.type:machine AND control_plane_request.user.aws_account_id:123456789012

Control Plane Field Reference

Field	Type	Description
`source`	String	Always `control-plane` for these logs
`timestamp`	DateTime	When the call started (RFC3339)
`control_plane_request.command.name`	String	API command (for example `UpdatePolicy`)
`control_plane_request.command.type`	String	`create`, `read`, `update`, `delete`, or `other`
`control_plane_request.service`	String	Service name
`control_plane_request.method`	String	HTTP method
`control_plane_request.url`	String	Procedure or path
`control_plane_request.user.email`	String	Caller email
`control_plane_request.user.id`	String	Caller user id
`control_plane_request.user.type`	String	`human` or `machine`
`control_plane_request.user.groups`	[]String	Caller groups
`control_plane_request.user.aws_principal_arn`	String	AWS principal ARN (SigV4 machine auth)
`control_plane_request.user.aws_account_id`	String	AWS account ID (SigV4 machine auth)
`control_plane_request.api_key.id`	String	API key id when present
`control_plane_request.api_key.name`	String	API key name when present
`control_plane_request.ip_address`	String	Client IP
`control_plane_request.policy_action`	String	`allow`, `deny`, or `error`
`control_plane_request.duration`	String	Request duration
`control_plane_request.args`	Object	Redacted request payload
`control_plane_request.error`	String	Error message when the call failed

Permissions for Viewing Logs

There is no separate permission per log source. Access to Connector, Desktop, Control Plane, and workflow logs is gated by the Logs application in Control Plane permissions. If a user cannot open Logs or call Logs APIs, they cannot view Control Plane audit logs in Formal. Formal returns HTTP 403 for blocked requests.

Restrict Logs to Security Admins

package formal.app

import future.keywords.in
import future.keywords.if

default allow = true

allow := false if {
  input.app.name == "Logs"
  not "security-admins" in input.user.groups
}

Users outside security-admins cannot list or manage logs. Everyone else keeps allow-by-default access to other applications.

Allow Read-Only Logs Access

package formal.app

import future.keywords.in
import future.keywords.if

default allow = false

# Security admins: full access
allow if {
  "security-admins" in input.user.groups
}

# Auditors: read Logs only
allow if {
  input.app.name == "Logs"
  input.app.command.type == "read"
  "auditors" in input.user.groups
}

Auditors can search and view logs (List, Get) but cannot change log configurations or related write commands.

Useful Logs Commands

Goal	`input.app.name`	Example `input.app.command.name`	`input.app.command.type`
Search or open a log	`Logs`	`ListLogsV2`, `GetLog`	`read`
Natural-language search	`Logs`	`GetLogsFromNaturalLanguage`	`read`
Aggregations	`Logs`	`ListLogAggregations`, `GetGroupByAggregation`	`read`
Manage retention / log configs	`Logs`	`CreateLogConfiguration`, `UpdateLogConfiguration`	`create` / `update`

Permissions evaluate the Logs application as a whole. They do not filter by source. A user who can read Logs can query Control Plane, Connector, Desktop, and workflow logs (subject to any query they run).

Forwarding Control Plane Logs

When you configure a Log Integration, Formal forwards Control Plane logs with every other source. For object storage (S3, GCS, Azure Blob), Control Plane objects use this key prefix:

formal/logs/control-plane/{year}/{month}/{day}/{file}

Other sources use the same layout with connector, desktop, or workflow in place of control-plane.

Best Practices

Monitor denied Control Plane calls

Alert on control_plane_request.policy_action:deny in Formal or your SIEM. Spikes often mean misconfigured permissions or probing.

Limit who can view Logs

Restrict the Logs application to security or audit groups. Control Plane logs include API arguments and identity context.

Pair with change control

Use Control Plane logs to audit who changed policies, connectors, and users. Filter by control_plane_request.command.type:update or :delete.

Forward for long-term retention

Keep console search for day-to-day work. Forward to S3 or your SIEM for multi-year compliance archives.

Next Steps

Logs

Search, aggregations, export, and retention

Permissions

Configure OPA access to Formal applications

Log Integration

Forward logs to S3, Datadog, or Splunk

Logs API

Query logs with the public API (LogsService)

​Overview

​Log Sources

​What Gets Logged

​View Control Plane Logs

​Search Examples

​Control Plane Field Reference

​Permissions for Viewing Logs

​Restrict Logs to Security Admins

​Allow Read-Only Logs Access

​Useful Logs Commands

​Forwarding Control Plane Logs

​Best Practices

​Next Steps

Logs

Permissions

Log Integration

Logs API

Overview

Log Sources

What Gets Logged

View Control Plane Logs

Search Examples

Control Plane Field Reference

Permissions for Viewing Logs

Restrict Logs to Security Admins

Allow Read-Only Logs Access

Useful Logs Commands

Forwarding Control Plane Logs

Best Practices

Next Steps