How to Enable Debug Logging on Tableau Server
When your Tableau Server runs into a mysterious error or a tough performance bottleneck, the standard application logs might not give you enough detail to find the cause. To dig deeper, you'll need to enable debug logging. This article will guide you through the process of enabling debug logging, collecting the necessary files, and disabling it safely when you're done.
Why (and When) to Use Debug Logging
Think of your Tableau Server's standard logs as a summary of daily activities. They tell you what happened - a view loaded, a data source refreshed - but not always the nitty-gritty details of how or why. Debug logs switch your server into a highly detailed diagnostic mode, recording thousands of intricate operations happening under the hood.
This level of detail is unnecessary for everyday monitoring but is essential for troubleshooting specific, tricky issues. Here are a few common scenarios where enabling debug logging is the right move:
- Recurring, Unexplained Errors: When users are consistently getting an error message but the cause isn't obvious from the standard logs or the on-screen prompt.
- Performance Issues: If a specific dashboard is suddenly taking minutes to load instead of seconds, debug logs for the VizQL Server process can help pinpoint the exact query or rendering step that's causing the slowdown.
- Working with Tableau Support: If you've opened a case with Tableau Support, they will almost always ask you to enable debug logging, reproduce the issue, and send them the log archive. Providing these logs promptly helps them diagnose your problem much faster.
- Complex User Session Problems: Troubleshooting issues related to user permissions, specific data source connections, or inconsistent behavior across sessions.
The key is to use it as a temporary diagnostic tool. You turn it on, replicate the problem, collect the evidence, and turn it right back off.
Important Considerations Before You Start
Enabling debug logging is a powerful troubleshooting step, but it's not without risks. Here are a few critical things to keep in mind before you proceed.
It Will Impact Server Performance
This is the most important consideration. Debug-level logging is resource-intensive. Your server will be writing significantly more data to disk, consuming more CPU and memory to process and record these granular events. You will likely notice a performance slowdown while it's active. For this reason, you should never leave debug logging enabled permanently. Only use it for short periods when actively troubleshooting an issue, ideally during off-peak hours if possible.
Free PDF Guide
AI for Data Analysis Crash Course
Learn how to get AI to do data analysis for you — the best tools, prompts, and workflows to go from raw data to insights without writing a single line of code.
You Need Administrator Access
To change logging levels, you need administrator privileges on the machine running Tableau Server and the ability to use the Tableau Services Manager (TSM) command-line interface.
Target Specific Processes
Tableau Server is made up of several different services, or "processes," that handle a variety of tasks (like rendering views, running background jobs, handling web requests, etc.). Instead of enabling debug logging for the entire server, it's much more efficient to target only the process related to your issue. Some common processes you might debug include:
- VizQL Server (vizqlserver): Handles rendering visualizations and executing queries for views. Debug this for slow dashboard loading, rendering errors, and issues with user-facing interactivity.
- Application Server (vizportal): Manages the web application, user permissions, and content management. Debug this for login issues, permission problems, and strange portal behavior.
- Backgrounder (backgrounder): Manages scheduled extract refreshes, subscriptions, and other background tasks. Debug this for failing extracts or subscription failures.
- Data Server (dataserver): Manages Tableau Server data source connections. Debug this for issues with published data sources or connection errors.
Check Your Disk Space
Debug logs can grow incredibly fast and consume gigabytes of disk space in a short amount of time. Before starting, quickly check the available disk space on your server nodes to ensure you won't run into any issues.
Step-by-Step: Enabling Debug Logging with TSM
The standard way to manage logging levels is through the TSM command-line interface. Let's walk through the steps to enable debug logging for a specific process - we'll use the VizQL Server in our example.
Step 1: Open an Authenticated Command Prompt or Terminal
First, you need to open a Command Prompt (on Windows) or Terminal session (on Linux) as an administrator on the primary Tableau Server node.
Step 2: Find the Correct Configuration Key
Each process has a unique configuration "key" that controls its log level. You'll need to know the specific key for the service you're troubleshooting. Here are some of the most common keys:
- VizQL Server:
vizqlserver.native_api.log.level - Application Server (Vizportal):
vizportal.log.level - Backgrounder:
backgrounder.log.level - Data Server:
dataserver.log.level - API server:
api.server.log.level
Step 3: Set the Logging Level to 'debug'
Now, you will use the tsm configuration set command to change the log level from the default (usually 'info') to 'debug'. The command follows this pattern: tsm configuration set -k <key> -v <value>
For our VizQL Server example, the command would be:
tsm configuration set -k vizqlserver.native_api.log.level -v debug
After you run this command, TSM will let you know this change is now pending.
Step 4: Apply the Pending Changes
Your change won't take effect until you apply it. To do this, run:
tsm pending-changes apply
Heads up: Applying pending configuration changes will automatically restart the Tableau Server services. This will result in a brief period of downtime for your users, so be sure to plan for this interruption. Once the services are restarted, debug logging for the specified process will be active.
Reproducing the Issue and Collecting Logs
With logging enabled, it's time to capture the event you're trying to diagnose.
- Reproduce the Issue: As quickly as possible after the server restarts, perform the exact actions that trigger the error or performance issue.
- Note the Time: Make a note of the exact time the issue occurred. This timestamp is crucial for finding the right entries in the log files.
- Generate a Log Archive: Go back to your TSM command line and generate a zipped archive of the logs. The command is
tsm maintenance ziplogs. Using flags to narrow down the time window makes the archive much smaller and easier to manage.
For example, you can create a .zip file named "debug-viz_issue.zip" containing logs from today:
tsm maintenance ziplogs -d -f debug-viz-issue.zip
Tableau will save the zip file in a directory you can locate by running tsm configuration get -k basefilepath.log_archive.
Once you've saved the log bundle, you are ready to move on to the final and most important step: disabling debug mode.
Free PDF Guide
AI for Data Analysis Crash Course
Learn how to get AI to do data analysis for you — the best tools, prompts, and workflows to go from raw data to insights without writing a single line of code.
How to Disable Debug Logging
As soon as you have captured the logs you need, you must revert the logging level back to its default state to prevent further performance degradation and excessive disk space usage. The default level is typically 'info'.
Step 1: Set the Logging Level Back to 'info'
Using the same command as before, simply replace 'debug' with 'info'. For our example, the command is:
tsm configuration set -k vizqlserver.native_api.log.level -v info
Step 2: Apply the Changes
Just like before, you must apply the pending change to make it take effect. This will also cause a brief restart of server services.
tsm pending-changes apply
Once the server comes back online, it will be operating with its normal logging level, and you can breathe a sigh of relief.
Final Thoughts
Enabling Tableau Server's debug logging is an essential skill for any admin tasked with solving tough problems. By temporarily increasing the verbosity of a specific process with TSM, you can get the detailed evidence needed for a quick diagnosis, either on your own or with the help of Tableau Support. Just remember to always revert the settings back to their defaults when you are finished.
Spending hours digging through server logs to diagnose a problem can be a slow, manual chore. We think getting performance insights shouldn't be that complicated. That's why we built Graphed. We automate the whole process by connecting directly to your key data sources - like Google Analytics, Shopify, and your CRM - so you can use simple, natural language to build real-time dashboards and get answers in seconds. It frees you from the manual work, letting you focus on the insights that drive decisions, not the low-level investigation.
Related Articles
Facebook Ads for Gyms: The Complete 2026 Strategy Guide
Master Facebook advertising for your gym in 2026. Learn the proven 6-section framework, targeting strategies, and ad formats that drive memberships.
Facebook Ads for Home Cleaners: The Complete 2026 Strategy Guide
Learn how to run Facebook ads for home cleaners in 2026. Discover the best ad formats, targeting strategies, and budgeting tips to generate more leads.
Facebook Ads for Pet Grooming: The Complete 2026 Strategy Guide
Learn how to run Facebook ads for pet grooming businesses in 2025. Discover AI-powered creative scaling, pain point discovery strategies, and the new customer offer that works.