[mapserver-commits] r10146 - in branches/branch-5-6/docs/en: images
optimization
svn at osgeo.org
svn at osgeo.org
Fri May 7 15:46:35 EDT 2010
Author: jmckenna
Date: 2010-05-07 15:46:35 -0400 (Fri, 07 May 2010)
New Revision: 10146
Added:
branches/branch-5-6/docs/en/images/iis-debug.png
branches/branch-5-6/docs/en/optimization/debugging.txt
Modified:
branches/branch-5-6/docs/en/optimization/index.txt
Log:
new MapServer Debugging document (ticket:2854)
Added: branches/branch-5-6/docs/en/images/iis-debug.png
===================================================================
(Binary files differ)
Property changes on: branches/branch-5-6/docs/en/images/iis-debug.png
___________________________________________________________________
Added: svn:mime-type
+ application/octet-stream
Added: branches/branch-5-6/docs/en/optimization/debugging.txt
===================================================================
--- branches/branch-5-6/docs/en/optimization/debugging.txt (rev 0)
+++ branches/branch-5-6/docs/en/optimization/debugging.txt 2010-05-07 19:46:35 UTC (rev 10146)
@@ -0,0 +1,534 @@
+.. _debugging:
+
+*****************************************************************************
+ Debugging MapServer
+*****************************************************************************
+
+:Author: Jeff McKenna
+:Contact: jmckenna at gatewaygeomatics.com
+:Revision: $Revision: 9846 $
+:Date: $Date: 2010-02-21 12:40:26 -0400 (Sun, 21 Feb 2010) $
+
+.. contents:: Table of Contents
+ :depth: 3
+ :backlinks: top
+
+Introduction
+============
+
+When developing an application for the Internet, you will inevitably across problems many problems
+in your environment. The goal of this guide is to assist you with locating the problem
+with your MapServer application.
+
+Links to Related Information
+----------------------------
+
+- :ref:`RFC 28: Redesign of LOG/DEBUG output mechanisms <rfc28>`
+- :ref:`MapServer Errors <errors>`
+
+Steps to Enable MapServer Debugging
+===================================
+
+Starting with MapServer 5.0, you are able to control the levels of debugging/logging
+information returned to you by MapServer, and also control the location of the output
+log file.
+
+In technical terms, there are msDebug() calls in various areas of the MapServer code that generate
+information that may be useful in tuning and troubleshooting applications.
+
+Step 1: Set the MS_ERRORFILE Variable
+-------------------------------------
+
+The **MS_ERRORFILE** variable is used to specify the output of debug messages from MapServer.
+You can pass the following values to **MS_ERRORFILE**:
+
+**[filename]**
+ Full path and filename of a log file, to contain MapServer's debug messages. Any file extension
+ can be used, but *.log* or *.txt* is recommended. The file will be created, if it does not
+ already exist.
+
+**stderr**
+ Use this to send MapServer's debug messages to the Web server's log file (i.e. "standard error").
+ If you are using Apache, your debug messages will be placed in the Apache *error_log* file.
+ If you are using Microsoft IIS, your debug messages will be sent to *stdout*
+ (i.e. the browser), so its use is discouraged. With IIS it is recommended to direct output to a file
+ instead.
+
+**stdout**
+ Use this to send MapServer's debug messages to the standard output (i.e. the browser), combined with
+ the rest of MapServer's output.
+
+**windowsdebug**
+ Use this to send MapServer's debug messages to the Windows OutputDebugString API, allowing the use of
+ external programs like SysInternals debugview to display the debug output.
+
+
+Through the Mapfile
+*******************
+
+The recommended way to set the **MS_ERRORFILE** variable is in your mapfile, within the :ref:`MAP` object,
+such as:
+
+.. code-block:: mapfile
+
+ MAP
+ ...
+ CONFIG "MS_ERRORFILE" "/ms4w/tmp/ms_error.txt"
+ ...
+ LAYER
+ ...
+ END
+ END
+
+Through an Environment Variable
+*******************************
+
+You can also set the **MS_ERRORFILE** variable as an environment variable on your system. Apache
+users can set the environment variable in Apache's *httpd.conf* file, such as:
+
+::
+
+ SetEnv MS_ERRORFILE "/ms4w/tmp/ms_error.txt"
+
+Windows users can alternatively set the environment variable through the Windows System
+Properties; but make sure to set a SYSTEM environment variable.
+
+.. NOTE::
+ If both the *MS_ERRORFILE* environment variable is set and a *CONFIG MS_ERRORFILE* is also set,
+ then the CONFIG directive takes precedence.
+
+Step 2: Set the DEBUG Level
+---------------------------
+
+You can retrieve varying types of debug messages by setting the *DEBUG* parameter in the :ref:`mapfile`.
+You can place the *DEBUG* parameter in any LAYER in the mapfile, or instead, set it once in the MAP
+object so that it applies to each layer. Use the value of the *DEBUG* parameter to set the type of information
+returned, as follows:
+
+DEBUG Levels
+************
+
+**Level 0**
+ Errors only (DEBUG OFF, or DEBUG 0)
+
+ In level 0, only msSetError() calls are logged to MS_ERORFILE. No msDebug() output at all.
+ This is the default and corresponds to the original behavior of MS_ERRORFILE in MapServer 4.x
+
+**Level 1**
+ Errors and Notices (DEBUG ON, or DEBUG 1)
+
+ Level 1 includes all output from Level 0 plus msDebug() warnings about common pitfalls, failed
+ assertions or non-fatal error situations (e.g. missing or invalid values for some parameters,
+ missing shapefiles in tileindex, timeout error from remote WMS/WFS servers, etc.)
+
+**Level 2**
+ Map Tuning (DEBUG 2)
+
+ Level 2 includes all output from Level 1 plus notices and timing information useful for tuning
+ mapfiles and applications. *this is the recommended minimal debugging level*
+
+**Level 3**
+ Verbose Debug (DEBUG 3)
+
+ All of Level 2 plus some debug output useful in troubleshooting problems such as WMS connection
+ URLs being called, database connection calls, etc.
+
+**Level 4**
+ Very Verbose Debug (DEBUG 4)
+
+ Level 3 plus even more details...
+
+**Level 5**
+ Very Very Verbose Debug (DEBUG 5)
+
+ Level 4 plus any msDebug() output that might be more useful to developers than to users.
+
+
+Mapfile Example
+***************
+
+The following example is the recommended method to set the *DEBUG* parameter:
+
+.. code-block:: mapfile
+
+ MAP
+ ...
+ CONFIG "MS_ERRORFILE" "/ms4w/tmp/ms_error.txt"
+ DEBUG 5
+ ...
+ LAYER
+ ...
+ END
+ END
+
+The MS_DEBUGLEVEL Environment Variable
+**************************************
+
+Instead of setting the *DEBUG* Debug level in each of your mapfiles, you can also be set
+the level globally by using the *MS_DEBUGLEVEL* environment variable.
+
+When set, this value is used as the default debug level value for all map and layer objects as they
+are loaded by the mapfile parser. This option also sets the debug level for any msDebug() call
+located outside of the context of a map or layer object, for instance for debug statements relating
+to initialization before a map is loaded. If a DEBUG value is also specified in the mapfile in
+some map or layer objects then the local value (in the mapfile) takes precedence over the
+value of the environment variable.
+
+Apache users can set the environment variable in Apache's *httpd.conf* file, such as:
+
+::
+
+ SetEnv MS_DEBUGLEVEL 5
+
+Windows users can alternatively set the environment variable through the Windows System
+Properties; but make sure to set a SYSTEM environment variable.
+
+Step 3: Turn on CPL_DEBUG (optional)
+------------------------------------
+
+MapServer relies on the `GDAL <http://www.gdal.org/>`__ library to access most data layers, so
+you may wish to turn on GDAL debugging, to hopefully get more information on how GDAL is accessing
+your data file. This could be very helpful for problems with accessing raster files and PostGIS
+tables. You can trigger this GDAL output by setting the **CPL_DEBUG** variable in your mapfile,
+within the :ref:`MAP` object, such as:
+
+.. code-block:: mapfile
+
+ MAP
+ ...
+ CONFIG "CPL_DEBUG" "ON"
+ ...
+ LAYER
+ ...
+ END
+ END
+
+Step 4: Test your Mapfile
+-------------------------
+
+Once you have set the *MS_ERRORFILE* and *DEBUG* level in your mapfile, you should now test
+your mapfile and read your generated log file.
+
+Using shp2img
+*************
+
+The recommended way to test your mapfile is to use the MapServer commandline utility :ref:`shp2img`,
+to verify that your mapfile creates a valid map image. :ref:`shp2img` should be included in your MapServer
+installation (`MS4W <http://www.maptools.org/ms4w>`__ users need to execute *setenv.bat* before
+using the utility).
+
+You can set the *DEBUG* level by passing the :ref:`shp2img` following parameters to your commandline call:
+
+.. NOTE::
+ If you have already set *MS_ERRORFILE* and *DEBUG* in your mapfile, you must comment these out
+ in order to use these :ref:`shp2img` options
+
+-all_debug
+^^^^^^^^^^
+
+Use this setting to set the debug level for the MAP object and all layers. *this is the recommended switch
+to use*
+
+::
+
+ shp2img -m spain.map -o test.png -all_debug 5
+
+ msLoadMap(): 0.002s
+ msDrawMap(): Layer 0 (spain provinces), 0.012s
+ msDrawRasterLayerLow(orthophoto): entering.
+ msDrawGDAL(): src=0,0,3540,2430, dst=188,48,1,1
+ source raster PL (-793.394,-1712.627) for dst PL (188,48).
+ msDrawGDAL(): red,green,blue,alpha bands = 1,2,3,0
+ msDrawMap(): Layer 1 (orthophoto), 0.150s
+ msDrawMap(): Layer 2 (urban areas), 0.004s
+ msDrawMap(): Layer 3 (species at risk), 0.008s
+ msDrawMap(): Layer 4 (populated places), 1.319s
+ msDrawMap(): Drawing Label Cache, 0.014s
+ msDrawMap() total time: 1.513s
+ msSaveImage() total time: 0.039s
+ msFreeMap(): freeing map at 0218C1A8.
+ freeLayer(): freeing layer at 0218F5E0.
+ freeLayer(): freeing layer at 030C33A0.
+ freeLayer(): freeing layer at 030C3BC8.
+ freeLayer(): freeing layer at 030C4948.
+ freeLayer(): freeing layer at 030C7678.
+ shp2img total time: 1.567s
+
+-map_debug
+^^^^^^^^^^
+
+Use this setting to set the debug level for the MAP object only.
+
+::
+
+ shp2img -m spain.map -o test.png -map_debug 5
+
+ msDrawMap(): Layer 0 (spain provinces), 0.012s
+ msDrawRasterLayerLow(orthophoto): entering.
+ msDrawMap(): Layer 1 (orthophoto), 0.144s
+ msDrawMap(): Layer 2 (urban areas), 0.004s
+ msDrawMap(): Layer 3 (species at risk), 0.008s
+ msDrawMap(): Layer 4 (populated places), 1.323s
+ msDrawMap(): Drawing Label Cache, 0.013s
+ msDrawMap() total time: 1.511s
+ msSaveImage() total time: 0.039s
+ msFreeMap(): freeing map at 0205C1A8.
+
+-layer_debug
+^^^^^^^^^^^^
+
+Use this setting to set the debug level for one layer object only.
+
+::
+
+ shp2img -m spain.map -o test.png -layer_debug orthophoto 5
+
+ msDrawRasterLayerLow(orthophoto): entering.
+ msDrawGDAL(): src=0,0,3540,2430, dst=188,48,1,1
+ source raster PL (-793.394,-1712.627) for dst PL (188,48).
+ msDrawGDAL(): red,green,blue,alpha bands = 1,2,3,0
+ msDrawMap(): Layer 1 (orthophoto), 0.151s
+ freeLayer(): freeing layer at 02F23390.
+
+Set CPL_DEBUG
+^^^^^^^^^^^^^
+
+At the commandline execute the following:
+
+::
+
+ set CPL_DEBUG=ON
+
+ shp2img -m spain.map -o test.png -layer_debug orthophoto 5
+
+ msDrawRasterLayerLow(orthophoto): entering.
+ GDAL: GDALOpen(D:\ms4w\apps\spain\map/.\../data/ov172068_200904_c100u50x75c24n.jpg, this=0
+ 4059840) succeeds as JPEG.
+ msDrawGDAL(): src=0,0,3540,2430, dst=188,48,1,1
+ source raster PL (-793.394,-1712.627) for dst PL (188,48).
+ msDrawGDAL(): red,green,blue,alpha bands = 1,2,3,0
+ GDAL: GDALDefaultOverviews::OverviewScan()
+ msDrawMap(): Layer 1 (orthophoto), 0.155s
+ freeLayer(): freeing layer at 03113390.
+ GDAL: GDALDeregister_GTiff() called.
+
+Reading Errors Returned by shp2img
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If there is a problem with your mapfile, :ref:`shp2img` should output the line number in your
+mapfile that is causing the trouble. The following tells us that there is a problem on line 85
+of my mapfile:
+
+::
+
+ getSymbol(): Symbol definition error. Parsing error near (truetype2):(line 85)
+
+If you are using mapfile :ref:`INCLUDEs <include>`, it may be tricky to track down this line number,
+but most of the time the line number is useful.
+
+Using mapserv CGI
+*****************
+
+Another handy way to test your mapfile is to call the mapserv CGI executable at the
+:ref:`commandline <mapserv>`, such as the following:
+
+::
+
+ mapserv -nh "QUERY_STRING=map=/ms4w/apps/spain/map/spain.map&mode=map"
+
+ON_MISSING_DATA
+***************
+
+If you are using tile indexes to access your data, you should also be aware of the
+configuration settings added in MapServer 5.4 that allow you to tell MapServer how to
+handle missing data in tile indexes. Please see the *CONFIG* parameter's *ON_MISSING_DATA* setting
+in the :ref:`map` object for more information.
+
+.. HINT::
+ You can check the attributes in the tileindex by executing "*ogrinfo -al*" on your data file
+
+Step 5: Check your Web Server Logs
+----------------------------------
+
+Once you have verified that there are no problems with you mapfile, next you should check your Web
+server log files, for any related information that may help you narrow down your problem.
+
+Apache
+******
+
+Unix users will usually find Apache's *error_log* file in a path similar to:
+
+::
+
+ /var/log/apache2/
+
+Windows users will usually find Apache's log files in a path similar to:
+
+::
+
+ C:\Program Files\Apache Group\Apache2\logs
+
+MapServer for Windows (`MS4W <http://www.maptools.org/ms4w>`__) users will find Apache's log files at:
+
+::
+
+ \ms4w\Apache\logs
+
+Microsoft IIS
+*************
+
+IIS log files can be located by:
+
+1. Go to Start -> Control Panel -> Administrative Tools
+2. Open the Internet Information Services (IIS) Manager.
+3. Find your Web site under the tree on the left.
+4. Right-click on it and choose Properties.
+5. On the Web site tab, you will see an option near the bottom that says "Active Log Format." Click on the
+ Properties button.
+
+ .. image:: ../images/iis-debug.png
+
+6. At the bottom of the General Properties tab, you will see a box that contains the log file directory
+ and the log file name. The full log path is comprised of the log file directory plus the first part
+ of the log file name, for example:
+ ::
+
+ C:\WINDOWS\system32\LogFiles\W3SVC1\ex100507.log
+
+You may also want to check the Windows Event Viewer logs, which is located at:
+
+1. Go to Start -> Control Panel -> Administrative Tools
+2. Computer Management
+3. Event Viewer
+
+.. WARNING::
+ As mentioned previously, in IIS the MapServer *stderr* debug output is returned to
+ the client instead of routed to the Web Server logs, so be sure to log the output
+ to a file, using:
+
+ ::
+
+ CONFIG "MS_ERRORFILE" "/ms4w/tmp/ms_error.txt"
+
+CGI Error - The specified CGI application misbehaved by not returning a complete set of HTTP headers
+****************************************************************************************************
+
+This error is often caused by missing DLL files. You should try to execute "*mapserv -v* at the
+commandline, to make sure that MapServer loads properly.
+
+
+Step 6: Verify your Application Settings
+----------------------------------------
+
+If you have verified that MapServer creates a valid map image through :ref:`shp2img`, you've checked
+your MapServer log files, and there are no problems noted in your Web server logs, then you should
+focus your attention on possible application configuration problems. "Application" here means how
+you are displaying your map images on the Web page, such as with `OpenLayers <http://www.openlayers.org>`__.
+
+PHP MapScript
+*************
+
+If you are using PHP MapScript in your application, here are some important notes for debugging:
+
+1. Make sure your *php.ini* file is configured to show all errors, by setting:
+
+ ::
+
+ display_errors = On
+
+
+2. To enable debugging in PHP MapScript, if you are using MapServer 5.6.0 or more
+ recent, make sure to define *ZEND_DEBUG* in the PHP source.
+
+ If you are using MapServer < 5.6.0, then:
+
+ - open the file */mapscript/php3/php_mapscript.c*
+
+ - change the following:
+
+ ::
+
+ #define ZEND_DEBUG 0
+
+ to
+
+ #define ZEND_DEBUG 1
+
+Debugging MapServer using Compiler Debugging Tools
+==================================================
+
+Once you build MapServer in debug mode (*./configure --enable-debug*), you should be
+able to debug MapServer with most debugging tools. `GDB <http://www.gnu.org/software/gdb/>`__
+is an example of a popular debugger tool, that works well with MapServer.
+
+Debugging Older Versions of MapServer (before 5.0)
+==================================================
+
+1. Make sure that MapServer is compiled in debug mode (on unix this is
+ enabled through *./configure --enable-debug*).
+
+ You can verify that your build was compiled in debug mode, by executing
+ the following at the commandline (look for "DEBUG=MSDEBUG"):
+
+ ::
+
+ ./mapserv -v
+
+ MapServer version 4.10.2 OUTPUT=GIF OUTPUT=PNG OUTPUT=WBMP
+ OUTPUT=SVG SUPPORTS=PROJ SUPPORTS=FREETYPE SUPPORTS=WMS_SERVER
+ SUPPORTS=WMS_CLIENT SUPPORTS=WCS_SERVER SUPPORTS=THREADS SUPPORTS=GEOS
+ INPUT=EPPL7 INPUT=POSTGIS INPUT=OGR INPUT=GDAL INPUT=SHAPEFILE
+ DEBUG=MSDEBUG
+
+2. Set the *MS_ERRORFILE* variable is in your mapfile, within the :ref:`MAP` object,
+ such as:
+
+ .. code-block:: mapfile
+
+ MAP
+ ...
+ CONFIG "MS_ERRORFILE" "/ms4w/tmp/ms_error.txt"
+ ...
+ LAYER
+ ...
+ END
+ END
+
+3. If you don't use the *MS_ERRORFILE* variable, you can use the LOG parameter in
+ your :ref:`WEB` object of the mapfile, such as:
+
+ .. code-block:: mapfile
+
+ MAP
+ ...
+ WEB
+ LOG "mapserver.log"
+ END
+ ...
+ LAYER
+ ...
+ END
+ END
+
+4. Specify *DEBUG ON* in your MAP object, or in your LAYER objects, such as:
+
+ .. code-block:: mapfile
+
+ MAP
+ ...
+ WEB
+ LOG "mapserver.log"
+ END
+ DEBUG ON
+ ...
+ LAYER
+ ...
+ END
+ END
+
+5. Note that only errors will be written to the log file; all DEBUG output
+ goes to stderr, in the case of Apache that is Apache's *error_log* file. If you are
+ using Microsoft IIS, debug output is routed to *stdout* (i.e. the browser), so be sure
+ to remove *DEBUG ON* statements if using IIS on a production server.
+
+.
\ No newline at end of file
Modified: branches/branch-5-6/docs/en/optimization/index.txt
===================================================================
--- branches/branch-5-6/docs/en/optimization/index.txt 2010-05-07 19:43:43 UTC (rev 10145)
+++ branches/branch-5-6/docs/en/optimization/index.txt 2010-05-07 19:46:35 UTC (rev 10146)
@@ -7,9 +7,10 @@
.. toctree::
:maxdepth: 2
- mapfile
- vector
- raster
+ debugging
fastcgi
+ mapfile
+ raster
tileindex
+ vector
\ No newline at end of file
More information about the mapserver-commits
mailing list