14.2 Configuring and Leveraging Syslog
Key Takeaways
IdentityIQ Syslog stores WARN, ERROR, and FATAL events, with stack traces, in the database; it is unrelated to the operating system's syslog service.
Syslog is enabled on Global Settings > IdentityIQ Configuration > Miscellaneous, where you set the lowest stored level (FATAL, ERROR, or WARN) and the days before deletion.
The incident code shown in a UI error banner is searched in Advanced Analytics > Syslog to retrieve the full stack trace.
Each Syslog event records the Server, which makes it especially useful in multi-host clusters.
The Perform Maintenance task's Prune syslog events option deletes events older than the configured age.
Configuring and Leveraging Syslog
Objective 6.2 is configure and leverage Syslog. In IdentityIQ, Syslog means a database record of errors, stored as syslog events, that administrators can search from the UI. It is not the Unix syslog daemon or a remote syslog server, which is a common source of confusion. The documentation describes a syslog event as "a capture of an error in the system, including the stack trace of the error."
Why Syslog Exists
Log files live on each server's disk, rotate away, and are often out of reach for administrators. Syslog puts the most important events, warnings, errors, and fatal errors, into the database, where anyone with the right access can search them. Each record includes the server that produced it, the user, and the stack trace. SailPoint notes that the Syslog search page is "used primarily to determine specific support information that SailPoint IdentityIQ support engineers can use for troubleshooting."
Configuration
Go to gear icon > Global Settings > IdentityIQ Configuration > Miscellaneous > Syslog Settings:
| Setting | Meaning |
|---|---|
| Enable syslog | Turns capture on |
| Level at which syslog events will be stored | The lowest level stored: FATAL, ERROR, or WARN. Lower levels, such as INFO and DEBUG, are never stored in Syslog. They go only to Log4j appenders (section 14.1). |
| Days before syslog event deletion | How long events are kept before they become eligible for purging |
The Perform Maintenance task's Prune syslog events option deletes events older than that age. Choosing WARN captures more detail but grows the table faster, so pick the level that fits your retention period and support needs.
From Incident Code to Stack Trace
When something fails in the UI, IdentityIQ shows a banner such as:
"The system has encountered a serious error while processing your request. Please report the following incident code to your system administrator: <incident code>"
The documented procedure:
- Note the incident code. Codes are specific to your environment.
- Go to Intelligence > Advanced Analytics and choose the Syslog search type.
- Enter the Incident Code and run the search.
- Open the event to see its stack trace. Attach it to a SailPoint Support case if you need to escalate.
Syslog Search Criteria
| Field | Use |
|---|---|
| Incident Code | The ID shown at the end of a UI error message |
| Server | The host where the exception happened, which is vital in clustered environments |
| Level | WARN, ERROR, or FATAL |
| Username | The user, or a system process, performing the action |
| Classname | The Java class that raised the exception |
| Message | The exception message |
| Line / Thread Name | Where and in which thread the error occurred |
| Start Date / End Date | A time window |
Like other Advanced Analytics searches, you can choose Fields to Display, save a Syslog search, or save it as a report and schedule it. A daily "errors on the task servers in the last 24 hours" report is a cheap early-warning system.
Using Syslog in a Debugging Routine
| Situation | Syslog helps by… | Pair it with… |
|---|---|---|
| A user reports a UI error | Finding the exact stack trace by incident code | The Debug pages (section 15.1) to inspect the objects involved |
| A task ended with errors overnight | Listing ERROR events by date, server, and class | Task results and the Administrator Console (section 15.2) |
| An intermittent problem on one node | Filtering by Server | log4j DEBUG on that node only (section 14.1) |
| A custom rule throws exceptions | Filtering by Classname or Message | The rule's own named logger |
Worked Example: An Overnight Task Failure
The nightly Identity Refresh finished with errors, and the task result says only that some identities failed.
- In Advanced Analytics > Syslog, set the date range to last night and Level to ERROR.
- Sort or filter by Classname. Most errors point to a custom rule class and the same Message, a null pointer.
- The Server column shows that every error came from one task host, so the problem is data or code, not a single failing node. Open one event's stack trace to find the rule and line.
- Turn on the rule's DEBUG logger on that host (section 14.1), refresh one affected identity from the console, and read the log to see which attribute was null.
- Fix the rule, rerun the refresh, and save the Syslog search as a daily report so the next regression is caught the same morning.
Syslog, Log Files, and Audit Compared
| Source | Contains | Best for |
|---|---|---|
| Syslog (database) | WARN, ERROR, and FATAL events with stack traces | Finding and sharing errors from the UI, by incident code |
| Log4j log files | Every level you enable, per host | Detailed step-by-step diagnosis |
| Audit events (section 8.3) | Business actions you chose to audit | Who did what, for compliance |
Common Misconceptions
- "Enable syslog forwards events to our SIEM." No. It stores events in IdentityIQ's own database. Getting data to a SIEM uses other features, such as audit exports or log appenders.
- "Syslog will show my debug statements." No. Only WARN, ERROR, and FATAL are stored.
- "Syslog keeps events forever." Not if Perform Maintenance prunes them after the configured number of days.
A user sees an error banner containing an incident code. What is the documented way to find the underlying stack trace?
Search for the incident code in Intelligence > Advanced Analytics with the Syslog search type.
Run the logConfig command with the incident code.
Open the application server's operating-system syslog daemon.
Look up the code in the Audit Configuration page.
Where is the lowest severity level stored in IdentityIQ's Syslog configured, and what choices are available?
In log4j2.properties, with any level from TRACE to FATAL
On Global Settings > IdentityIQ Configuration > Miscellaneous, with FATAL, ERROR, or WARN
On the Audit Configuration page, with Success or Failure
In the Administrator Console, per host
Why is the Server field in Syslog search especially valuable?
It shows which database server stored the event.
It identifies the SMTP server used for alerts.
It lists the servers in the Access History database.
It identifies which IdentityIQ host raised the exception, which helps isolate problems in a clustered environment.
Syslog events older than the configured number of days are still in the database. Which task option removes them?
Refresh Role Indexes
Full Text Index Refresh
Perform Maintenance with Prune syslog events enabled
Account Aggregation with Detect deleted accounts
Sections you finish are checked off in the contents.