Add json property description for list-to-map, map-to-list and user-a…

…gent processor (opensearch-project#4759) Signed-off-by: Hai Yan <[email protected]> Signed-off-by: Krishna Kondaka <[email protected]>
kkondaka · Aug 8, 2024 · a502bcb · a502bcb
1 parent 80315d3
commit a502bcb
Show file tree

Hide file tree

Showing 3 changed files with 43 additions and 0 deletions.
diff --git a/...va/org/opensearch/dataprepper/plugins/processor/mutateevent/ListToMapProcessorConfig.java b/...va/org/opensearch/dataprepper/plugins/processor/mutateevent/ListToMapProcessorConfig.java
@@ -7,6 +7,7 @@
 
 import com.fasterxml.jackson.annotation.JsonCreator;
 import com.fasterxml.jackson.annotation.JsonProperty;
+import com.fasterxml.jackson.annotation.JsonPropertyDescription;
 import jakarta.validation.constraints.NotEmpty;
 import jakarta.validation.constraints.NotNull;
 
@@ -41,35 +42,55 @@ static FlattenedElement fromOptionValue(final String option) {
     @NotEmpty
     @NotNull
     @JsonProperty("source")
+    @JsonPropertyDescription("The list of objects with `key` fields to be converted into keys for the generated map.")
     private String source;
 
     @JsonProperty("target")
+    @JsonPropertyDescription("The target for the generated map. When not specified, the generated map will be " +
+            "placed in the root node.")
     private String target = null;
 
     @JsonProperty("key")
+    @JsonPropertyDescription("The key of the fields to be extracted as keys in the generated mappings. Must be " +
+            "specified if `use_source_key` is `false`.")
     private String key;
 
     @JsonProperty("value_key")
+    @JsonPropertyDescription("When specified, values given a `value_key` in objects contained in the source list " +
+            "will be extracted and converted into the value specified by this option based on the generated map. " +
+            "When not specified, objects contained in the source list retain their original value when mapped.")
     private String valueKey = null;
 
     @JsonProperty("use_source_key")
+    @JsonPropertyDescription("When `true`, keys in the generated map will use original keys from the source. " +
+            "Default is `false`.")
     private boolean useSourceKey = false;
 
     @JsonProperty("extract_value")
+    @JsonPropertyDescription("When `true`, object values from the source list will be extracted and added to " +
+            "the generated map. When `false`, object values from the source list are added to the generated map " +
+            "as they appear in the source list. Default is `false`")
     private boolean extractValue = false;
 
     @NotNull
     @JsonProperty("flatten")
+    @JsonPropertyDescription("When `true`, values in the generated map output flatten into single items based on " +
+            "the `flattened_element`. Otherwise, objects mapped to values from the generated map appear as lists.")
     private boolean flatten = false;
 
     @NotNull
     @JsonProperty("flattened_element")
+    @JsonPropertyDescription("The element to keep, either `first` or `last`, when `flatten` is set to `true`.")
     private FlattenedElement flattenedElement = FlattenedElement.FIRST;
 
     @JsonProperty("list_to_map_when")
+    @JsonPropertyDescription("A [conditional expression](https://opensearch.org/docs/latest/data-prepper/pipelines/expression-syntax/), " +
+            "such as `/some-key == \"test\"'`, that will be evaluated to determine whether the processor will be " +
+            "run on the event. Default is `null`. All events will be processed unless otherwise stated.")
     private String listToMapWhen;
 
     @JsonProperty("tags_on_failure")
+    @JsonPropertyDescription("A list of tags to add to the event metadata when the event fails to process.")
     private List<String> tagsOnFailure;
 
     public String getSource() {

diff --git a/...va/org/opensearch/dataprepper/plugins/processor/mutateevent/MapToListProcessorConfig.java b/...va/org/opensearch/dataprepper/plugins/processor/mutateevent/MapToListProcessorConfig.java
@@ -6,6 +6,7 @@
 package org.opensearch.dataprepper.plugins.processor.mutateevent;
 
 import com.fasterxml.jackson.annotation.JsonProperty;
+import com.fasterxml.jackson.annotation.JsonPropertyDescription;
 import jakarta.validation.constraints.NotEmpty;
 import jakarta.validation.constraints.NotNull;
 
@@ -20,32 +21,47 @@ public class MapToListProcessorConfig {
 
     @NotNull
     @JsonProperty("source")
+    @JsonPropertyDescription("The source map used to perform the mapping operation. When set to an empty " +
+            "string (`\"\"`), it will use the root of the event as the `source`.")
     private String source;
 
     @NotEmpty
     @NotNull
     @JsonProperty("target")
+    @JsonPropertyDescription("The target for the generated list.")
     private String target;
 
     @JsonProperty("key_name")
+    @JsonPropertyDescription("The name of the field in which to store the original key. Default is `key`.")
     private String keyName = DEFAULT_KEY_NAME;
 
     @JsonProperty("value_name")
+    @JsonPropertyDescription("The name of the field in which to store the original value. Default is `value`.")
     private String valueName = DEFAULT_VALUE_NAME;
 
     @JsonProperty("map_to_list_when")
+    @JsonPropertyDescription("A [conditional expression](https://opensearch.org/docs/latest/data-prepper/pipelines/expression-syntax/), " +
+            "such as `/some-key == \"test\"'`, that will be evaluated to determine whether the processor will " +
+            "be run on the event. Default is `null`. All events will be processed unless otherwise stated.")
     private String mapToListWhen;
 
     @JsonProperty("exclude_keys")
+    @JsonPropertyDescription("The keys in the source map that will be excluded from processing. Default is an " +
+            "empty list (`[]`).")
     private List<String> excludeKeys = DEFAULT_EXCLUDE_KEYS;
 
     @JsonProperty("remove_processed_fields")
+    @JsonPropertyDescription("When `true`, the processor will remove the processed fields from the source map. " +
+            "Default is `false`.")
     private boolean removeProcessedFields = DEFAULT_REMOVE_PROCESSED_FIELDS;
 
     @JsonProperty("convert_field_to_list")
+    @JsonPropertyDescription("If `true`, the processor will convert the fields from the source map into lists and " +
+            "place them in fields in the target list. Default is `false`.")
     private boolean convertFieldToList = false;
 
     @JsonProperty("tags_on_failure")
+    @JsonPropertyDescription("A list of tags to add to the event metadata when the event fails to process.")
     private List<String> tagsOnFailure;
 
     public String getSource() {

diff --git a/...java/org/opensearch/dataprepper/plugins/processor/useragent/UserAgentProcessorConfig.java b/...java/org/opensearch/dataprepper/plugins/processor/useragent/UserAgentProcessorConfig.java
@@ -6,6 +6,7 @@
 package org.opensearch.dataprepper.plugins.processor.useragent;
 
 import com.fasterxml.jackson.annotation.JsonProperty;
+import com.fasterxml.jackson.annotation.JsonPropertyDescription;
 import jakarta.validation.constraints.NotEmpty;
 import jakarta.validation.constraints.NotNull;
 import org.opensearch.dataprepper.model.event.EventKey;
@@ -21,21 +22,26 @@ public class UserAgentProcessorConfig {
     @NotEmpty
     @NotNull
     @JsonProperty("source")
+    @JsonPropertyDescription("The field in the event that will be parsed.")
     @EventKeyConfiguration(EventKeyFactory.EventAction.GET)
     private EventKey source;
 
     @NotNull
     @JsonProperty("target")
+    @JsonPropertyDescription("The field to which the parsed event will write. Default is `user_agent`.")
     private String target = "user_agent";
 
     @NotNull
     @JsonProperty("exclude_original")
+    @JsonPropertyDescription("Determines whether to exclude the original UA string from the parsing result. Defaults to `false`. ")
     private boolean excludeOriginal = false;
 
     @JsonProperty("cache_size")
+    @JsonPropertyDescription("The cache size of the parser in megabytes. Defaults to `1000`.")
     private int cacheSize = DEFAULT_CACHE_SIZE;
 
     @JsonProperty("tags_on_parse_failure")
+    @JsonPropertyDescription("The tag to add to an event if the `user_agent` processor fails to parse the UA string.")
     private List<String> tagsOnParseFailure;
 
     public EventKey getSource() {