diff --git a/app/_includes/plugins/logging/log-custom-fields-by-lua.md b/app/_includes/plugins/logging/log-custom-fields-by-lua.md index bdd464d570..5c06220637 100644 --- a/app/_includes/plugins/logging/log-custom-fields-by-lua.md +++ b/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. diff --git a/app/_kong_plugins/file-log/index.md b/app/_kong_plugins/file-log/index.md index 64a1a52e06..1ea0e34045 100644 --- a/app/_kong_plugins/file-log/index.md +++ b/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 %} diff --git a/app/_kong_plugins/http-log/index.md b/app/_kong_plugins/http-log/index.md index a2010ad7b4..7e9a3d41f6 100644 --- a/app/_kong_plugins/http-log/index.md +++ b/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 %} diff --git a/app/_kong_plugins/kafka-log/index.md b/app/_kong_plugins/kafka-log/index.md index 1cf6ab6b6d..462847e194 100644 --- a/app/_kong_plugins/kafka-log/index.md +++ b/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 %} diff --git a/app/_kong_plugins/loggly/index.md b/app/_kong_plugins/loggly/index.md index 7d2caa88b1..5f8255c1d2 100644 --- a/app/_kong_plugins/loggly/index.md +++ b/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 %} \ No newline at end of file diff --git a/app/_kong_plugins/solace-log/changelog.json b/app/_kong_plugins/solace-log/changelog.json new file mode 100644 index 0000000000..eb62739eaf --- /dev/null +++ b/app/_kong_plugins/solace-log/changelog.json @@ -0,0 +1,9 @@ +{ + "3.12.0.0": [ + { + "message": "Added Solace Log plugin.", + "type": "feature", + "scope": "Plugin" + } + ] +} \ No newline at end of file diff --git a/app/_kong_plugins/solace-log/examples/enable-solace-log.yaml b/app/_kong_plugins/solace-log/examples/enable-solace-log.yaml new file mode 100644 index 0000000000..7dad2c379d --- /dev/null +++ b/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' + \ No newline at end of file diff --git a/app/_kong_plugins/solace-log/index.md b/app/_kong_plugins/solace-log/index.md new file mode 100644 index 0000000000..77b0947113 --- /dev/null +++ b/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 %} diff --git a/app/_kong_plugins/solace-log/reference.md b/app/_kong_plugins/solace-log/reference.md new file mode 100644 index 0000000000..a00b1c79b1 --- /dev/null +++ b/app/_kong_plugins/solace-log/reference.md @@ -0,0 +1,3 @@ +--- +content_type: reference +--- \ No newline at end of file diff --git a/app/_kong_plugins/syslog/index.md b/app/_kong_plugins/syslog/index.md index 124693c6a8..44c220814c 100644 --- a/app/_kong_plugins/syslog/index.md +++ b/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 diff --git a/app/_kong_plugins/tcp-log/index.md b/app/_kong_plugins/tcp-log/index.md index 2d69341303..e446d622ae 100644 --- a/app/_kong_plugins/tcp-log/index.md +++ b/app/_kong_plugins/tcp-log/index.md @@ -54,4 +54,4 @@ Log request and response data to a TCP server. ## Custom fields by Lua -{% include /plugins/logging/log-custom-fields-by-lua.md %} \ No newline at end of file +{% 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 %} \ No newline at end of file diff --git a/app/_kong_plugins/udp-log/index.md b/app/_kong_plugins/udp-log/index.md index 77bccd153a..a1a67f175c 100644 --- a/app/_kong_plugins/udp-log/index.md +++ b/app/_kong_plugins/udp-log/index.md @@ -55,4 +55,4 @@ Log request and response data to a UDP server. ## 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 %} \ No newline at end of file diff --git a/app/assets/icons/plugins/solace-log.png b/app/assets/icons/plugins/solace-log.png new file mode 100644 index 0000000000..1cb77fdfd6 Binary files /dev/null and b/app/assets/icons/plugins/solace-log.png differ