New Logging Features: Syslog and Restful Support

docs/Getting-Started/Migrating/0X-to-1X.md

@@ -154,7 +154,7 @@ Request and Error logging are inbuilt logging types that can be enabled using [`
 | [`Disable-PodeRequestLogging`](../../../Functions/Logging/Disable-PodeRequestLogging) |
 | [`Disable-PodeErrorLogging`](../../../Functions/Logging/Disable-PodeErrorLogging) |
 | [`Remove-PodeLogger`](../../../Functions/Logging/Remove-PodeLogger) |
-| [`Clear-PodeLoggers`](../../../Functions/Logging/Clear-PodeLoggers) |
+| [`Clear-PodeLogger`](../../../Functions/Logging/Clear-PodeLogger) |
 
 ### Writing Logs
 

docs/Tutorials/Configuration.md

@@ -79,6 +79,8 @@ A "path" like `Server.Ssl.Protocols` looks like the below in the file:
 | Server.FileMonitor               | Defines configuration for restarting the server based on file updates       | [link](../Restarting/Types/FileMonitoring)                              |
 | Server.ReceiveTimeout            | Define the amount of time a Receive method call will block waiting for data | [link](../Endpoints/Basic/StaticContent/#server-timeout)                |
 | Server.DefaultFolders            | Set the Default Folders paths                                               | [link](../Routes/Utilities/StaticContent/#changing-the-default-folders) |
+| Server.Logging.QueueLimit        | Set the maximum number of logs allowed in the queue                         | [link](../Logging/Overview)                                             |
+| Server.Logging.Masking.Patterns  | Regular expressions congiguration to mask sensitive logs information        | [link](../Logging/Overview)                                             |
 | Web.OpenApi.DefaultDefinitionTag | Define the primary tag name for OpenAPI ( `default` is the default)         | [link](../OpenAPI/Overview)                                             |
 | Web.OpenApi.UsePodeYamlInternal  | Force the use of the internal YAML converter (`False` is the default)       |                                                                         |
 | Web.Static.ValidateLast          | Changes the way routes are processed.                                       | [link](../Routes/Utilities/StaticContent)                               |

docs/Tutorials/Logging/Methods/Custom.md

@@ -1,35 +1,76 @@
 # Custom
 
-Sometimes you don't want to log to a file, or the terminal; instead you want to log to something better, like LogStash, Splunk, Athena, or any other central logging platform. Although Pode doesn't have these inbuilt (yet!) it is possible to create a custom logging method, where you define a ScriptBlock with logic to send logs to these platforms.
+Sometimes you may want to log to platforms other than a file or the terminal, such as LogStash, Splunk, Athena, or other central logging platforms. Although Pode doesn't have these integrations built-in (yet!), it is possible to create a custom logging method by defining a ScriptBlock with the logic to send logs to these platforms.
 
-These custom method can be used for any log type - Requests, Error, or Custom.
+Custom methods can be used for any log type: Requests, Error, or Custom.
 
-The ScriptBlock you create will be supplied two arguments:
+The ScriptBlock you create will receive two arguments:
 
-1. The item to be logged. This could be a string (from Requests/Errors), or any custom type.
-2. The options you supplied on [`New-PodeLoggingMethod`](../../../../Functions/Logging/New-PodeLoggingMethod).
+1. The item to be logged. This could be a string (from Requests/Errors) or any custom type.
+
+2. The options you supplied to [`New-PodeLoggingMethod`](../../../../Functions/Logging/New-PodeLoggingMethod).
+
+Additionally, custom logging methods can be run in their own runspace by using the `-UseRunspace` parameter, ensuring isolation and efficiency.
 
 ## Examples
 
 ### Send to S3 Bucket
 
-This example will take whatever item is supplied to it, convert it to a string, and then send it off to some S3 bucket in AWS. In this case, it will be logging Requests:
+This example takes the supplied item, converts it to a string, and sends it to an S3 bucket in AWS. In this case, it will log Requests:
 
+#### Legacy (No Runspace)
 ```powershell
 $s3_options = @{
     AccessKey = $AccessKey
     SecretKey = $SecretKey
 }
 
-$s3_logging = New-PodeLoggingType -Custom -ArgumentList $s3_options -ScriptBlock {
+$s3_logging = New-PodeLoggingMethod -Custom -ArgumentList $s3_options -ScriptBlock {
     param($item, $s3_opts)
 
-    Write-S3Object `
-        -BucketName '<name>' `
-        -Content $item.ToString() `
-        -AccessKey $s3_opts.AccessKey `
+    Write-S3Object \`
+        -BucketName '<name>' \`
+        -Content $item.ToString() \`
+        -AccessKey $s3_opts.AccessKey \`
         -SecretKey $s3_opts.SecretKey
 }
+$s3_logging | Enable-PodeRequestLogging
+```
+
 
+#### With Runspace
+
+```powershell
+$s3_options = @{
+    AccessKey = $AccessKey
+    SecretKey = $SecretKey
+}
+
+$s3_logging = New-PodeLoggingMethod -Custom -UseRunspace -CustomOptions $s3_options -ScriptBlock {
+    # No param() allowed here
+    Write-S3Object \`
+        -BucketName '<name>' \`
+        -Content $Item.ToString() \`
+        -AccessKey $Options.AccessKey \`
+        -SecretKey $Options.SecretKey
+}
 $s3_logging | Enable-PodeRequestLogging
 ```
+
+
+In this example, the `-UseRunspace` parameter ensures that the custom logging method runs in its own runspace, providing better isolation and performance.
+
+##### Variable available inside the ScriptBlock
+
+| Variable                | Type                          | Description                                      |
+| ----------------------- | ----------------------------- | ------------------------------------------------ |
+| Item                    | string                        | Log message content                              |
+| Options                 | hashtable                     | The options supplied to the logging method       |
+| Options.FailureAction   | string (Ignore, Report, Halt) | Defines the behavior in case of failure.         |
+| Options.DataFormat      | string                        | The date format to use for the log entries.      |
+| Options.AsUTC           | boolean                       | the time is logged in UTC instead of local time. |
+| Options.<CustomOptions> | PSObject                      | Any key passed using `-CustomOptions` parameter  |
+| RawItem                 | hashtable                     | Log message in raw format                        |
+
+
+By leveraging custom logging methods, you can extend Pode's logging capabilities to integrate with a wide range of external platforms, providing flexibility and control over your logging strategy.

docs/Tutorials/Logging/Methods/File.md

@@ -39,3 +39,42 @@ By default Pode puts all logs in the `./logs` directory. You can use a custom pa
 ```powershell
 New-PodeLoggingMethod -File -Name 'requests' -Path 'E:/logs' | Enable-PodeRequestLogging
 ```
+
+### Format
+
+The Format parameter allows you to specify the format of the log entries. Available options are:
+
+- RFC3164
+- RFC5424
+- Simple
+- Default (default option)
+
+The Simple format uses the following structure: timestamp level source message. The Default format uses the legacy Pode format.
+
+```powershell
+New-PodeLoggingMethod -File -Name 'requests' -Format 'Simple' | Enable-PodeRequestLogging
+```
+A log entry using the Simple format might look like this:
+
+```arduino
+2024-08-01T12:00:00Z INFO MyApp "Request received"
+```
+
+### Custom Separator
+When using the Simple format, you can specify a custom separator for log entries:
+
+```powershell
+New-PodeLoggingMethod -File -Name 'requests' -Format 'Simple' -Separator ',' | Enable-PodeRequestLogging
+```
+
+A log entry using the Simple format with a comma separator might look like this:
+```arduino
+2024-08-01T12:00:00Z,INFO,MyApp,"Request received"
+```
+
+### Maximum Log Entry Length
+The MaxLength parameter sets the maximum length of log entries. The default value is -1, which means no limit.
+
+```powershell
+New-PodeLoggingMethod -File -Name 'requests' -MaxLength 500 | Enable-PodeRequestLogging
+```

docs/Tutorials/Logging/Methods/Syslog.md

@@ -0,0 +1,56 @@
+
+# Syslog
+
+Pode supports logging items to a Syslog server using the inbuilt Syslog logging method. This method allows you to define various parameters such as the Syslog server address, port, transport protocol, and more. The logging method will convert any item to a string and send it to the configured Syslog server.
+
+By default, Pode will use UDP as the transport protocol and RFC5424 as the Syslog protocol. You can customize these settings based on your Syslog server requirements.
+
+## Examples
+
+### Basic
+
+The following example will setup the Syslog logging method for logging requests:
+
+```powershell
+New-PodeLoggingMethod -Syslog -Server '192.168.1.1' | Enable-PodeRequestLogging
+```
+
+### Custom Port
+
+The following example will configure Syslog logging to use a custom port. The default port is 514, but you can specify a different port if needed:
+
+```powershell
+New-PodeLoggingMethod -Syslog -Server '192.168.1.1' -Port 1514 | Enable-PodeRequestLogging
+```
+
+### Secure Connection with TLS
+
+The following example will configure Syslog logging to use TLS for a secure connection. You can also specify the TLS protocol version to use:
+
+```powershell
+New-PodeLoggingMethod -Syslog -Server '192.168.1.1' -Transport 'TLS' -TlsProtocol 'TLS1.2' | Enable-PodeRequestLogging
+```
+
+### Custom Syslog Protocol
+
+The following example will configure Syslog logging to use a different Syslog protocol. The default protocol is RFC5424, but you can specify RFC3164 if needed:
+
+```powershell
+New-PodeLoggingMethod -Syslog -Server '192.168.1.1' -SyslogProtocol 'RFC3164' | Enable-PodeRequestLogging
+```
+
+### Skip Certificate Validation
+
+The following example will configure Syslog logging to skip certificate validation for TLS connections. This is useful for testing purposes but not recommended for production environments:
+
+```powershell
+New-PodeLoggingMethod -Syslog -Server '192.168.1.1' -Transport 'TLS' -SkipCertificateCheck | Enable-PodeRequestLogging
+```
+
+### Custom Encoding
+
+The following example will configure Syslog logging to use a different encoding for the Syslog messages. The default encoding is UTF8:
+
+```powershell
+New-PodeLoggingMethod -Syslog -Server '192.168.1.1' -Encoding 'ASCII' | Enable-PodeRequestLogging
+```

docs/Tutorials/Logging/Overview.md

@@ -1,15 +1,17 @@
 # Overview
 
-There are two aspects to logging in Pode: Methods and Types.
+Logging in Pode consists of two main components: Methods and Types.
 
-* Methods define how log items should be recorded, such as to a file, terminal, or event viewer.
-* Types define how items to log are transformed, and what should be supplied to the Method.
+- **Methods**: Define how log items should be recorded, such as to a file, terminal, or event viewer. Each logging method operates in its own runspace, providing isolation and efficiency. The exception to this is the Custom method, which by default runs in the same runspace as the log dispatcher unless the `-UseRunspace` parameter is specified.
 
-For example when you supply an Exception to [`Write-PodeErrorLog`](../../../Functions/Logging/Write-PodeErrorLog), this Exception is first supplied to Pode's inbuilt Error logging type. This type transforms any Exception (or Error Record) into a string which can then be supplied to the File logging method.
+- **Types**: Define how log items are transformed and what data should be supplied to the Method.
 
-In Pode you can use File, Terminal, Event Viewer, or a Custom method. As well as Request, Error, or a Custom type.
+When you supply an Exception to [`Write-PodeErrorLog`](../../../Functions/Logging/Write-PodeErrorLog), the Exception is first processed by Pode's built-in Error logging type. This type transforms the Exception (or Error Record) into a string format, which can then be recorded by the logging method (e.g., File).
+
+Pode supports various logging methods, including File, Terminal, Event Viewer, Syslog, Restful, or Custom methods. Additionally, you can utilize different logging types such as Request, Error, or Custom types.
+
+This flexibility allows you to create a custom logging method that can output logs to various platforms, such as an S3 bucket, Splunk, or any other logging service.
 
-This means you could write a logging method to output to an S3 bucket, Splunk, or any other logging platform.
 
 ## Masking Values
 
@@ -109,3 +111,50 @@ Instead of writing logs one-by-one, the above will keep transformed log items in
 This means that the method's scriptblock will receive an array of items, rather than a single item.
 
 You can also sent a `-BatchTimeout` value, in seconds, so that if your batch size it 10 but only 5 log items are added, then after the timeout value the logs items will be sent to your method.
+
+
+
+## Configuring Failure Actions for Log Writing
+
+Defines the behavior in case of failure to write a log. This can happen if the disk is full, the Syslog server is offline, or if the number of logs in the queue reaches the maximum allowed. The options are:
+- **Ignore** : Does nothing and continues execution. **(Default)**
+- **Report** : Writes a message to the console for any failure.
+- **Halt** : Writes a message to the console and shuts down the Pode server.
+
+```powershell
+New-PodeLoggingMethod -File -Path './logs' -Name 'errors' -FailureAction 'Report' | Enable-PodeRequestLogging
+```
+
+## QueueLimit
+Defines the maximum number of logs allowed in the queue before throwing an event.
+The default value is 500.  The exception is handled based on the `-FailureAction` parameter.
+
+```powershell
+@{
+    Server = @{
+        Logging = @{
+            QueueLimit = 1000
+        }
+    }
+}
+```
+
+## DataFormat
+The date format to use for the log entries. The default format is `'dd/MMM/yyyy:HH:mm:ss zzz'`.
+
+```powershell
+New-PodeLoggingMethod -File -Path './logs' -Name 'access' -DataFormat 'yyyy-MM-dd HH:mm:ss' | Enable-PodeErrorLogging
+```
+
+## ISO8601
+If set, the date format will be ISO 8601 compliant (equivalent to `-DataFormat 'yyyy-MM-ddTHH:mm:ssK'`). This parameter is mutually exclusive with DataFormat.
+
+```powershell
+New-PodeLoggingMethod -File -Path './logs' -Name 'access' -ISO8601 | Enable-PodeErrorLogging
+```
+
+## AsUTC
+If set, the time will be logged in UTC instead of local time.
+
+```powershell
+New-PodeLoggingMethod -File -Path './logs' -Name 'access' -AsUTC -ISO8601 | Enable-PodeErrorLogging

docs/Tutorials/Logging/Types/General.md

@@ -0,0 +1,70 @@
+
+# General Logging
+
+Pode supports general logging, allowing you to define custom logging methods and log levels. This feature enables you to write logs based on specified methods, ensuring flexibility and control over logging outputs.
+
+To enable general logging, use the `Enable-PodeGeneralLogging` function. This function takes a hashtable defining the logging method, including a ScriptBlock for log output. You can specify various log levels to be enabled, such as Error, Emergency, Alert, Critical, Warning, Notice, Informational, Info, Verbose, and Debug.
+
+## Enabling General Logging
+
+To enable general logging, use the `Enable-PodeGeneralLogging` function, supplying the necessary parameters:
+
+- `Method`: The hashtable defining the logging method, including the ScriptBlock for log output.
+- `Levels`: An array of log levels to be enabled for the logging method (default includes Error, Emergency, Alert, Critical, Warning, Notice, Informational, Info, Verbose, Debug).
+- `Name`: The name of the logging method to be enabled.
+- `Raw`: If set, the raw log data will be included in the logging output.
+
+### Example
+
+```powershell
+$method = New-PodeLoggingMethod -syslog -Server 127.0.0.1 -Transport UDP
+$method | Enable-PodeGeneralLogging -Name "mysyslog"
+```
+
+## Disabling General Logging
+
+To disable a general logging method, use the `Disable-PodeGeneralLogging` function with the `Name` parameter:
+
+### Example
+
+```powershell
+Disable-PodeGeneralLogging -Name 'mysyslog'
+```
+
+With these functions, Pode ensures robust and customizable logging capabilities, allowing you to manage logs effectively based on your specific requirements.
+
+## Writing to General Logs
+
+Pode allows you to write logs to configured custom or inbuilt logging methods using the `Write-PodeLog` function. This function supports both custom and inbuilt logging methods, enabling structured logging with various log levels and messages.
+
+### Writing to General Logs
+
+To write logs, you can use the `Write-PodeLog` function with different parameters to specify the logging method, log level, message, and other details.
+
+#### Example Usage
+
+##### Logging an Object
+
+To write an object to a configured logging method:
+
+```powershell
+$logItem = @{
+    Date     = [datetime]::Now
+    Level    = 'Informational'
+    Server   = 'MyServer'
+    Category = 'General'
+    Message  = 'This is a log message'
+    StackTrace = ''
+}
+$logItem | Write-PodeLog -Name 'mysyslog'
+```
+
+##### Logging with Custom Levels and Messages
+
+To log a custom message with a specific log level:
+
+```powershell
+Write-PodeLog -Name 'mysyslog' -Level 'Error' -Message 'An error occurred.' -Tag 'MyApp'
+```
+
+In these examples, `Write-PodeLog` is used to write structured log items or custom messages to the specified logging methods, helping you maintain organized and detailed logs.

docs/Tutorials/Logging/Types/Requests.md

@@ -6,7 +6,10 @@ Pode has inbuilt Request logging logic, that will parse and return a valid log i
 
 To enable and use the Request logging you use the [`Enable-PodeRequestLogging`](../../../../Functions/Logging/Enable-PodeRequestLogging) function, supplying a logging method from [`New-PodeLoggingMethod`](../../../../Functions/Logging/New-PodeLoggingMethod).
 
-The Request type logic will format a string using [Combined Log Format](https://httpd.apache.org/docs/1.3/logs.html#combined). This string is then supplied to the logging method's scriptblock. If you're using a Custom logging method and want the raw hashtable instead, you can supply `-Raw` to [`Enable-PodeRequestLogging`](../../../../Functions/Logging/Enable-PodeRequestLogging).
+The Request type logic will format a string using [Combined Log Format](https://httpd.apache.org/docs/1.3/logs.html#combined).
+This string is then supplied to the logging method's scriptblock. You can customize the log format using the `-LogFormat` parameter with options like `Extended`, `Common`, `Combined`, and `JSON`.
+
+If you're using a Custom logging method and want the raw hashtable instead, you can supply `-Raw` to [`Enable-PodeRequestLogging`](../../../../Functions/Logging/Enable-PodeRequestLogging).
 
 ## Examples
 
@@ -18,6 +21,23 @@ The following example simply enables Request logging, and will output all items
 New-PodeLoggingMethod -Terminal | Enable-PodeRequestLogging
 ```
 
+### Log Format
+
+#### Extended Log Format
+The following example enables Request logging using the Extended Log Format:
+
+```powershell
+New-PodeLoggingMethod -File -Path './logs' -Name 'requests' | Enable-PodeRequestLogging -LogFormat 'Extended'
+```
+
+#### JSON Format
+The following example enables Request logging using JSON Format:
+
+```powershell
+New-PodeLoggingMethod -File -Path './logs' -Name 'requests' | Enable-PodeRequestLogging -LogFormat 'Json'
+```
+
+
 ### Using Raw Item
 
 The following example uses a Custom logging method, and sets Request logging to return and supply the raw hashtable to the Custom method's scriptblock. The Custom method simply logs the Host an StatusCode to the terminal (but could be to something like an S3 bucket):
@@ -70,4 +90,4 @@ The raw Request hashtable that will be supplied to any Custom logging methods wi
         Size = '9001'
     }
 }
-```
+```