improve timestamper processor documentation (#618)

* update changelog

* add additional failure testcase and clarify documentation

CHANGELOG.md

@@ -9,10 +9,12 @@
 and `field_manager` processors
 
 ### Features
+
 ### Improvements
 
 * a result object was added which is returned by every processor
   * includes generated extra_data, warnings and errors
+* add documentation about behavior of the `timestamper` on `ISO8601` and `UNIX` time parsing
 
 ### Bugfix
 

logprep/processor/timestamper/processor.py

@@ -30,7 +30,7 @@
 from logprep.processor.field_manager.processor import FieldManager
 from logprep.processor.timestamper.rule import TimestamperRule
 from logprep.util.helper import get_dotted_field_value
-from logprep.util.time import TimeParserException, TimeParser
+from logprep.util.time import TimeParser, TimeParserException
 
 
 class Timestamper(FieldManager):

logprep/processor/timestamper/rule.py

@@ -90,14 +90,36 @@ class Config(FieldManagerRule.Config):
             default=["ISO8601"],
             converter=lambda x: x if isinstance(x, list) else [x],
         )
-        """A list of possible source formats if source_fields is not an iso8601 compliant time format string
-        the format must be given in the syntax of the python builtin :code:`datetime.strptime`
+        """A list of possible source formats if source_fields is not an iso8601 compliant
+        time format string the format must be given in the syntax of the
+        python builtin :code:`datetime.strptime`
         (see: https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes).
         Additionally, the value :code:`ISO8601` (default)  and :code:`UNIX` can be used in the list
         of the source_formats field. The former can be used if the timestamp already exists
         in the ISO8601 format, such that only a timezone conversion should be applied.
         And the latter can be used if the timestamp is given in the UNIX Epoch Time.
         This supports the Unix timestamps in seconds and milliseconds.
+        Be aware that :code:`UNIX` and :code:`ISO8601` formats do not validate the completeness of
+        input string. If you want to ensure, the completeness of the input string, you have to use
+        the :code:`datetime.strptime` syntax.
+
+        For example, the following time formats are valid :code:`ISO8601` formats:
+
+        - :code:`hh:mm`
+        - :code:`hh:mm:ss`
+        - :code:`hh:mm:ss.sss`
+        - :code:`hhmmss.ssssss`
+        - :code:`hhmm`
+        - :code:`hhmmss`
+
+        The output string will always be in this format: :code:`2000-12-31T22:59:59Z`.
+        As you can see the output string has a time with seconds.
+        If the input string does not have a time or the time does not have seconds,
+        the output string will have seconds or times set to zero.
+
+        If you don't want this behavior, you have to use the :code:`datetime.strptime` syntax.
+        With this syntax, the :code:`timestamper`errors out with a :code:`TimeParserException` and
+        a tag :code:`_timestamper_failure` will be added to the event.
         """
         source_timezone: ZoneInfo = field(
             validator=[validators.instance_of(ZoneInfo)], converter=ZoneInfo, default="UTC"

tests/unit/processor/timestamper/test_timestamper.py

@@ -275,6 +275,21 @@
         {"message": "2000 12 31 - 22:59:59", "tags": ["_timestamper_failure"]},
         r"Could not parse timestamp",
     ),
+    (
+        "attempt parsing valid ISO8601 with not matching pattern",
+        {
+            "filter": "message",
+            "timestamper": {
+                "source_fields": ["message"],
+                "source_format": ["%Y-%m-%dT%H:%M:%S"],
+            },
+        },
+        {
+            "message": "2019-09-07T15:50",
+        },
+        {"message": "2019-09-07T15:50", "tags": ["_timestamper_failure"]},
+        r"Could not parse timestamp",
+    ),
     (
         "raises if source field is none",
         {"filter": "message", "timestamper": {"source_fields": ["@timestamp"]}},