V3: filter audit_events via created_at, equals

This commit polishes the documentation:

- We use the upcoming timestamp format, `YYYY-MM-DDThh:mm:ssZ`, in our
  documentation. Previously we used a version that supports the local
  timezone. That version will no longer be allowed when a future story is
  implemented.

- We don't trouble the user with the knowledge that timestamps are often
  recorded with sub-second accuracy in the database. The explanation is
  long-winded, and adds no value to the user. The user is better left off
  believing that databases timestamps have a granularity of seconds (not,
  as in the case of PostgreSQL, microseconds).

[#173517696]

Authored-by: Brian Cunnie <bcunnie@vmware.com>

Author: cunnie

app/fetchers/event_list_fetcher.rb

@@ -48,8 +48,8 @@ def filter(message, dataset)
             end
           else
             # Gotcha: unlike the other relational operators, which are hashes such as
-            # { lt: '2020-06-29T12:34:56-07:00' }, the equals operator is simply a value, e.g.
-            # '2020-06-29T12:34:56-07:00'.
+            # { lt: '2020-06-30T12:34:56Z' }, the equals operator is simply a value, e.g.
+            # '2020-06-30T12:34:56Z'.
             # Gotcha: the equals operator returns all resources occurring within
             # the span of the second (e.g. "12:34:56.00-12:34:56.9999999"), for databases store
             # timestamps in sub-second accuracy (PostgreSQL stores in microseconds, for example)

docs/v3/source/includes/concepts/_filters.md.erb

@@ -44,24 +44,16 @@ This will return all routes with hostname `"hostname1"`, `""` OR `"hostname2"`.
 ##### Filtering on Equality
 
 Fields can be filtered using equality when listing resources. Currently, only the `created_at` field
-is supported.
-
-For example, a response to `/v3/audit_events?created_at=2020-06-29T12:34:56-07:00` will contain
-audit events with a `created_at` timestamp equal to `2020-06-29T13:56:40`, PDT.  Most databases
-store timestamps with sub-second accuracy. When filtering on equality, the response will include
-_all_ resources within the second specified. For example, in the above query, any audit event
-occurring as early as `12:34:56.00` will be returned as well as any audit event occurring as late as
-`12:34:56.999999`.
-
-Timestamps must be in ISO 8601 format.
+is supported. The `created_at` field expects a timestamp filter, and timestamps must be in ISO 8601
+format, e.g. `2020-06-30T12:34:56Z`.
 
 ##### Filtering on Inequality
 
 Fields can be filtered using inequality when listing resources. Currently, only the `created_at`
 field is supported.
 
-For example, a response to `/v3/audit_events?created_at[lt]=2020-06-29T13:56:40-07:00` will contain
-audit events with a `created_at` timestamp strictly earlier than `2020-06-29T13:56:40`, PDT.
+For example, a response to `/v3/audit_events?created_at[lt]=2020-06-30T12:34:56Z` will contain
+audit events with a `created_at` timestamp strictly earlier than `2020-06-30T12:34:56Z`.
 
 Timestamps must be in ISO 8601 format.