Merge pull request #88860 from rachel-msft/auditedits1

ktoliver · web-flow · commit 9ca61e8bb732 · 2019-09-17T15:04:44.000-07:00
Auditedits1
diff --git a/articles/postgresql/TOC.yml b/articles/postgresql/TOC.yml
@@ -104,6 +104,8 @@
         href: concepts-monitoring.md
       - name: Server logs
         href: concepts-server-logs.md
+      - name: Audit logs
+        href: concepts-audit.md
       - name: Query Store
         items:
         - name: Query Store
diff --git a/articles/postgresql/concepts-audit.md b/articles/postgresql/concepts-audit.md
@@ -0,0 +1,85 @@
+---
+title: Audit logging using pgAudit in Azure Database for PostgreSQL - Single Server
+description: Concepts for pgAudit audit logging in Azure Database for PostgreSQL - Single Server.
+author: rachel-msft
+ms.author: raagyema
+ms.service: postgresql
+ms.topic: conceptual
+ms.date: 09/18/2019
+---
+
+# Audit logging in Azure Database for PostgreSQL - Single Server
+
+Audit logging of database activities in Azure Database for PostgreSQL - Single Server is available through the PostgreSQL Audit Extension: [pgAudit](https://www.pgaudit.org/). pgAudit provides detailed session and/or object audit logging.
+
+> [!NOTE]
+> pgAudit can be enabled on General Purpose and Memory Optimized servers only.
+
+## Usage considerations
+By default, pgAudit log statements are emitted along with your regular log statements by using Postgres's standard logging facility. In Azure Database for PostgreSQL, these .log files can be downloaded through the Azure portal or the CLI. The maximum storage for the collection of files is 1 GB, and each file is available for a maximum of seven days (the default is three days). This service is a short-term storage option.
+
+Alternatively, you can configure all logs to be emitted to Azure Monitor's diagnostic log service. If you enable Azure Monitor diagnostic logging, your logs will be automatically sent (in JSON format) to Azure Storage, Event Hubs, and/or Azure Monitor logs, depending on your choice.
+
+Enabling pgAudit generates a large volume of logging on a server, which has an impact on performance and log storage. We recommend that you use the Azure diagnostic log service, which offers longer-term storage options, as well as analysis and alerting features. We recommend that you turn off standard logging to reduce the performance impact of additional logging:
+
+   1. Set the parameter `logging_collector` to OFF. 
+   2. Restart the server to apply this change.
+
+To learn how to set up logging to Azure Storage, Event Hubs, or Azure Monitor logs, visit the diagnostic logs section of the [server logs article](concepts-server-logs.md).
+
+## Installing pgAudit
+
+To install pgAudit, you need to include it in the server's shared preload libraries. A change to Postgres's `shared_preload_libraries` parameter requires a server restart to take effect. You can change parameters using the [Azure portal](howto-configure-server-parameters-using-portal.md), [Azure CLI](howto-configure-server-parameters-using-cli.md), or [REST API](/rest/api/postgresql/configurations/createorupdate).
+
+Using the [Azure portal](https://portal.azure.com):
+
+   1. Select your Azure Database for PostgreSQL server.
+   2. On the sidebar, select **Server Parameters**.
+   3. Search for the `shared_preload_libraries` parameter.
+   4. Select **pgaudit**.
+   5. Restart the server to apply the change.
+
+   6. Connect to your server using a client (like psql) and enable the pgAudit extension
+      ```SQL
+      CREATE EXTENSION pgaudit;
+      ```
+
+> [!TIP]
+> If you see an error, confirm that you restarted your server after saving `shared_preload_libraries`.
+
+## pgAudit settings
+
+pgAudit allows you to configure session or object audit logging. [Session audit logging](https://github.com/pgaudit/pgaudit/blob/master/README.md#session-audit-logging) emits detailed logs of executed statements. [Object audit logging](https://github.com/pgaudit/pgaudit/blob/master/README.md#object-audit-logging) is audit scoped to specific relations. You can choose to set up one or both types of logging. 
+
+> [!NOTE]
+> pgAudit settings are specified gloabally and cannot be specified at a database or role level.
+
+Once you have [installed pgAudit](#installing-pgaudit), you can configure its parameters to start logging. The [pgAudit documentation](https://github.com/pgaudit/pgaudit/blob/master/README.md#settings) provides the definition of each parameter. Test the parameters first and confirm that you are getting the expected behavior.
+
+> [!NOTE]
+> Setting `pgaudit.log_client` to ON will redirect logs to a client process (like psql) instead of being written to file. This setting should generally be left disabled.
+
+> [!NOTE]
+> `pgaudit.log_level` is only enabled when `pgaudit.log_client` is on. Also, in the Azure portal, there is currently a bug with `pgaudit.log_level`: a combo box is shown, implying that multiple levels can be selected. However, only one level should be selected. 
+
+> [!NOTE]
+> In Azure Database for PostgreSQL, `pgaudit.log` cannot be set using a `-` (minus) sign shortcut as described in the pgAudit documentation. All required statement classes (READ, WRITE etc) should be individually specified.
+
+### Audit log format
+Each audit entry is indicated by `AUDIT:` near the beginning of the log line. The format of the rest of the entry is detailed in the [pgAudit documentation](https://github.com/pgaudit/pgaudit/blob/master/README.md#format).
+
+If you need any other fields to satisfy your audit requirements, use the Postgres parameter `log_line_prefix`. `log_line_prefix` is a string that is output at the beginning of every Postgres log line. For example, the following `log_line_prefix` setting provides timestamp, username, database name, and process ID:
+
+```
+t=%m u=%u db=%d pid=[%p]:
+```
+
+To learn more about `log_line_prefix`, visit the [PostgreSQL documentation](https://www.postgresql.org/docs/current/runtime-config-logging.html#GUC-LOG-LINE-PREFIX).
+
+### Getting started
+To quickly get started, set `pgaudit.log` to `WRITE`, and open your logs to review the output. 
+
+
+## Next steps
+- [Learn about logging in Azure Database for PostgreSQL](concepts-server-logs.md)
+- Learn how to set parameters using the [Azure portal](howto-configure-server-parameters-using-portal.md), [Azure CLI](howto-configure-server-parameters-using-cli.md), or [REST API](/rest/api/postgresql/configurations/createorupdate).
diff --git a/articles/postgresql/concepts-extensions.md b/articles/postgresql/concepts-extensions.md
@@ -5,7 +5,7 @@ author: rachel-msft
 ms.author: raagyema
 ms.service: postgresql
 ms.topic: conceptual
-ms.date: 08/23/2019
+ms.date: 09/10/2019
 ---
 # PostgreSQL extensions in Azure Database for PostgreSQL - Single Server
 PostgreSQL provides the ability to extend the functionality of your database using extensions. Extensions bundle multiple related SQL objects together in a single package that can be loaded or removed from your database with a single command. After being loaded in the database, extensions function like built-in features.
@@ -38,6 +38,7 @@ The following extensions are available in Azure Database for PostgreSQL servers
 > |[isn](https://www.postgresql.org/docs/11/isn.html)                          | 1.2             | data types for international product numbering standards|
 > |[ltree](https://www.postgresql.org/docs/11/ltree.html)                        | 1.1             | data type for hierarchical tree-like structures|
 > |[orafce](https://github.com/orafce/orafce)                       | 3.7             | Functions and operators that emulate a subset of functions and packages from commercial RDBMS|
+> |[pgaudit](https://www.pgaudit.org/)                     | 1.3             | provides auditing functionality|
 > |[pgcrypto](https://www.postgresql.org/docs/11/pgcrypto.html)                     | 1.3             | cryptographic functions|
 > |[pgrouting](https://pgrouting.org/)                    | 2.6.2           | pgRouting Extension|
 > |[pgrowlocks](https://www.postgresql.org/docs/11/pgrowlocks.html)                   | 1.2             | show row-level locking information|
@@ -82,6 +83,7 @@ The following extensions are available in Azure Database for PostgreSQL servers
 > |[isn](https://www.postgresql.org/docs/10/isn.html)                          | 1.1             | data types for international product numbering standards|
 > |[ltree](https://www.postgresql.org/docs/10/ltree.html)                        | 1.1             | data type for hierarchical tree-like structures|
 > |[orafce](https://github.com/orafce/orafce)                       | 3.7             | Functions and operators that emulate a subset of functions and packages from commercial RDBMS|
+> |[pgaudit](https://www.pgaudit.org/)                     | 1.3             | provides auditing functionality|
 > |[pgcrypto](https://www.postgresql.org/docs/10/pgcrypto.html)                     | 1.3             | cryptographic functions|
 > |[pgrouting](https://pgrouting.org/)                    | 2.5.2           | pgRouting Extension|
 > |[pgrowlocks](https://www.postgresql.org/docs/10/pgrowlocks.html)                   | 1.2             | show row-level locking information|
@@ -127,6 +129,7 @@ The following extensions are available in Azure Database for PostgreSQL servers
 > |[isn](https://www.postgresql.org/docs/9.6/isn.html)                          | 1.1             | data types for international product numbering standards|
 > |[ltree](https://www.postgresql.org/docs/9.6/ltree.html)                        | 1.1             | data type for hierarchical tree-like structures|
 > |[orafce](https://github.com/orafce/orafce)                       | 3.7             | Functions and operators that emulate a subset of functions and packages from commercial RDBMS|
+> |[pgaudit](https://www.pgaudit.org/)                     | 1.3             | provides auditing functionality|
 > |[pgcrypto](https://www.postgresql.org/docs/9.6/pgcrypto.html)                     | 1.3             | cryptographic functions|
 > |[pgrouting](https://pgrouting.org/)                    | 2.3.2           | pgRouting Extension|
 > |[pgrowlocks](https://www.postgresql.org/docs/9.6/pgrowlocks.html)                   | 1.2             | show row-level locking information|
@@ -172,6 +175,7 @@ The following extensions are available in Azure Database for PostgreSQL servers
 > |[isn](https://www.postgresql.org/docs/9.5/isn.html)                          | 1.0             | data types for international product numbering standards|
 > |[ltree](https://www.postgresql.org/docs/9.5/ltree.html)                        | 1.0             | data type for hierarchical tree-like structures|
 > |[orafce](https://github.com/orafce/orafce)                       | 3.7             | Functions and operators that emulate a subset of functions and packages from commercial RDBMS|
+> |[pgaudit](https://www.pgaudit.org/)                     | 1.3             | provides auditing functionality|
 > |[pgcrypto](https://www.postgresql.org/docs/9.5/pgcrypto.html)                     | 1.2             | cryptographic functions|
 > |[pgrouting](https://pgrouting.org/)                    | 2.3.0           | pgRouting Extension|
 > |[pgrowlocks](https://www.postgresql.org/docs/9.5/pgrowlocks.html)                   | 1.1             | show row-level locking information|
@@ -207,6 +211,9 @@ Currently, outbound connections from Azure Database for PostgreSQL are not suppo
 If you are planning to use `uuid_generate_v4()` from the uuid-ossp extension, consider comparing with `gen_random_uuid()` from the pgcrypto extension for performance benefits.
 
 
+## pgAudit
+The pgAudit extension provides session and object audit logging. To learn how to use this extension in Azure Database for PostgreSQL, visit the [auditing concepts article](concepts-audit.md). 
+
 ## TimescaleDB
 TimescaleDB is a time-series database that is packaged as an extension for PostgreSQL. TimescaleDB provides time-oriented analytical functions, optimizations, and scales Postgres for time-series workloads.
 
diff --git a/articles/postgresql/concepts-server-logs.md b/articles/postgresql/concepts-server-logs.md
@@ -5,7 +5,7 @@ author: rachel-msft
 ms.author: raagyema
 ms.service: postgresql
 ms.topic: conceptual
-ms.date: 5/6/2019
+ms.date: 09/18/2019
 ---
 # Server logs in Azure Database for PostgreSQL - Single Server
 Azure Database for PostgreSQL generates query and error logs. Query and error logs can be used to identify, troubleshoot, and repair configuration errors and suboptimal performance. (Access to transaction logs is not included). 
@@ -22,12 +22,21 @@ If you've enabled logs, you can access them from the Azure Database for PostgreS
 
 
 ## Diagnostic logs
-Azure Database for PostgreSQL is integrated with Azure Monitor Diagnostic Logs. Once you have enabled logs on your PostgreSQL server, you can choose to have them emitted to [Azure Monitor logs](../azure-monitor/log-query/log-query-overview.md), Event Hubs, or Azure Storage. To learn more about how to enable diagnostic logs, see the how-to section of the [diagnostic logs documentation](../azure-monitor/platform/diagnostic-logs-overview.md). 
+Azure Database for PostgreSQL is integrated with Azure Monitor Diagnostic Logs. Once you have enabled logs on your PostgreSQL server, you can choose to have them emitted to [Azure Monitor logs](../azure-monitor/log-query/log-query-overview.md), Event Hubs, or Azure Storage. 
 
 > [!IMPORTANT]
 > This diagnostic feature for server logs is only available in the General Purpose and Memory Optimized [pricing tiers](concepts-pricing-tiers.md).
 
-The following table describes what's in each log. Depending on the output endpoint you choose, the fields included and the order in which they appear may vary. 
+To enable Diagnostic logs using the Azure portal:
+
+   1. In the portal, go to *Diagnostic Settings* in the navigation menu of your Postgres server.
+   2. Select *Add Diagnostic Setting*.
+   3. Name this setting. 
+   4. Select your preferred downstream location (storage account, event hub, log analytics). 
+   5. Select the data types you want.
+   6. Save your setting.
+
+The following table describes what is in each log. Depending on the output endpoint you choose, the fields included and the order in which they appear may vary. 
 
 |**Field** | **Description** |
 |---|---|
@@ -52,6 +61,9 @@ The following table describes what's in each log. Depending on the output endpoi
 | DatatypeName | Name of the datatype (if applicable) |
 | LogicalServerName | Name of the server | 
 | _ResourceId | Resource URI |
+| Prefix | Log line's prefix |
+
+
 
 ## Next steps
 - Learn more about accessing logs from the [Azure portal](howto-configure-server-logs-in-portal.md) or [Azure CLI](howto-configure-server-logs-using-cli.md).
