Skip to main content

​
Overview

Every query, command, and API call that flows through Formal Connectors is logged and stored for auditing, compliance, and security analysis. Formal’s log system provides comprehensive visibility into data access across your organization. Formal logs dashboard

​
What Gets Logged

Database Queries

Full SQL/NoSQL queries, execution time, rows affected

API Calls

HTTP requests, headers, request/response bodies, status codes

SSH Commands

Every command executed in SSH sessions

Kubernetes Exec

kubectl exec sessions and commands

​
Log Enrichment

Formal automatically enriches each log entry with contextual information:
FieldDescription
TimestampWhen the query/command was executed
UserFormal user who made the request
End-UserActual end-user (for BI tool queries)
ResourceTarget database, API, or server
ConnectorWhich Connector processed the request
Session IDAssociated session identifier
Policy ActionsAny policy enforcement (mask, block, filter, etc.)
Client IPSource IP address
ApplicationClient application (psql, Looker, etc.)
DurationQuery execution time
Rows AffectedNumber of records touched

​
Accessing Logs

Navigate to Logs in the Formal console to view all logged activity.

​
Viewing Modes

  • Logs Mode
  • Aggregation Mode
Default view that displays all log entries chronologically. - See individual queries/commands - Click any row to open detailed panel - Filter and search across all fields - Export to CSV

​
Log Details Panel

Click any log entry to view comprehensive details: Log details panel

​
What’s Included

  • Full Query/Command: Complete text of what was executed
  • User Context: User, end-user, groups, email
  • Resource Information: Database, hostname, port, technology
  • Policy Evaluation: Which policies evaluated, actions taken, reasons
  • Performance Metrics: Duration, rows affected, data transferred
  • Network Information: Client IP, application, connection details
  • Session Link: Jump to associated session recording
Formal uses Quickwit query engine for powerful search capabilities.

​
Basic Filters

Use the sidebar to filter by:
  • Connector
  • Resource
  • User
  • End-user
  • Group
  • Technology (postgres, ssh, http, etc.)
  • Time range
Write Quickwit queries for complex searches: 
# Find all queries by user Alice
user:alice@example.com

# Find queries that triggered policies
policy_actions:* AND NOT policy_actions:allow

# Find slow queries (>1 second)
duration_ms:[1000 TO *]

# Find DELETE statements in production
query:"DELETE" AND resource:production-postgres

# Find SSH commands containing "sudo"
command:"sudo" AND technology:ssh

# Find queries accessing specific table
query:"FROM users" OR query:"JOIN users"

# Complex: Find non-admin users accessing PII tables
user.groups:(NOT admin) AND (table:"users_pii" OR table:"customers_sensitive")

# Time-based: Queries in the last 24 hours
timestamp:[now-24h TO now]

# Failed authentications
status:denied AND policy_action:block_authentication

​
Query Templates

Formal provides pre-built query templates:
TemplateDescriptionQuery
Formal UsersSystem-generated usersuser.type:formal
Native UsersQueries using native credentialsuser_type:native
Triggered PoliciesLogs with policy enforcementpolicy_actions:* AND NOT policy_actions:allow
Datastore QueriesDatabase queriestechnology:(postgres OR mysql OR mongodb OR snowflake)
HTTP RequestsAPI callstechnology:http
S3 RequestsS3 operationstechnology:s3
Encrypted RequestsQueries with encryptionrequest.query.encrypted:true
SSH SessionsTerminal sessionstechnology:ssh

​
Query Library

Query actions Access your queries by clicking Queries in the toolbar. The Query Library provides three tabs:

​
Recent Queries

View your search history:
  1. Click Queries to open the Query Library
  2. View the Recent tab (default)
  3. Select any previous query to re-run it
  4. History persists across sessions

​
Saved Queries

Save frequently used queries for quick access:
  1. Create your query with filters or search terms
  2. Click Save in the toolbar
  3. Name your query
  4. Access later from Queries → Saved tab

​
Template Queries

Pre-built queries for common use cases. Click Queries → Templates to browse available templates (see Query Templates above)

​
Exporting Logs

​
CSV Export

Export search results to CSV for offline analysis:
  1. Apply filters or search query
  2. Click Export to CSV
  3. Download the file

​
SIEM Integration

Forward all logs to external systems:
  • AWS S3: Long-term archive, compliance storage
  • Datadog: Real-time monitoring and alerting
  • Splunk: SIEM integration
  • Elastic: Centralized logging
  • Sumo Logic: Security analytics
See SIEM Integration for setup instructions.

​
Best Practices

Save frequently used searches for compliance, security, or operational monitoring.
Forward logs to your SIEM or data lake for advanced analytics and long-term retention beyond Formal’s console.
Schedule weekly or monthly log reviews to identify unusual patterns, policy gaps, or security incidents.
Leverage aggregation and visualization to spot trends that aren’t obvious in individual log entries.
Regularly review logs where policies blocked or masked data to ensure policies are working as intended.

​
Policy Evaluation Input Retention

Formal can optionally retain the input data that was available to policies during evaluation. This enables policy backtesting - the ability to test new or modified policies against historical access patterns.

​
What Gets Retained

The full input object that is passed to policies at a particular evaluation stage will be retained. Refer to our policies evaluation docs to learn more about what is passed as input.

​
Configuring Retention

Configure retention periods independently for each evaluation stage in your Log Configurations:
  • 0 days (disabled): No policy inputs are retained in the Control Plane
  • 1-30 days: Policy inputs are stored for the specified duration
In addition, you can enable retention at the resource, connector, space, or account level.
Policy evaluation inputs may contain sensitive data depending on your policies. Retention is subject to a maximum of 30 days. Changing retention settings may take a day to take effect.

​
Integration with Policies

Policies can enrich logs with contextual information: 
package formal.v2

import future.keywords.if

post_request := {
  "action": "allow",
  "reason": "Query approved for analytics team",
  "contextual_data": sprintf(
    "Approved query on %s by %s from %s",
    [input.resource.name, input.user.email, input.client_ip_address]
  )
} if {
  "analytics" in input.user.groups
}
The reason and contextual_data fields appear in the log entry, providing audit trail context.

​
Next Steps

Sessions

View active and completed sessions

SIEM Integration

Forward logs to your SIEM