Odoo Performance Troubleshooting: Unleash 7 Powerful Optimization Strategies

Source Video: Odoo Experience 2025: Odoo Performance Troubleshooting – Hall 11B Day 2 AM

Imagine this: It’s early morning, you’re enjoying your coffee, when suddenly your phone buzzes. A client is in distress, their Odoo database is inaccessible, and everything is excruciatingly slow. As a dedicated Odoo partner, your first instinct is to dive into the monitoring tools, and what you see is alarming: CPU bottlenecks, concurrent requests piling up, bad gateway errors, and response times soaring above four seconds. Nothing is working.

This scenario highlights a critical need for effective Odoo Performance Troubleshooting. Understanding what happened and, more importantly, how to identify the root cause, is your superpower. This comprehensive guide will equip you with the essential tools and a step-by-step approach to diagnose and resolve almost 80% of your Odoo performance issues. We’ll delve into the twin pillars of performance analysis: Observability and Traceability, and even touch upon a common bottleneck often overlooked – document generation.

The Essential Toolkit for Robust Odoo Performance Troubleshooting

To effectively tackle any Odoo performance issue, you need two fundamental capabilities:

1. Observability (Monitoring): This is about understanding when something happens. It provides real-time insights into your server and software’s health, allowing you to pinpoint periods of strain.

   • For Odoo.sh users: You automatically get access to built-in monitoring dashboards.
   • For On-Premise deployments: You can implement powerful monitoring solutions like Prometheus for data collection and Grafana for visualizing hardware resources and application metrics.

2. Traceability (Logging): Once you know when a problem occurred, traceability helps you understand what specifically happened. This involves analyzing historical data stored in your Odoo logs.

   • Odoo.sh Logs: Provide access to module update logs, build update logs, and crucial PG slow request logs, which record any PostgreSQL query taking over 30 seconds.
   • On-Premise Logs: You’ll examine the output from your Odoo bin executable, which details application activities and errors.

The main goal of monitoring isn’t to tell you what went wrong, but when. Over a week-long period, a recurring performance dip might coincide with specific business hours, end-of-day operations, or automated tasks. Monitoring helps you narrow down that timeframe, allowing you to then dig into the logs for specifics.

Decoding Observability: Monitoring Graphs Explained

Let’s explore key monitoring graphs and what they reveal about your Odoo system’s health, offering vital clues for Odoo Performance Troubleshooting.

CPU Graph: Unmasking Processing Bottlenecks

The CPU graph is cumulative, meaning 100% represents one worker fully utilized. For an 8-worker database, peaking at 400% indicates 50% overall capacity usage.

• Green: Indicates Python-side processing. This is typically where most of Odoo’s application logic resides.
• Blue: Represents database operations, primarily PostgreSQL queries. High blue spikes suggest database-level bottlenecks.
• Red: Signifies administrator actions, such as direct commands executed in Jupyter Lab, the shell, or a terminal. Unexpected red spikes can point to manual interventions causing issues.
• Yellow: Denotes cron jobs and other time-based automated actions. A large yellow spike might mean a problematic cron job is consuming excessive resources.

A healthy Odoo database typically shows a CPU usage of around 70% green (Python) and 20-25% blue (database). If you see significant deviations, like a massive blue spike, it’s a clear signal for further investigation into your database queries.

Memory Graph: Spotting Resource Hogs

This graph tracks the memory consumption of your Odoo container. Each worker is typically allocated about 2 GB of memory, which is not cumulative per request. So, if you have 10 workers, it doesn’t mean a single request gets 20 GB; it means each worker can use up to 2 GB for its processing.

• General Trends: Useful for identifying long-term memory growth, perhaps due to large imports or sustained heavy usage.
• Limitations: The graph samples at intervals (e.g., every five seconds), so sudden, short-lived memory spikes (e.g., signing an enormous architectural document that temporarily exceeds a container’s limit) might not appear. These often manifest as “out of memory” (OOM) errors.
• Red Line: Crucially, a red line on this graph indicates a code commit from a custom module. If performance issues or memory errors appear immediately after a red line, the problem is highly likely rooted in your newly deployed custom code. This insight significantly speeds up Odoo Performance Troubleshooting.

Request Graph: Understanding Your System’s Load

The request graph shows the total number of incoming requests to your Odoo container, highlighting errors and rate limiting.

• Rate Limiting: If incoming requests exceed your worker capacity, they are queued. Odoo is designed to queue requests, preventing immediate failures.
• Bad Gateway Errors: However, if the queue becomes full, the Odoo.sh platform (or your on-premise proxy) will withdraw requests, leading to “Bad Gateway” errors (HTTP 502/504).
• Investigating Causes: A sudden spike in requests leading to bad gateways could indicate a volume issue (e.g., a Black Friday sale, a bot scanning your site) or resource contention. This graph helps in appropriately sizing your database and worker count for anticipated loads.

Concurrency Requests Graph: Sizing Your Database Effectively

This graph is vital for identifying bottlenecks and congestion. It directly influences how you should size your Odoo database.

• Capacity Benchmark: On average, an Odoo worker can handle approximately eight concurrent requests. This gives you a baseline for your system’s capacity.
• Analysis: If you see sustained high concurrency (e.g., consistently above 40 for a 5-worker setup), it points to one of two issues: either a genuinely high volume of simultaneous users, or a few specific, slow requests that are “hogging” resources, preventing other requests from being processed. This is a prime area for Odoo Performance Troubleshooting.

Average Response Time: Pinpointing Slow Operations

The average response time graph indicates how long, on average, it takes Odoo to process requests.

• Aggregation Caveat: Be aware that monitoring data is often aggregated over time, meaning sharp, brief spikes in response time might be smoothed out and less apparent.
• Best Practice: For more granular insight, focus on the average response time over the last 24 hours, where sampling is typically more frequent. This allows you to better spot sudden increases in usage or specific events that correlate with performance degradation. If you observe a suspicious peak at a particular hour, it’s time to investigate your logs for that specific timeframe.

Deep Dive into Traceability: Unraveling Odoo Logs

Once monitoring helps you identify when an issue occurred, your logs become the detective’s magnifying glass, revealing what went wrong. While many log warnings can be ignored, specific error types are crucial for Odoo Performance Troubleshooting.

Concurrency Errors: Navigating Data Conflicts

Odoo, using PostgreSQL, operates in a “repeatable read” serialization mode. This means a transaction takes a snapshot of the database at its start. If two parallel requests try to modify the same record, for data consistency, the first one to commit wins, and the second is rolled back.

• Serialization Failures: These occur when a transaction is rolled back due to conflicting modifications.
  • Normal Occurrence: A few occasional serialization errors are not usually a problem. Odoo automatically retries these transactions up to five times, and often the second attempt succeeds.
  • Problematic Wave: A constant, non-stop stream of these errors, however, signals a significant performance bottleneck. Common triggers include many users simultaneously marking a discuss channel as read or a high volume of website visitors.
• Deadlocks: This is a more severe concurrency issue where two or more transactions are waiting on each other to release resources, creating a circular dependency.
  • PostgreSQL Detected Deadlocks: PostgreSQL automatically detects and aborts one of the transactions, which is then retried. You’ll see “deadlock detected” in the logs. Like serialization errors, occasional occurrences are not a concern if they are not persistent.
  • Python/PostgreSQL Deadlocks: These are far more insidious because they are not directly logged by PostgreSQL. They often occur when custom code opens a second cursor within a transaction, implicitly creating dependencies that lead to a waiting loop between Python and the database.
    • Diagnosis: Requires real-time monitoring of PostgreSQL activity (e.g., using pg_activity) to observe blocking and waiting queries. If you can reproduce the issue, running a profiler can help trace the code path and identify the specific queries acquiring locks. Understanding these complex interactions is key to advanced Odoo Performance Troubleshooting.

Operational Errors: Tackling Incorrect Code & Zombie Crons

These errors often indicate programming mistakes or inefficient processes.

• Bad Queries: These are usually symptoms of incorrectly constructed SQL queries (e.g., passing a False value into a list of integers). While occasional bad queries might not be a performance issue on their own, they become critical if they occur within cron jobs.
• The “Zombie Cron” Problem: If a cron job encounters an unhandled exception and rolls back its transaction, its next execution date isn’t updated. This means it will repeatedly re-trigger itself, fail, and re-trigger, endlessly hogging resources.
  • Solution: The Commit Progress API: Odoo introduced an API called commit_progress to address this. This API changes how long-running cron jobs are processed. Instead of one massive transaction, jobs are processed in batches (e.g., 20 records at a time). After each batch, commit_progress commits the changes and frees any acquired locks, then triggers the cron to execute again immediately for the next batch. This prevents long-held locks and allows other database operations to proceed smoothly. Furthermore, if a cron fails repeatedly (e.g., more than five times), it’s automatically archived, and a notification is sent to the Odoo administrator, preventing it from becoming a zombie. You can find documentation on commit_progress within Odoo’s official documentation.

Memory Errors: Diagnosing Hidden Resource Overloads

Memory errors are notoriously tricky because the logs often just state that a process was killed due to memory, without detailing which specific request caused it.

• Common Symptoms: You often lose connection to your Odoo server, only for it to be immediately restored after performing a specific action. For example, you post a large invoice, it hangs, then you get connection lost/restored notifications, and the record hasn’t saved. This is almost always a memory error.
• Investigation Tools:
  • memray (Bloomberg): A state-of-the-art Python memory profiler. You can typically take a local dump of your database, remove memory limits, attach memray to the Odoo process, and reproduce the problematic flow. It will then generate a detailed graph showing which parts of your code consume the most memory.
  • Odoo’s Integrated Memory Profiler: Odoo now includes its own memory profiler, making initial diagnosis much easier by avoiding the need to download a database dump locally.
• Typical Causes: Excessive prefetching of HTML fields with base64 images, reading large attachments, or inefficient filtering operations. These are often fixable issues that, once addressed, significantly improve Odoo Performance Troubleshooting outcomes.

Dump Stacks: Instant Snapshots of Problematic Requests

Dump stacks are invaluable for Odoo Performance Troubleshooting. They are generated when a request times out, or when a quit signal is explicitly sent to an Odoo worker.

• Triggering: If you have a long-running request that hasn’t timed out yet, you can send a kill -3 signal to the Odoo bin process (odoo-bin). Odoo will catch this signal, dump the full stack trace into the logs, and not quit the operation. Repeating this a few times provides multiple snapshots of where the code was executing during the slowdown.
• Information Provided: The stack trace includes crucial details like the user who made the request, the model involved, and three “magic numbers” for performance analysis:
  1. Query Count: Number of SQL queries executed.
  2. Query Time: Total time spent in SQL.
  3. Python Time: The remaining time, assumed to be Python processing time.
     • Example: Seeing 900 seconds of Python time means a 15-minute timeout likely occurred during Python code execution. This directly points to the area needing optimization.

Advanced Log Analysis: Tools and Techniques for Odoo Performance Troubleshooting

Analyzing log files, which can often be several gigabytes for a single day on a large database, requires specialized tools.

• lnav (Log Navigator): A powerful command-line tool (lnav.org) that parses logs, injects them into an SQLite database, and allows you to run SQL queries directly on your log data.
  • Histograms: lnav can generate histograms of request frequencies, errors, and warnings, providing a visual correlation with your monitoring graphs. This helps you quickly zoom into specific problematic timeframes (e.g., a spike in requests around 7:30 AM).
  • Aggregate Queries: You can run SQL queries to calculate aggregated database load (e.g., SUM(request_time * request_count)). This load can be correlated with the “surface” of your CPU graph, helping identify the most resource-intensive requests. For instance, two specific requests might account for 80% of your database’s load, immediately highlighting them for investigation.
  • Filtering: Filter logs by IP address to identify frequent visitors, potential bots, or services that might be causing unusual load patterns. This level of detail is crucial for precise Odoo Performance Troubleshooting.

Addressing a Specific Bottleneck: Document Generation Performance

While focusing on general Odoo Performance Troubleshooting, it’s vital not to overlook specific, often deeply embedded, bottlenecks. A prime example highlighted in Odoo development is document generation. Historically, Odoo has relied on WKHTMLtoPDF for rendering documents.

• The WKHTMLtoPDF Problem:
  • Deprecated: The tool has been deprecated since 2020, meaning no further updates or bug fixes.
  • Old WebKit Engine: It uses a WebKit engine from 2014, making it incompatible with modern CSS and HTML standards, leading to broken fonts, missing text, and images—unacceptable for critical business documents.
  • Inefficient Process: Conceptually, WKHTMLtoPDF is highly inefficient. It creates a hidden browser window, loads the document, then loads it again for print preview, and then a third time for PDF output. This triples the workload for a simple task.
  • Resource Intensive: This multi-step process results in exponential CPU time and memory usage, making it a significant drain on Odoo’s resources, especially under high load.
  • Dependency on Odoo Workers: It needs Odoo to respond to asset requests (images, fonts). If Odoo has only one worker and it’s tied up, WKHTMLtoPDF can hang, creating a deadlock situation.
• Introducing Paper Manure: Odoo’s Innovative Solution:
  Recognizing these profound limitations, Odoo developed Paper Manure, a brand-new, purpose-built document generator designed from scratch. Paper Manure aims to be a lightweight, fast, and secure alternative for converting HTML and CSS to PDF.
  • Efficiency: It simplifies the process dramatically, aiming to load a document once and directly output to PDF, significantly reducing CPU and memory footprint compared to WKHTMLtoPDF.
  • Modern Web Standards: Built to support contemporary HTML and CSS, ensuring reliable and accurate document rendering.
  • Performance Focus: Optimized for document generation rather than interactive web browsing, prioritizing speed and minimal memory consumption to alleviate a common Odoo performance bottleneck.
  • Security: Incorporates sandboxing technologies (Linux seccomp and namespaces) to isolate the rendering process, containing potential bugs and enhancing system security.
  • Impact on Troubleshooting: By replacing WKHTMLtoPDF, Paper Manure eliminates a major source of system slowdowns, memory errors, and general unreliability related to document printing, contributing significantly to overall Odoo Performance Troubleshooting efforts. While still in alpha, it promises a substantial leap forward in Odoo’s document generation capabilities, directly improving system responsiveness and stability.

Conclusion: Mastering Your Odoo Performance

Effective Odoo Performance Troubleshooting is not just about reacting to problems; it’s about proactively understanding your system’s behavior. By leveraging the power of observability (monitoring) to identify when issues occur and traceability (logging) to understand what caused them, you gain a powerful capability.

Whether you’re diagnosing CPU spikes, memory leaks, database deadlocks, or slow cron jobs, the structured approach outlined here—from interpreting graphs to deep-diving into log analysis with tools like lnav—provides a clear path to resolution. Even seemingly isolated issues, like inefficient document generation, can have a profound impact on overall system responsiveness. Recognizing and addressing these bottlenecks, perhaps through innovative solutions like Paper Manure, is crucial for maintaining a healthy and efficient Odoo environment.

Remember, complex performance issues might require assistance. Don’t hesitate to open a ticket with Odoo’s support team. They can help analyze if the issue stems from Odoo’s core, your custom code, or an automated action, and propose the necessary fixes. Your superpower lies in understanding the indicators and pinpointing the root cause, ensuring your Odoo system runs smoothly and efficiently for all your clients.

Share Your Thoughts: Have you faced challenging Odoo performance issues? What tools and techniques have you found most effective in your Odoo Performance Troubleshooting journey? Let us know in the comments below!