mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-06-28 17:34:17 -04:00
92 lines
5.3 KiB
Text
92 lines
5.3 KiB
Text
[[reroute-processor]]
|
|
=== Reroute processor
|
|
++++
|
|
<titleabbrev>Reroute</titleabbrev>
|
|
++++
|
|
|
|
The `reroute` processor allows to route a document to another target index or data stream.
|
|
It has two main modes:
|
|
|
|
When setting the `destination` option, the target is explicitly specified and the `dataset` and `namespace` options can't be set.
|
|
|
|
When the `destination` option is not set, this processor is in a data stream mode.
|
|
Note that in this mode, the `reroute` processor can only be used on data streams that follow the {fleet-guide}/data-streams.html#data-streams-naming-scheme[data stream naming scheme].
|
|
Trying to use this processor on a data stream with a non-compliant name will raise an exception.
|
|
|
|
The name of a data stream consists of three parts: `<type>-<dataset>-<namespace>`.
|
|
See the {fleet-guide}/data-streams.html#data-streams-naming-scheme[data stream naming scheme] documentation for more details.
|
|
|
|
This processor can use both static values or reference fields from the document to determine the `dataset` and `namespace` components of the new target.
|
|
See <<reroute-options>> for more details.
|
|
|
|
NOTE: It's not possible to change the `type` of the data stream with the `reroute` processor.
|
|
|
|
After a `reroute` processor has been executed, all the other processors of the current pipeline are skipped, including the final pipeline.
|
|
If the current pipeline is executed in the context of a <<pipeline-processor>>, the calling pipeline will be skipped, too.
|
|
This means that at most one `reroute` processor is ever executed within a pipeline,
|
|
allowing to define mutually exclusive routing conditions,
|
|
similar to a if, else-if, else-if, … condition.
|
|
|
|
The reroute processor ensures that the `data_stream.<type|dataset|namespace>` fields are set according to the new target.
|
|
If the document contains a `event.dataset` value, it will be updated to reflect the same value as `data_stream.dataset`.
|
|
|
|
Note that the client needs to have permissions to the final target.
|
|
Otherwise, the document will be rejected with a security exception which looks like this:
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
{"type":"security_exception","reason":"action [indices:admin/auto_create] is unauthorized for API key id [8-dt9H8BqGblnY2uSI--] of user [elastic/fleet-server] on indices [logs-foo-default], this action is granted by the index privileges [auto_configure,create_index,manage,all]"}
|
|
--------------------------------------------------
|
|
// NOTCONSOLE
|
|
|
|
[[reroute-options]]
|
|
.Reroute options
|
|
[options="header"]
|
|
|======
|
|
| Name | Required | Default | Description
|
|
| `destination` | no | - | A static value for the target. Can't be set when the `dataset` or `namespace` option is set.
|
|
| `dataset` | no | `{{data_stream.dataset}}` a| Field references or a static value for the dataset part of the data stream name. In addition to the criteria for <<indices-create-api-path-params, index names>>, cannot contain `-` and must be no longer than 100 characters. Example values are `nginx.access` and `nginx.error`.
|
|
|
|
Supports field references with a mustache-like syntax (denoted as `{{double}}` or `{{{triple}}}` curly braces). When resolving field references, the processor replaces invalid characters with `_`. Uses the `<dataset>` part of the index name as a fallback if all field references resolve to a `null`, missing, or non-string value.
|
|
| `namespace` | no | `{{data_stream.namespace}}` a| Field references or a static value for the namespace part of the data stream name. See the criteria for <<indices-create-api-path-params, index names>> for allowed characters. Must be no longer than 100 characters.
|
|
|
|
Supports field references with a mustache-like syntax (denoted as `{{double}}` or `{{{triple}}}` curly braces). When resolving field references, the processor replaces invalid characters with `_`. Uses the `<namespace>` part of the index name as a fallback if all field references resolve to a `null`, missing, or non-string value.
|
|
include::common-options.asciidoc[]
|
|
|======
|
|
|
|
The `if` option can be used to define the condition in which the document should be rerouted to a new target.
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
{
|
|
"reroute": {
|
|
"tag": "nginx",
|
|
"if" : "ctx?.log?.file?.path?.contains('nginx')",
|
|
"dataset": "nginx"
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// NOTCONSOLE
|
|
|
|
The dataset and namespace options can contain either a single value or a list of values that are used as a fallback.
|
|
If a field reference evaluates to `null`, is not present in the document, the next value or field reference is used.
|
|
If a field reference evaluates to a non-`String` value, the processor fails.
|
|
|
|
In the following example, the processor would first try to resolve the value for the `service.name` field to determine the value for `dataset`.
|
|
If that field resolves to `null`, is missing, or is a non-string value, it would try the next element in the list.
|
|
In this case, this is the static value `"generic`".
|
|
The `namespace` option is configured with just a single static value.
|
|
|
|
[source,js]
|
|
--------------------------------------------------
|
|
{
|
|
"reroute": {
|
|
"dataset": [
|
|
"{{service.name}}",
|
|
"generic"
|
|
],
|
|
"namespace": "default"
|
|
}
|
|
}
|
|
--------------------------------------------------
|
|
// NOTCONSOLE
|