Log Schemas

Overview

Log schemas modify matching Connector and Endpoint logs before Formal stores or exports them. Use schemas to remove, encrypt, truncate, or sanitize sensitive fields with field-level precision. Configure them with the formal_log_schema Terraform resource. Each schema contains:

A CEL scope that selects logs.
One or more protobuf field paths.
One or more actions for each path.
An optional asymmetric encryption key.

Configure a Log Schema

This example removes SQL literals from queries for one resource:

resource "formal_log_schema" "strip_customer_queries" {
  name = "strip-customer-queries"

  scope_cel = "log.source == \"connector\" && log.resource.id == \"${formal_resource.customers.id}\""

  path {
    name      = "log.request.query"
    strip_sql = true
  }
}

Run terraform apply, then query the resource through Formal. Verify: Open Logs and inspect the resulting request log. The query has values_stripped: true and does not contain its original literals.

Scope Fields

The scope_cel expression must return a boolean. It can use these fields:

Field	Values
`log.source`	`connector` or `endpoint`
`log.event_type`	The log event type, such as `request`
`log.resource`	`id`, `name`, and `technology`
`log.connector`	`id` and `name`
`log.space`	`id` and `name`
`log.user`	`id`, `username`, `type`, and `groups`
`log.end_user`	`id`, `username`, `type`, and `groups`

The scope cannot inspect payload fields, timestamps, or the complete log. Use paths to select payload fields after the scope matches.

Endpoint schemas use log.source == "endpoint". Stored Endpoint logs use source:desktop when you search them.

Schema Actions

Action	Behavior
`drop`	Removes the selected field. Selecting `log` drops the entire log.
`encrypt`	Encrypts one string field with the schema’s asymmetric key.
`truncate`	Limits one string field to a maximum UTF-8 byte length.
`strip_sql`	Removes literal values and parameters from a datastore query.
`encrypt_sql`	Encrypts query text, normalized text, and parameters.

encrypt and encrypt_sql require encryption_key_id. The key must use an asymmetric algorithm. See Encryption Keys. You can combine compatible actions on one path. drop takes precedence over every other action. Truncation runs before encryption. SQL stripping runs before SQL encryption.

Encryption Examples

Each example encrypts one kind of log content. Every example needs an asymmetric encryption_key_id. encrypt selects one string, google.protobuf.Struct, or google.protobuf.Value field. To encrypt a whole message, such as an HTTP body, list each sensitive field inside it. A path can cross a repeated field, such as messages. The action then applies to every element of that list. You can merge these paths into one schema. Do not repeat a path across schemas.

HTTP Bodies

This schema encrypts HTTP request and response bodies from Connectors and Endpoints:

resource "formal_log_schema" "encrypt_http_bodies" {
  name              = "encrypt-http-bodies"
  encryption_key_id = formal_encryption_key.logs_key.id
  scope_cel         = "true"

  path {
    name    = "log.request.http.body.received"
    encrypt = true
  }

  path {
    name    = "log.request.http.body.sent"
    encrypt = true
  }

  path {
    name    = "log.request.http.body.dry_run_policies"
    encrypt = true
  }

  path {
    name    = "log.response.http.body.received"
    encrypt = true
  }

  path {
    name    = "log.response.http.body.sent"
    encrypt = true
  }

  path {
    name    = "log.response.http.body.dry_run_policies"
    encrypt = true
  }
}

received and sent hold the body before and after Formal policies run. dry_run_policies holds the body that dry-run policies would produce.

LLM Content

LLM content appears in two places. log.llm is the top-level view of the whole exchange. log.request.http.llm holds the LLM fields parsed from the HTTP request. Encrypt both to cover every copy:

resource "formal_log_schema" "encrypt_llm_content" {
  name              = "encrypt-llm-content"
  encryption_key_id = formal_encryption_key.logs_key.id
  scope_cel         = "true"

  # Top-level LLM view
  path {
    name    = "log.llm.messages.content_parts.text"
    encrypt = true
  }

  path {
    name    = "log.llm.messages.content_parts.input"
    encrypt = true
  }

  path {
    name    = "log.llm.response_messages.content_parts.text"
    encrypt = true
  }

  path {
    name    = "log.llm.response_messages.content_parts.input"
    encrypt = true
  }

  path {
    name    = "log.llm.tool_calls.input"
    encrypt = true
  }

  path {
    name    = "log.llm.events.data"
    encrypt = true
  }

  # LLM fields nested under the HTTP request
  path {
    name    = "log.request.http.llm.messages.content_parts.text"
    encrypt = true
  }

  path {
    name    = "log.request.http.llm.messages.content_parts.input"
    encrypt = true
  }

  path {
    name    = "log.request.http.llm.response_messages.content_parts.text"
    encrypt = true
  }

  path {
    name    = "log.request.http.llm.response_messages.content_parts.input"
    encrypt = true
  }

  path {
    name    = "log.request.http.llm.tool_calls.input"
    encrypt = true
  }

  path {
    name    = "log.request.http.llm.events.data"
    encrypt = true
  }
}

messages holds the prompt the client sent. response_messages holds the model’s reply. content_parts.input holds tool inputs, encrypted as one value. To remove prompts instead, use one drop path on log.llm.messages. Do not combine it with child paths such as log.llm.messages.content_parts.text.

S3 Requests

This schema encrypts the bucket name and object path of S3 requests:

resource "formal_log_schema" "encrypt_s3_requests" {
  name              = "encrypt-s3-requests"
  encryption_key_id = formal_encryption_key.logs_key.id
  scope_cel         = "log.resource.technology == \"s3\""

  path {
    name    = "log.request.s3.bucket_name"
    encrypt = true
  }

  path {
    name    = "log.request.s3.path"
    encrypt = true
  }
}

Exec Streams

This schema encrypts the terminal data of Kubernetes exec sessions:

resource "formal_log_schema" "encrypt_exec_streams" {
  name              = "encrypt-exec-streams"
  encryption_key_id = formal_encryption_key.logs_key.id
  scope_cel         = "log.resource.technology == \"kubernetes\""

  path {
    name    = "log.stream.message.data"
    encrypt = true
  }
}

This path encrypts every stream message, including terminal resize events. Verify: Run terraform apply, then send matching traffic through Formal. Open Logs and inspect the log. Each selected field holds ciphertext instead of plaintext.

Supported Paths

Every path starts with log. The following path families support schema actions:

Path family	Supported actions
`log`	`drop`
`log.session.device.*`	`drop`, `encrypt`, `truncate`
`log.request.query`	`drop`, `strip_sql`, `encrypt_sql`
`log.request.http.*`	`drop`, `encrypt`, `truncate`
`log.request.s3.*`	`drop`, `encrypt`, `truncate`
`log.request.grpc.*`	`drop`, `encrypt`, `truncate`
`log.request.dynamodb.*`	`drop`, `encrypt`, `truncate`
`log.response.datastore.*`	`drop`, `encrypt`, `truncate`
`log.response.http.*`	`drop`, `encrypt`, `truncate`
`log.response.s3.*`	`drop`, `encrypt`, `truncate`
`log.response.mcp.*`	`drop`, `encrypt`, `truncate`
`log.stream.message.*`	`drop`, `encrypt`, `truncate`
`log.llm.*`	`drop`, `encrypt`, `truncate`

encrypt and truncate only support singular string fields. drop can select a supported parent field, string, list, or map. Paths use protobuf field names, not search aliases. For example, use log.request.http.body.received, not request_body.

Path Restrictions

A schema cannot contain both a parent path and its child. For example, you cannot combine log.request.http.body with log.request.http.body.received. Do not configure overlapping paths across separate schemas.

Failure Behavior

Formal clears a selected sensitive field if its encryption action fails. It then continues applying actions to other paths. A failed SQL encryption clears the complete selected query object. A scope evaluation failure skips only that schema. Other matching schemas continue to apply.

Next Steps

Configure Encryption Keys

Policy Input Retention

Configure how long policy evaluation inputs are kept

Getting Started

Example Use Cases

AI Governance

Configuring Formal

Integrations

Configuration

Overview

Configure a Log Schema

Scope Fields

Schema Actions

Encryption Examples

HTTP Bodies

LLM Content

S3 Requests

Exec Streams

Supported Paths

Path Restrictions

Failure Behavior

Next Steps

Configure Encryption Keys

Policy Input Retention

​Overview

​Configure a Log Schema

​Scope Fields

​Schema Actions

​Encryption Examples

​HTTP Bodies

​LLM Content

​S3 Requests

​Exec Streams

​Supported Paths

​Path Restrictions

​Failure Behavior

​Next Steps

Configure Encryption Keys

Policy Input Retention

Overview

Configure a Log Schema

Scope Fields

Schema Actions

Encryption Examples

HTTP Bodies

LLM Content

S3 Requests

Exec Streams

Supported Paths

Path Restrictions

Failure Behavior

Next Steps