Problem statement
Is it possible to search the tenant logs for specific types of activity between two dates?
In this case, we would like to view events related to Passwordless login over the last 14 days.
Solution
- How to view Log Events
Log events can be viewed using the Dashboard or the Management API:
For this article, it will be assumed that the log search will be performed via the Dashboard.
- Search within a range of dates
The Auth0 documentation describes several strategies for searching tenant logs that lie within certain date boundaries:
This is the general approach to setting date boundaries:
- For inclusive ranges, use square brackets:
[min TO max] - For exclusive ranges, use curly brackets:
{min TO max}
The following is an example of how to search the tenant logs for activity within a 14-day period between October 12th, 2023, and October 26th, 2023. This will provide an example of how to use the ‘inclusive’ and ‘exclusive’ constraints:
The format of the sample query is as follows:
date:[2023-10-12T00:00:00 TO 2023-10-27T00:00:00}
Note the following:
- The first character in the expression is a square bracket ‘]’, which indicates that this date is inclusive.
- The last character in the expression is a curly bracket ‘}’, which indicates that this date is exclusive.
This query can be interpreted as “Find and show me all activity in the tenant logs, starting at midnight on October 12th, for the next 14-day period, excluding activity starting at midnight on October 27th”.
- Log retention period
The range of dates that can be searched will depend on the type of subscription plan that a customer has. The retention period for tenant logs can vary from 1 day for free tenants to 30 days for our premium business plans.
Check our Pricing page for details of the log retention periods of the various subscription plans that Auth0 offers:
- What is your Use Case → Compare Plans → Platform → Log Retention
If it is desired to store copies of tenant logs outside of the log retention period, then Log Streaming is recommended.
- Using filters
Searching for log events with a certain range of dates and times will likely produce a lot of irrelevant information. The following is an example of how filters can display only wanted types of events. Auth0 provides a rich set of Log Event codes that can be used to filter out only wanted types of events:
Consider an example of a customer who has recently started using a Passwordless connection and would like to review activity patterns in the first 14 days of use. The fundamental requirement here is to search the tenant logs for all activity within a 14-day period, between October 12th, 2023, and October 26th, 2023. Once again, here is the search expression that will be used for this purpose:
date:[2023-10-12T00:00:00 TO 2023-10-27T00:00:00}
The next step is to combine this expression with a filter. To select the correct filter, it is necessary to have a clear understanding of the basic type(s) of information that we are looking for. In this example, we can refer to the Passwordless section of the Authentication documentation:
This describes the three options that rely on a call to the POST /passwordless/start endpoint.
- Send a verification code using email.
- Send a link using email.
- Send a verification code using SMS.
The next step is to find the Event Codes that refer to these activities: If it is unclear what event name to search for, it may be necessary to browse through the page to find the required event description.
In this example of a search for events relating to Passwordless login, the desired events are Code/Link Sent (cls) and Code Sent (cs)
These search terms can be combined with the date/time search that displays only the wanted events. The format of each of these combined search terms is as follows:
date:[2023-10-12T00:00:00 TO 2023-10-27T00:00:00} AND cls
date:[2023-10-12T00:00:00 TO 2023-10-27T00:00:00} AND cs
It’s possible to combine these search terms using logical AND / OR clauses, as in this example:
date:[2023-10-12T00:00:00 TO 2023-10-27T00:00:00} AND ( cs OR cls )
Log searches frequently return examples of failed events, indicating something has gone wrong. In this example, it is possible to find instances where Passwordless OTP has failed by searching for Failed Exchange (fepotpft) events. The format of this query would be:
date:[2023-10-12T00:00:00 TO 2023-10-27T00:00:00} AND fepotpft
This will help to narrow down the cause of any failures that may have been experienced.
- Where to find out more about Logs
The documentation on Logs provides a useful overview of tenant logs and includes links to all of the other major aspects of log search and management that can make working with logs more productive.