feat(gateway): Solace Log plugin (#2730)

* bootstrap solace log plugin

* Apply suggestions from code review

Co-authored-by: Zachary Hu <[email protected]>

* add reference table

---------

Co-authored-by: Zachary Hu <[email protected]>

Author: lena-larionova

app/_includes/plugins/logging/log-custom-fields-by-lua.md

@@ -1,36 +1,39 @@
-The `custom_fields_by_lua` configuration allows for the dynamic modification of
+{% assign custom_fields_by_lua = include.custom_fields_by_lua %}
+{% assign custom_fields_by_lua_slug = include.custom_fields_by_lua_slug %}
+
+The [`custom_fields_by_lua`](./reference/#schema--{{custom_fields_by_lua_slug}}) configuration allows for the dynamic modification of
 log fields using Lua code. Below is a snippet of an example configuration that 
 removes the `route` field from the logs:
 
 ```sh
 curl -i -X POST http://localhost:8001/plugins \
-... 
-  --data config.custom_fields_by_lua.route="return nil"
+  --data config.name={{include.slug}} \
+  --data {{custom_fields_by_lua}}.route="return nil"
 ```
 
 Similarly, new fields can be added:
 
 ```sh
 curl -i -X POST http://localhost:8001/plugins \
-... 
-  --data config.custom_fields_by_lua.header="return kong.request.get_header('h1')"
+  --data config.name={{include.slug}} \
+  --data {{custom_fields_by_lua}}.header="return kong.request.get_header('h1')"
 ```
 
-### Special characters {% new_in 3.10 %}
+### Special characters {% unless page.name =="Solace Log"%}{% new_in 3.10 %}{% endunless %}
 
 Dot characters (`.`) in the field key create nested fields. You can use a backslash `\` to escape a dot if you want to keep it in the field name.
 
-For example, if you configure a field in the File Log plugin with both a regular dot and an escaped dot:
+For example, if you configure a field with both a regular dot and an escaped dot:
 
 ```sh
 curl -i -X POST http://localhost:8001/plugins/ \
 ...
-  --data config.name=file-log \
-  --data config.custom_fields_by_lua[my_file.log\.field]="return foo"
+  --data config.name={{page.name}} \
+  --data {{custom_fields_by_lua}}.[my_entry.log\.field]="return foo"
 ```
 The field will look like this in the log:
 ```sh
-"my_file": {
+"my_entry": {
   "log.field": "foo"
 }
 ```
@@ -39,19 +42,19 @@ The field will look like this in the log:
 
 All logging plugins use the same table for logging. 
 If you set `custom_fields_by_lua` in one plugin, all logging plugins that execute after that plugin will also use the same configuration. 
-For example, if you configure fields via `custom_fields_by_lua` in [File Log](/plugins/file-log/), those same fields will appear in [Kafka Log](/plugins/kafka-log/), since File Log executes first.
+For example, if you configure fields via `custom_fields_by_lua` in {% unless page.name =="Syslog" %}{{page.name}}{% else %}[File Log](/plugins/file-log/){% endunless %}, those same fields will appear in [Syslog](/plugins/syslog/), since {{page.name}} executes first.
 
 If you want all logging plugins to use the same configuration, we recommend using the [Pre-function](/plugins/pre-function/) plugin to call [kong.log.set_serialize_value](/gateway/pdk/reference/kong.log/#kong-log-set-serialize-value-key-value-options) so that the function is applied predictably and is easier to manage.
 
 If you **don't** want all logging plugins to use the same configuration, you need to manually disable the relevant fields in each plugin. 
 
-For example, if you configure a field in File Log that you don't want appearing in Kafka Log, set that field to `return nil` in the Kafka Log plugin:
+For example, if you configure a field in File Log that you don't want appearing in {{include.name}}, set that field to `return nil` in the {{include.name}} plugin:
 
 ```sh
 curl -i -X POST http://localhost:8001/plugins/ \
 ...
-  --data config.name=kafka-log \
-  --data config.custom_fields_by_lua.my_file_log_field="return nil"
+  --data config.name={{include.slug}} \
+  --data {{custom_fields_by_lua}}.my_file_log_field="return nil"
 ```
 
 See the [plugin execution order reference](/gateway/entities/plugin/#plugin-contexts) for more details on plugin ordering.

app/_kong_plugins/file-log/index.md

@@ -67,4 +67,4 @@ to physical files on slow (spinning) disks.
 
 ## Custom fields by Lua
 
-{% include /plugins/logging/log-custom-fields-by-lua.md %}
+{% include /plugins/logging/log-custom-fields-by-lua.md custom_fields_by_lua='config.custom_fields_by_lua' custom_fields_by_lua_slug='config-custom-fields-by-lua' name=page.name slug=page.slug %}

app/_kong_plugins/http-log/index.md

@@ -85,4 +85,4 @@ In contrast to other plugins that use queues, all HTTP Log plugin instances that
 
 ## Custom fields by Lua
 
-{% include /plugins/logging/log-custom-fields-by-lua.md %}
+{% include /plugins/logging/log-custom-fields-by-lua.md custom_fields_by_lua='config.custom_fields_by_lua' custom_fields_by_lua_slug='config-custom-fields-by-lua' name=page.name slug=page.slug %}

app/_kong_plugins/kafka-log/index.md

@@ -72,7 +72,7 @@ When encoding request bodies, several things happen:
 
 ## Custom fields by Lua
 
-{% include /plugins/logging/log-custom-fields-by-lua.md %}
+{% include /plugins/logging/log-custom-fields-by-lua.md custom_fields_by_lua='config.custom_fields_by_lua' custom_fields_by_lua_slug='config-custom-fields-by-lua' name=page.name slug=page.slug %}
 
 ## Schema registry support {% new_in 3.11 %}
 

app/_kong_plugins/loggly/index.md

@@ -55,4 +55,4 @@ Log request and response data over UDP to [Loggly](https://www.loggly.com).
 
 ## Custom fields by Lua
 
-{% include /plugins/logging/log-custom-fields-by-lua.md %}
+{% include /plugins/logging/log-custom-fields-by-lua.md custom_fields_by_lua='config.custom_fields_by_lua' custom_fields_by_lua_slug='config-custom-fields-by-lua' name=page.name slug=page.slug %}

app/_kong_plugins/solace-log/changelog.json

@@ -0,0 +1,9 @@
+{
+  "3.12.0.0": [
+    {
+      "message": "Added Solace Log plugin.",
+      "type": "feature",
+      "scope": "Plugin"
+    }
+  ]
+}

app/_kong_plugins/solace-log/examples/enable-solace-log.yaml

@@ -0,0 +1,35 @@
+description: 'Set up the Solace logging plugin to send logs to a Solace message broker.'
+
+title: 'Enable Solace Logging'
+
+weight: 900
+
+requirements: 
+ - "[Solace installed](https://docs.solace.com/API/API-Developer-Guide/Installation.htm) and running" 
+
+config:
+  session:
+    host: "tcp://192.168.88.20:55555"
+    vpn_name: "default"
+    authentication:
+      scheme: "BASIC"
+      username: "admin"
+      password: "admin"
+  message:
+    destinations:
+      - name: "test"
+        type: "QUEUE"
+    delivery_mode: "PERSISTENT"
+    custom_fields_by_lua:
+      broker: 'return "solace"'
+
+tools:
+  - deck
+  - admin-api
+  - konnect-api
+  - kic
+  - terraform
+
+min_version:
+  gateway: '3.12'
+    

app/_kong_plugins/solace-log/index.md

@@ -0,0 +1,80 @@
+---
+title: 'Solace Log'
+name: 'Solace Log'
+
+content_type: plugin
+
+publisher: kong-inc
+tier: enterprise
+description: 'Publish request and response logs to a Solace endpoint or topic'
+
+products:
+    - gateway
+
+works_on:
+    - on-prem
+    - konnect
+
+min_version:
+    gateway: '3.12'
+
+topologies:
+  on_prem:
+    - hybrid
+    - db-less
+    - traditional
+  konnect_deployments:
+    - hybrid
+    - cloud-gateways
+    - serverless
+
+tags:
+  - logging
+  - events
+  - solace
+
+search_aliases:
+  - solace-log
+  - events
+  - event-gateway
+
+icon: solace-log.png
+
+categories:
+   - logging
+
+related_resources:
+  - text: Solace Upstream plugin
+    url: /plugins/solace-upstream/
+  - text: Solace Consume plugin
+    url: /plugins/solace-consume/
+  - text: Event Gateway
+    url: /event-gateway/
+---
+
+Publish request and response logs in `JSON` format to a [Solace](https://solace.com/) endpoint or topic.
+For more information, see [Solace Event Messaging Overview](https://docs.solace.com/Messaging/messaging-overview.htm).
+
+Kong also provides plugins for publishing messages to and consuming messages from Solace:
+* [Solace Upstream](/plugins/solace-upstream/)
+* [Solace Consume](/plugins/solace-consume/)
+
+## Log format
+
+{% include /plugins/logging/log-format.md %}
+
+### Log format definitions 
+
+{% include /plugins/logging/json-object-log.md %}
+
+## Implementation details
+
+This plugin leverages the [log PDK](/gateway/pdk/reference/kong.log/) to collect and [customize](#custom-fields-by-lua) log fields.
+
+The prepared log message is sent to the Solace broker via the official [Solace C API](https://docs.solace.com/API/Messaging-APIs/C-API/c-api-home.htm). The sending job is executed in a background timer context so that it doesn't block client requests.
+
+If the [custom Lua code](#custom-fields-by-lua) associated with the log fields fails to execute, the relevant fields remain untouched.
+
+## Custom fields by Lua
+
+{% include /plugins/logging/log-custom-fields-by-lua.md custom_fields_by_lua='config.message.custom_fields_by_lua' custom_fields_by_lua_slug='config-message-custom-fields-by-lua' name=page.name slug=page.slug %}

app/_kong_plugins/solace-log/reference.md

@@ -0,0 +1,3 @@
+---
+content_type: reference
+---

app/_kong_plugins/syslog/index.md

@@ -70,7 +70,7 @@ logging level severity equal to or lower than the one set in the [`config.log_le
 
 ## Custom fields by Lua
 
-{% include /plugins/logging/log-custom-fields-by-lua.md %}
+{% include /plugins/logging/log-custom-fields-by-lua.md custom_fields_by_lua='config.custom_fields_by_lua' custom_fields_by_lua_slug='config-custom-fields-by-lua' name=page.name slug=page.slug %}
 
 ## Forwarding logs to a remote network host