Collection

Development tools and debugging

Find the active code, trace a request, and diagnose unexpected behavior.

Choose the task that matches what you need to do. The pages explain the relevant workflow and link to related guides and reference material. Examples use the local site garden; use your own site name and check the command’s scope before running it.

In this section

  1. 1Choose a development toolStart with the symptom and use the smallest tool that explains it.
  2. 2Enable the Development moduleSign in to the local site's admin as an administrator. Open the module management page, find Development (mod_development), and activate it if necessary.
  3. 3Reload the browser after source changesOpen System → Development and enable live reload. The page also enables separate CSS and JavaScript files when needed.
  4. 4Trace templates rendered by a requestOpen the Development page's Live dependency graph of templates tool. Start a trace for your session, then load the page or path you want to inspect.
  5. 5Inspect template dependenciesOpen Dependency graph of all available templates from the Development page. Use the graph to understand inheritance and include relationships before changing a shared template.
  6. 6Check template referencesOpen Cross-reference check of templates in the Development page and run the check. Read each reported reference with the active module set in mind.
  7. 7Trace a URL through dispatchOpen the Development page's dispatch tools. Inspect the list of active rules, then trace the path that produces an unexpected result.
  8. 8Find registered observersOpen Show an overview of all observers from the Development page. Find the notification and inspect the registered callbacks and their order.
  9. 9Trace database queries for your sessionEnable module#mod_server_storage if the Development page says it is needed for database tracing. On the Development page, enable Trace all database queries for the current session.
  10. 10Trace a small number of Erlang callsOpen the Development function tracing tool as the admin user. Enter a module, optionally a function, and a small limit on the number of calls.
  11. 11Distinguish stale cache data from stale codeFirst check which file is selected and whether the changed code compiled. Then repeat the request with the relevant cache disabled or flushed.
  12. 12Write logs that explain an operationLog the operation and its result with structured fields. Include an identifier that helps connect the message to a resource or job, without logging credentials or complete private request data.
  13. 13Recompile code and refresh discoveryUse compilation for changed Erlang source, loading for changed BEAM files, and an index refresh when new templates or application files are not discovered.
  14. 14Understand the optional development APIThe Development page has an option to enable an API for recompiling and rebuilding Zotonic. The model implements actions for recompiling, flushing caches, and refreshing indexes and translations.