Logs in Azure HorizonDB

Azure HorizonDB provides resource logs for PostgreSQL events, session activity, query execution, waits, autovacuum, and transaction-ID usage. You can send these logs to a Log Analytics workspace and query them with Kusto Query Language (KQL).

Use logs to troubleshoot database errors and investigate query performance. Compare log records with metrics to identify changes in cluster activity.

Log generation and log routing are separate

To collect logs in a Log Analytics workspace:

  1. Configure the database or collector to generate the records you need.
  2. Create a diagnostic setting to send the corresponding log category to your workspace.

Configure statement logging, query store, and optional collectors separately from diagnostic settings. A diagnostic setting controls where logs are sent; it doesn't enable the collection of records in the database.

Platform metrics are available without a diagnostic setting. The subscription's Activity log records Azure management operations, while server logs record PostgreSQL events.

Supported log categories

Each HorizonDB log category uses a resource-specific table with the same name. The portal uses friendly labels, such as HorizonDB server logs, for these categories.

Diagnostic category and Log Analytics table Purpose Generation considerations
HorizonDBServerLogs PostgreSQL server events, including eligible errors and configured logging output. PostgreSQL logging parameters determine which events are emitted.
HorizonDBPgStatActivitySessions Snapshots of PostgreSQL sessions, including state, waits, and node context. The table reference describes a five-minute collection interval. Review database/activity collection settings.
HorizonDBQueryStoreRuntimeStats Query execution counts, durations, and resource statistics. Query store must capture the relevant workload.
HorizonDBQueryStoreWaitsStats Sampled query wait statistics. Review query store capture and wait-sampling configuration.
HorizonDBQueryStoreQueryText Query text captured by query store. Enable only when needed and approved; SQL text can contain sensitive data.
HorizonDBAutovacuumStats Autovacuum and schema-level statistics. Review autovacuum collection settings and the applicable collection interval.
HorizonDBTransactionsStats Remaining transaction and multitransaction identifiers by database. Requires relevant statistics to be generated; it isn't a transaction-log or WAL download.

For the complete category reference and table schemas, see Supported logs and Log Analytics tables for HorizonDB. Use the categories returned for your cluster when automating configuration.

Category groups

You can select individual log categories or a category group. Both audit and allLogs currently include all seven HorizonDB log categories. This means that audit includes query text and performance statistics as well as server events.

Select individual categories to collect only the data you need. Group membership can change, so review the included categories and their collection costs before enabling a group. Configure the required database collectors separately.

Configure PostgreSQL logging

Use PostgreSQL logging parameters to control which events are written to server logs. The following table lists common parameters and their documented defaults.

Parameter Use Documented default
log_min_messages Choose the minimum message level written to server logs. warning
log_min_error_statement Include statements associated with errors at or above a selected level. error
log_min_duration_statement Log statements whose execution reaches a duration threshold, in milliseconds. -1 disables duration-based statement logging. -1
log_statement Choose statement classes to log. none
log_connections Log connection events. on
log_disconnections Log session termination events. on
log_lock_waits Log qualifying lock waits. off
log_autovacuum_min_duration Log autovacuum activity that reaches a duration threshold. -1 disables this output. -1

Check your compute pool's effective parameter values before making changes. For details about each parameter, see when to log and what to log.

To change pool-level parameters, use parameter groups. Default parameter groups are read-only. If the pool uses a default group, create a custom parameter group and assign it to the compute pool. Custom parameter groups can be updated in place. Preserve existing overrides and review the effect on every compute pool assigned to the custom group before saving changes.

Warning

Verbose statement logging can increase workload overhead and log-ingestion costs. SQL statements, parameters, error details, and query text can contain personal data, credentials, or other sensitive information. Enable statement and query-text collection only when you need that data for your investigation.

Optional collectors and query store

  • For database and activity statistics, check the target compute pool's effective metrics.collector_database_activity value and set it to on through its parameter group if it's off.
  • Use metrics.autovacuum_diagnostics for table-statistics collection. Check the compute pool's effective value and the metrics parameter reference before changing it.
  • Use pg_qs.query_capture_mode to select which queries the query store captures. none disables new query capture. top and all select different capture scopes.
  • Use pgms_wait_sampling.query_capture_mode to configure query store wait sampling. You must also enable query store capture to collect query waits.

Check the compute pool's effective values rather than assuming a query capture default. Set the required values through the parameter-group workflow described in Configure PostgreSQL logging. Selecting a diagnostic category doesn't change these values.

Query store retention in the database and log retention in Log Analytics are configured separately. Azure Monitor ingestion and retention charges are separate from the query store feature.

Route and access logs

Configure diagnostic settings on the cluster to send the required log categories to your destination. For portal instructions, destination access, and query examples, see Configure and access logs.

Resource and node context

Resource-specific tables include _ResourceId and, where applicable, Pool, Node, and Role. Use these fields to filter records by cluster and node when a workspace contains logs from multiple sources. Role values include ReadWrite, ReadOnly, and Unknown.

TimeGenerated is a UTC timestamp. Some tables also have collection or aggregation-window timestamps. Use the timestamp that corresponds to the data you want to analyze. For example, session records describe the sampled session state at collection time, not every state change between samples.

For server logs, common fields include ErrorLevel, SqlErrorCode, Message, and ProcessId. Check the table schema when writing or updating queries.

Access control

Managing the cluster, configuring a diagnostic setting, and reading destination logs are separate permissions.

  • Grant diagnostic-settings management permissions at the cluster scope and appropriate access to the selected destination.
  • Grant log-query access according to the workspace's access-control mode, resource-context permissions, and any table-level restrictions.
  • PostgreSQL credentials or the Reader role on a cluster don't by themselves grant access to all records in a shared workspace.
  • For other destinations, apply the destination's access-control requirements.

See Manage access to Log Analytics workspaces.

Retention and cost

Log Analytics ingestion, retention, and some query or export operations can incur charges, depending on the table plan and configuration. Configure retention at the workspace or table level. Log retention is configured separately from platform-metric retention.

If you send logs to Azure Storage, use an appropriate lifecycle policy. For logs sent to Event Hubs, configure retention and the downstream consumer's data lifecycle.

Collect only the categories you need. Remove temporary diagnostic settings when an investigation ends. Removing a diagnostic setting stops future routing but doesn't delete data already retained at the destination.

See Azure Monitor pricing and Log Analytics data retention.

Limitations and troubleshooting

  • A log table might not appear until it receives its first records. Allow for the source collection interval and ingestion delay.
  • It can take up to 90 minutes for logs to appear after you create a diagnostic setting. A query also returns no records if the source didn't generate events in the selected time range.
  • Check the selected categories, destination workspace, query time range, and _ResourceId filter if expected records are missing. Review the relevant collector and query store settings for optional categories.
  • Use the HorizonDB resource-specific table names in this article.
  • Selecting the audit category group controls routing; it doesn't enable database auditing.

For general routing and destination requirements, see Diagnostic settings in Azure Monitor.