The ESI Development Tool Enhanced and Original Versions

VISoftware and s/w Development

Oct 6, 2011 (5 years and 10 months ago)

3,077 views

Akamai Technologies, Inc.

October 7, 2010
The ESI Development Tool
Enhanced and Original Versions

Akamai Technologies, Inc.
Akamai Customer Care: 1-877-425-2832 or, for routine requests, email ccare@akamai.com
Akamai EdgeControl, for customers and resellers: http://control.akamai.com
The ESI Development Tool
Copyright © 2001–2010 Akamai Technologies, Inc. All Rights Reserved.
Reproduction in whole or in part in any form or medium without express written permission is prohibited. Akamai, the Akamai wave
logo, and the names of Akamai services referenced herein are trademarks of Akamai Technologies, Inc. While every precaution has been
taken in the preparation of this document, Akamai Technologies, Inc. assumes no responsibility for errors, omissions, or for damages
resulting from the use of the information herein. The information in these documents is believed to be accurate as of the date of this
publication but is subject to change without notice. The information in this document is subject to the confidentiality provisions of the
Terms & Conditions governing your use of Akamai services.
Other trademarks contained herein are the property of their respective owners and are not used to imply endorsement of Akamai or its
services.
US Headquarters
8 Cambridge Center
Cambridge, MA 02142
Tel: 617.444.3000
Fax: 617.444.3001
US Toll free 877.4AKAMAI (877.425.2624)
For a list of offices around the world, see:
http://www.akamai.com/html/about/locations.html
The ESI Development Tool, Enhanced and Original. Akamai Confidential. NDA Required for Release 3
Contents
Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5
Enhanced and Original Debuggers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5
If You Want To... See Page... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6
Use the Original Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6
Use the Enhanced Debugger. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6
Debug Using Curl or Telnet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6
Debug Using the ESI Code Shortcut. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6
Debug Using ETS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6
Using the Original Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7
Configuring Your PC to the Debugger Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7
Logging in and Setting Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8
Using the Enhanced Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10
Using the Coding Shortcut—esi:debug. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12
Running the Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13
Nested Reports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15
Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16
ESI Syntax Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17
Evaluation Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19
Sample ESI Debug Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23
4 The ESI Development Tool, Enhanced and Original. Akamai Confidential. NDA Required for Release
The ESI Development Tool, Enhanced and Original. Akamai Confidential. NDA Required for Release 5
The ESI Debugger
Overview
The ESI Development Tool —also known simply as the debugger— provides a way
for you to test, view, and debug your web pages containing ESI code. You can debug
your production pages, or you can set up a test origin site—a Test Origin Server—
and debug the pages on the test site before deployment or modification. When it pro-
cesses pages containing ESI code, the edge server will send back debugging informa-
tion in its reply if a debugging cookie is sent to it.
Enhanced and Original Debuggers
There are different ways to use the debugger: the Enhanced version provides a one-
stop interface that allows you to specify the URL you want to debug, then click a but-
ton and view the results.
The Original debugger requires more setup, but provides a way to view both the
resulting web page and the debug report in a browser window. You can also use a
command line method.
• Both the Original and the Enhanced
- Are available on the portal, https://control.akamai.com.
- Allow you to specify a test server to replace the origin for testing purposes.
- Do not cache for the objects being debugged, allowing modification and
testing without concern for caching issues.
- Provide identical debug reports as described in this document.
The differences can be summarized as follows:
• The Enhanced debugger:
- Allows you to specify the URL to debug, then click Submit and view the
debug report on a page that appears.
- Allows you to specify client request headers (to emulate browsers, etc.)
- Allows you to specify a client IP (to emulate content targeting (EdgeScape
GEO) data.
• The Original debugger:
- Requires some setup on your PC, but then allows you to view an ESI results
URL in a browser window, and view the source for the results to view the
debug report.
- Allows you to test from the command line with Telnet or Curl.
- Allows you to use a shortcut ESI code statement,
esi:debug
.
- Allows you to test on the ESI Test Server (ETS).
The ESI Debugger
6 The ESI Development Tool, Enhanced and Original. Akamai Confidential. NDA Required for Release
If You Want To... See Page...
Use the Original Debugger
See the procedures beginning on the next page.
Use the Enhanced Debugger
See page 10.
Debug Using Curl or Telnet
If you want to test from the command line, you follow the same setup as for the orig-
inal debugger in the procedures described beginning on the next page, but you can
send a cookie using Telnet or Curl, as described on page 13.
Debug Using the ESI Code Shortcut
You can skip the first three steps listed in “Using the Original Debugger” on the next
page first by enabling the use of an ESI debug statement in your edge server configu-
ration file, and then using the statement in your ESI code. For more information, see
page 12.
Debug Using ETS
If you’re using this debugger with the ESI Test Server (ETS), the setup described here
for the original debugger is handled automatically in ETS configuration. When you
run the ETS install program or when you reconfigure ETS as described in the ESI
Test Server Users Guide, turn on the ESI Debugging (ESID) option. Then skip the
preliminary steps in this guide and start with “Running the Debugger” on page 13.
Using the Original Debugger
The ESI Development Tool, Enhanced and Original. Akamai Confidential. NDA Required for Release 7
Using the Original Debugger
1.Do this once only for the domain you want to debug. If you change domains,
you need to repeat this step for the new domain: add a line to your computer’s
Hosts file so that the debugger can set a debugging cookie for the domain.
2.Enter the domain you wish to debug into the Portal Domain Validation Tool.
3.Log in to Akamai EdgeControl, open the debugger page and set the domain to
debug and, if necessary, set a Test Origin Server, and turn the debugger on.
4.Make a request for the ESI page using your browser or a command-line tool such
as telnet or curl.
5.Using your browser, view the source for the page to see the debug report. Or with
the command line tool, view it using your specified output device.
6.When you are finished debugging, return to the debugger portal page and turn
the debugger off.
The remainder of this discussion describes these steps and the resulting report.
Configuring Your PC to the Debugger Domain
To debug using your browser, you first need to configure a DNS option on your
desktop in order to allow the debugger to set the debugging cookie for your domain.
You do this by adding one line to your Hosts file. To add the line, you first need to
determine the debugger IP address.
You need to add a new line for each domain you want to debug.
1.To determine your debugger address, ping esid.akamai.com and make a note of
the resulting IP address. 80.67.70.29 is the IP as of this writing, but the address
can change, so ping to double-check.
2.Open your Hosts file in a text editor. The location of the file depends on your
operating system:
3.Add a line to the Hosts file in the following form:
IP_for_esid.akamai.com Debug_Domain
The IP_for_esid.akamai.com is the IP address you determined in the first step.
The Debug_Domain is a URL in the following form, and the site can be either a
secure or insecure site:
esid.name_of_the_domain_to_debug
For example, if you want to debug www.myplace.com, the Debug_Domain is:
Operating System Hosts file Location
Windows XP/WINDOWS/system32/drivers/etc/Hosts
Windows NT/2000/Winnt/System32/drivers/etc/Hosts
Windows 98/Windows/Hosts
UNIX / Linux/etc/hosts
Mac Depends on version - information can be
found at http://kbase.info.apple.com.
The ESI Debugger
8 The ESI Development Tool, Enhanced and Original. Akamai Confidential. NDA Required for Release
esid.myplace.com
Using the examples, the line would look like this:
80.67.70.29 esid.myplace.com
4.Save the changed Hosts file to disk and exit the text editor.
5.If your browser is open, close it and reopen it to apply the new configuration.
As an alternative to the above steps, you or your system administrator can configure
your DNS server to cname esid.myplace.com to esid.akamai.com.
Logging in and Setting Options
Validating Your Domains
Before using the debugger, make sure the domain you want to work on is valid and in the
Akamai system. To confirm your domains, log in to http://control.akamai.com, click the
Tools link under your product link in the sidebar, then use the Origin Domains tool.
Turning the Debugger On or Off
To turn the debugger on or off, and to set options:
1.In your browser, log into the Akamai portal at https://control.akamai.com.
2.In the navigation bar on the left, go to your product and open its submenu.
3.Click Tools under your product to open the Tools page.
4.On the Tools page, click the ESI Development Tools link under Development
Tools to open the Enhanced Debugger page.
Figure 1. Original debugger link on the Enhanced Debugger page.
5.At the top of the Enhanced Development Tool page, click the Original Develop-
ment Tool link.
Using the Original Debugger
The ESI Development Tool, Enhanced and Original. Akamai Confidential. NDA Required for Release 9
6.On this page, use the Debugging drop-down list to turn the debugger on or off.
Figure 2. Setting the Debugger
7.Specify the Debugging Domain containing the ESI content you want to debug.
This domain must be the same as the domain you used in step 3 on page 7. For
example, if you want to debug a page at www.myplace.com, you used the address
esid.myplace.com
in the Hosts file, and you would now enter
myplace.com
in
the Debugging Domain box on this page.
8.Optionally, specify a Test Origin Server—for example,
test.myplace.com
—to
use instead of your deployment origin server.
For requests to the origin, the edge server will replace the value specified in your con-
figuration file data with this test origin value.
9.Click Save.
Once you’ve clicked Save, your browser will make a connection to
esid.myplace.com
to set the debugging cookie.
This cookie will work with a secure or insecure site. While the cookie may be stored
in an insecure location on your local PC, the cookie itself is relatively secure since it is
encrypted and tied to a specific IP.
Note that the debugging cookie expires after two weeks, and when the cookie has
expired it is necessary to repeat the above steps.
Running the Debugger from a Static IP or Dynamic IP
You’re now ready to run the debugger. Note that you’ll need run the debugger from
the same IP address and PC as the one you used to set the cookie in the preceding
procedure—the best situation is to use a static IP address. If you run the debugger
from a dynamic IP address: any time your address changes, you’ll need to re-run the
preceding procedure to set the cookie on your current IP address. Because of the way
AOL handles IP addresses, you may not be able to run the debugger from an AOL
account.
The ESI Debugger
10 The ESI Development Tool, Enhanced and Original. Akamai Confidential. NDA Required for Release
Using the Enhanced Debugger
Before using either the enhanced or original debugger, of course, you must create the
ESI pages you want to debug. If you want to use a test origin server that is different
from the origin that holds your production objects, you need to set that up as well.
To use the enhanced debugger:
1.In your browser, log into the Akamai portal at https://control.akamai.com.
2.In the navigation bar on the left, go to your product and open its submenu.
3.Click Tools under your product to open the Tools page.
4.On the Tools page, click the ESI Development Tools link under Development
Tools to open the Enhanced Debugger page.
Figure 3. Setting Enhanced Debugger Options
5.On this page, specify the URL and, if desired, the other options:
- Specify the URL, the page you want to debug, for example,
http://www.example.com. This can be a secure site, but if it is, you must
specify the “https”; the default for the debugger is “http”.
Using the Enhanced Debugger
The ESI Development Tool, Enhanced and Original. Akamai Confidential. NDA Required for Release 11
- Optionally, add or modify Client Request Headers to emulate specific client
browser conditions.
- Optionally, set a Client IP to emulate a location for specific EdgeScape GEO
(geographic) data. For more information on GEO, see the EdgeScape and
EdgeScape Pro Users Guide.
- Optionally, set a Origin Server—for example,
test.example.com
—to use
instead of your deployment origin server. For requests to the origin, the edge
server will replace the origin in the URL with this test origin value. Note that
your edge server configuration must be set up to allow the edge server to
access the domain. For example, if you want to use
test.example.com
for
the test origin,
example.com
must be known to the edge server. If this is not
the case, talk to your Akamai representative.
6.Click Submit. The debug report, which is described in the next chapter, appears
on a new page.
The ESI Debugger
12 The ESI Development Tool, Enhanced and Original. Akamai Confidential. NDA Required for Release
Using the Coding Shortcut—esi:debug
You can skip both the configuration steps (page 7) and the logging-in steps (page 8)
when you use the ESI debug statement,
<esi:debug/>
, in your ESI code. The use of
the
debug
statement first must be enabled through your edge server configuration file
or by response header.
A Security and Performance Warning
When the shortcut is enabled by response header or in edge server configuration, the
debug report can be available to anyone opening the page with a browser. The short-
cut has the advantages of flexibility and speed, but it should be used with caution.
Also, enabling use of the shortcut will cause a decrease in performance for assembling
and serving the ESI results. The performance is adversely affected regardless of whether
an
<esi:debug>
statement is found and a debug report sent. For this reason, the short-
cut should be enabled only for the content you plan to debug. Moreover, for this rea-
son as well as the potential security issue, it is recommended that you do not enable
the
debug
statement for content that will be served to end users.
To use the coding shortcut:
1.Enable the use of the
debug
statement in ESI code in one of two ways:
- Have the
debug
statement enabled in your edge server configuration file. To
do this, see your Akamai representative. OR,
- Use an Edge-control response header:
Note: you can disable use of the debugging tag with an exclamation point (!):
Edge-Control: !dca-enable-debugging-tag
.
2.Place an
<esi:debug/>
statement anywhere in a template page or a fragment.
You can use the
debug
statement inside other ESI blocks such as the
choose
state-
ment. For example:
When enabled and used, the
debug
statement causes the edge server to create a debug
output report for the page and the page's children and parents. The debug report is
discussed subsequently in this document.
However, if processing fails because of a parsing error (for example, bad syntax), then
no debug report is created, because the edge server will not have processed the
esi:debug
statement. In that case, if you want to see syntax errors, you need to fol-
low the longer preparatory steps listed in this document.
Edge-Control: dca-enable-debugging-tag
<esi:choose>
<esi:when test="$(QUERY_STRING) matches 'debug'">
<esi:debug/>
</esi:when>
</esi:choose>
Running the Debugger
The ESI Development Tool, Enhanced and Original. Akamai Confidential. NDA Required for Release 13
Running the Debugger
After you have set the debugging domain and turned on the debugger, you can run it
simply by requesting the ESI-coded page in your browser. Alternatively, you can use
various command line tools. However you run the debugger, the result is a report,
discussed in the “The Debug Report” subsection that follows this one.
Using a Browser
Using your browser, simply go to the page(s) you want to debug. If the code runs suc-
cessfully, you’ll see the normal web page. View the source code and you’ll see the
report-annotated page source.
Command Line Testing Using Telnet or Curl
When you clicked Save on the esid.akamai.com page, the debugger set an encrypted
cookie on your browser. You need to find it; it looks like “Akamai-EncDebug”. You
can pass this cookie directly using curl, telnet, or your favorite command line HTTP
client. For example, using CURL at the command line:
Curl URL_to_test --cookie “Akamai-EncDebug=XYZYAY…”
The ESI Debugger
14 The ESI Development Tool, Enhanced and Original. Akamai Confidential. NDA Required for Release
The ESI Development Tool, Enhanced and Original. Akamai Confidential. NDA Required for Release 15
The Debug Report
How you view the Debug Report depends on the method you use to get it:
• Using the Enhanced Development Tool, the report appears on a new page after
you click the Submit button.
• Running the original debugger, the debug report is hidden in the browser page
you see when view the ESI results—the URL in your browser. You view the
source code (e.g., choose Source or Page Source on the browser’s View menu), to
view the Debug Report.
• Using Telnet or Curl, the report is sent to your output device.
The Debug Report contains the following subsections:
1.Enumerated source: the ESI source code with line numbers prefixed to each line.
2.Environment Variables: the resulting values for the ESI-supported variables. This
includes user-defined variables.
3.Syntax messages: information about any syntax errors found.
4.Evaluation messages: the results of evaluating the ESI source code.
Nested Reports If you’re using ESI nesting—the files you’re fetching using ESI contain ESI code to
fetch other files—the nested files are also debugged. The debug reports on the nested
pages are themselves nested, appearing after the including line in the template page.
For example, in debugging template.htm, you might see following:
Debugging Section for template.htm……
……
template.htm code says to include nested.htm
begin nested.htm debugging section
nested.htm debug report
end nested.htm debug
back to next line of template.htm debug report
The Debug Report
16 The ESI Development Tool, Enhanced and Original. Akamai Confidential. NDA Required for Release
Environment Variables
The environment variables section reports all ESI-supported environment variables
and user-defined variables and their values. For example:
<EnvironmentVariables>
GEO: country_code=US,region_code=CA,georegion=246,city=SANJOSE,
dma=807,pmsa=7400,areacode=408,county=SANTACLARA,fips=06085,
lat=37.3353,long=121.8938,timezone=PST,network=reserved
HTTP_ACCEPT: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, */*
HTTP_ACCEPT_CHARSET:
HTTP_ACCEPT_ENCODING:
HTTP_ACCEPT_LANGUAGE:
HTTP_CONTENT_LENGTH: 50
HTTP_CONTENT_LOCATION:
HTTP_CONTENT_TYPE: text/html
HTTP_COOKIE:
HTTP_HOST: 127.0.0.2:4567
HTTP_REFERER:
HTTP_USER_AGENT: curl/6.2 (i686-pc-linux-gnu) libcurl 6.2
QUERY_STRING: esifrag=4
REMOTE_ADDR: 127.0.0.1
REQUEST_METHOD: GET
REQUEST_PATH: /akcontrol.jsp
HTTP_PRAGMA: no-cache
HTTP_SERVER: WebLogic 6.0 Service Pack 1 03/04/2001 22:05:05 #101616
HTTP_DATE: Mon, 07 May 2001 18:52:18 GMT
HTTP_CONNECTION: keep-alive
</EnvironmentVariables>
The ESI Development Tool, Enhanced and Original. Akamai Confidential. NDA Required for Release 17
ESI Syntax Messages
If you see a Syntax Messages section in your debug report, the page contains ESI syn-
tax errors; you won’t see it otherwise. The 1000 series messages deal with ESI syntax
only. The 2000 series (Table 2) deals with ESI processing.
Table 1: ESI Syntax Error Messages
No.Text (n = Line Number) Description
1000 Line n. Error A generic or unidentifiable error in an ESI statement.
1001 Line n. Unrecognized ESI tag An ESI opening statement is incorrect. For example,
“<esi:xyz...>” (“xyz” is not an ESI element).
1002 Line n. Unrecognized ESI attribute An attribute, such as “src” in “esi:include src,” is misspelled
or otherwise unrecognizable.
1003 Line n. Unrecognized ESI closing tag The closing statement is not recognized. For example, you
used “<esi:remove>” to open a block, and
</esi:rem> to close it.
1004 Line n. Badly constructed include tag For example, <esi:include somefile.htm/>. (The include
statement must contain an “src” before the primary object
to be fetched.)
1005 Line n. Illegal character in variable name.In the <esi:set> tag, the name must be composed of up to
256 alphanumeric characters (A-z, 0-9), and can include
underscores (_).
1006 Line n. Unknown variable type.The type specified in the <esi:set> was either not known or
was misspelled. ESI accepts only type=’string’.
1007 Line n. Missing quotes for string constant.In the short form of the <esi:set> statement, the string set
in the value attribute must be surrounded by quotes.
1008 Line n. More then one name attribute in a
<esi:set> or <esi:assign> tag.
The <esi:set> or <esi:assign> tag accepts only one name.
1009 Line n. More then one type attribute in a
<esi:set> or <esi:assign> tag.
The <esi:set> or <esi:assign> tag accepts only one type.
1010 Line n. More then one value attribute in a
<esi:set> or <esi:assign> tag.
The <esi:set> or <esi:assign> tag accepts only one value.
1011 Line n. One or more attributes are missing for
the <esi:set> or <esi:assign> tag.
The <esi:set> or <esi:assign> tag must be followed by a
value.
1012 Line n. Expecting a numerical value for attribute.A numeric value was expected but not found, for example,
with the include statement “maxwait=“.
1013 Line n. Invalid character in function name.An invalid character, such as a number or other special char-
acter, has been found in a function name.
1016 Line n, More than one name attribute in a
<esi:param> tag.
Each <esi:param> tag in an esi:include statement can
include only one name.
The Debug Report
18 The ESI Development Tool, Enhanced and Original. Akamai Confidential. NDA Required for Release
1017 Line n, More than one value attribute in a
<esi:param> tag.
Each <esi:param> tag in an esi:include statement can
include only one value.
1018 Line n. Badly constructed <esi:param> tag.This correct form is <esi:param name="name"
value="value"/>
1019 Line n. One or more attributes are missing for
the <esi:param> tag.
Each <esi:param> tag in an esi:include statement must
include a name and a value.
1020 Line n. A specified attribute must have a value Attributes must be assigned values—e.g., you cannot have
a ttl alone, it must be a ttl=t, where t is a time value.
1021 Line n. More then one item attribute in a
<esi:foreach> tag.
In the esi:foreach statement, which begins, <esi:foreach
item="My_Item" ... there can only be one item defined.
1022 Line n. More than one collection attribute in a
<esi:foreach> tag.
In the statement <esi:foreach, item="My_Item" collec-
tion="[sequence]">, there can be only one collection
attribute.
1023 Line n. Badly constructed foreach tag. Collection
attribute required.
You cannot formulate an esi:foreach statement without
specifying the collection the iteration is to work on.
1024 Line n. No rule matches syntax.An unidentified syntax error—one that did not trigger any
message between 1001–1023 —was found.
1025 Line n, An <esi:function> definition cannot be
nested inside another <esi:function> definition.
User-defined functions cannot include other user-defined
functions as part of the definition.
1026 Line n, An <esi:eval> statement cannot be
nested inside an <esi:function> definition.
You cannot place an <esi:eval> statement inside an
<esi:function> block.
1027 Line n, An <esi:return> statement must be con-
tained in an <esi:function>.
You cannot place an <esi:return> statement outside an
<esi:function> block.
1028 Line n, An <esi:break> statement must be con-
tained in a loop.
The <esi:break> statement can be placed only inside an iter-
ation loop -- the <esi:foreach> block.
Table 1: ESI Syntax Error Messages
No.Text (n = Line Number) Description
The ESI Development Tool, Enhanced and Original. Akamai Confidential. NDA Required for Release 19
Evaluation
Messages
These messages deal with ESI processing. ESI syntax and parser messages are shown
other tables. The messages fall into three categories: Info messages advise you about
general ESI processing; Warning messages occur when there has been an ESI process-
ing problem but it is not necessarily a serious error that will affect page display. Error
messages represent serious errors that will affect page display.
Table 2: Evaluation Messages
No.Type Text (n = Line Number) Comments
2000 Info Line n.Processing next branch of con-
ditional structure.
The conditional expressions evaluated to false, so ESI is pro-
ceeding to the next “otherwise” statement.
2001 Info Line n. All conditional branches failed.In this case, All conditional expressions evaluated to false,
and there is no “otherwise” block. ESI processing continues
as if there were no conditional block.
2002 Info Line n. WHEN expression evaluated
TRUE.
2003 Info Line n. WHEN expression evaluated
FALSE.
2004 Info Line n. Your code ran successfully One of these two messages—2004 or 2005—will be the last
line in the evaluation section.
2005 Error Line n. Your code did not run success-
fully
2006 Warn
ing
Line n. Failed fetching fragment
frag_name.
There could be a number of causes: e.g., the path or host for
the fragment is not specified in your configuration metadata;
the file doesn’t exist; or there is a connectivity problem
between the edge server and the origin server.
2007 Info Line n. Including fragment
frag_name.
2008 Error Line n. Failed fetching fragment
frag_name. Request hit resource
boundary.
One of two limits has been violated:
1) More than 15 levels of nesting (the initial “include” is the
first level), or
2) More than 65 “include” attempts on one page.
The 65 attempts is the sum of the includes on the initial tem-
plate plus all subsequent associated attempts, such as those
on nested pages.
The limit is for both “src” and “alt” attempts. A fetch on the
“alt” object is only attempted and counted if the “src” fails.
In processing a page, the edge server attempts all “src”
objects before attempting to fetch “alt” objects.
2009 Error Line n. Failed fetching fragment
frag_name. Error in path or host.
The path specified in the code contains illegal characters or
other format errors.
2010 Error Your code is too big. Your total file
size must be less than xx bytes.
The sum of the sizes of files to be fetched and included,
including nested objects, exceeds 1 megabyte (the default).
The Debug Report
20 The ESI Development Tool, Enhanced and Original. Akamai Confidential. NDA Required for Release
2011 Info The document contains no ESI tags.The file was nominated for ESI parsing by the configuration
file or Edge-control header metadata, but no ESI tags were
found in the file.
2012 Error Line n. Bad regular expression “text." A regular expression was formed incorrectly in the matches
operator.
2013 Error A processor of type type1 may only
instantiate a processor of the same
type. It is trying to instantiate a pro-
cessor of type type2. This is not
allowed. Please modify your metadata
or response headers to instantiate the
correct type of processor.
Currently, this means that an XSLT parent cannot include an
ESI fragment.
2014 Error Line n. Unknown processing specified.
dca must be one of none, esi, or aka-
maizer.
The dca attribute of the esi:include statement can be one of
the four values.
2016 Info Your ESI source file is too large to dis-
play the line numbers with the source.
Only ESI source code less than %d
bytes will show line numbers in the
debug output.
To be processed by ESI, the source file size must be less than
1 MB (see Number 2010). However, the size that can be
included in the debug message is smaller. The maximum
value is currently 200,000 bytes. The entire report is sent; but
the source code is not enumerated.
2017 Error You are attempting to include a file
fragment without processing the frag-
ment. Either a) the fragment and the
container page must be from the
same hostname or b) your edge server
configuration must be set up to
enable the fragment to be included
from any hostname.
You have attempted to include a fragment that is not known
to the edge server. The fragment must either be from the
same host name, or ESI processing must be enabled in your
edge server configuration file. If the configuration is set not
to require strict domain checking, that setting must be
enabled for the fragment’s URI, not the template’s, to avoid
this error.
2018 Error You are attempting to include a
stylesheet from a different hostname
than the xml file. Your xml uses the
hostname ’%s’. Your stylesheet uses
the hostname ’%s’. Either a) the
stylesheet and the xml page must be
from the same hostname or b) your
edge server configuration must be set
up to enable the xml file to include a
stylesheet from any hostname.
You have attempted to include a fragment that is not known
to the edge server. The fragment must either be from the
same host name, or you must enable processing a stylesheet
from any host name in your edge server configuration file.
2019 Info Setting stylesheet global param -
\"%s\" value - \’%s\’.
This reports the value you set with an esi:param name
attribute.
2020 Error Function [name] fails.The named function has failed to evaluate.
2021 Error Unknown function name [name].A function name was used that ESI does not recognize.
2023 Info Function [name] returns value: [value].Reports the value returned by a function
Table 2: Evaluation Messages
No.Type Text (n = Line Number) Comments
The ESI Development Tool, Enhanced and Original. Akamai Confidential. NDA Required for Release 21
2024 Error Line n. Multibyte characters cannot be
evaluated in a regular expression
The has_i, matches, and matches_i, operators cannot be
used with multibyte characters.
2025 Error Multibyte characters are not allowed
in $list_delitem()
The $list_delitem() function does not accept multibyte char-
acters.
2026 Error $from/to_utf8() may only be used on
multibyte pages.
The $convert_to_unicode() or $convert_from_unicode() was
used on a page that is not set up for multibyte encoding.
2028 Error Transcoding from EncodingA to
EncodingB failed.
A transcoding failed using $convert_to_unicode() or
$convert_from_unicode() to convert between one encoding
(EncodingA) and another (EncodingB).
2029 Error Bad regular expression “abc” The Akamaizer, used to Akamaize ESI pages, found a bad
regular expression.
2030 Error Unknown replacement regex “def” The Akamaizer could not read the replacement regular
expression.
2031 Error'$(' sign not closed in regex replace-
ment.
The Akamaizer found the beginning of a variable $(, but no
closing paren ).
2032 Info Replacing object abc with def.Akamaizer success message: replacing one object with
another.
2033 Info Testing object abc against regex def.Akamaizer message: testing the object against the regex
expression.
2034 Info Source encoding detected: charset.Using a multibyte character set, ESI has detected and is using
the reported character set.
2035 Error The maximum limit (n1) of substitu-
tions was reached: subst = n2
When using the Akamaizer, the maximum number of back
references and variable references in the substitution expres-
sion has been reached. The maximum is 100.
2036 Error The maximum request size of n1 bytes
was exceeded. Current size: n2 bytes
A forward request generated by ESI cannot exceed a certain
size. Currently, that size is 64K, but that is subject to change.
2037 Error The maximum header value size of n
bytes was exceeded. Value truncated.
A header value (set via $set_header or $set_redirect) cannot
exceed a certain size. Currently, that size is 60000 bytes but
that is subject to change.
2038 Info This processor of type '%s' is formed
through daisy chaining.
This Informational message states how a processor (e.g.
dca=esi->akamaizer, etc.) is created.
2039 Error You have attempted to instantiate a
fragment with an unknown processor
type.
The processor type can only be esi, akamaizer, or none.
2040 Error Invalid url requested: URL An error parsing a URI, usually in an <esi:include>
Table 2: Evaluation Messages
No.Type Text (n = Line Number) Comments
The Debug Report
22 The ESI Development Tool, Enhanced and Original. Akamai Confidential. NDA Required for Release
2041 Error An <esi:break> statement was
detected outside of a loop - probably
in a function definition
The <esi:break> statement can be placed only inside an itera-
tion loop -- the <esi:foreach> block.
2042 Error Maximum depth of user defined func-
tions exceeded ( %d >= %d )
You can set up recursion inside a user-defined function, but
not to a level greater than that set in configuration.
2043 Error Line n. You are trying to run a request
using a processor type of type '%s'.
You are not authorized to use this
type of processor.
If your configuration is not set up to allow for the processor
type—for example, ESI—you cannot call that processor in
your ESI code, for example, as an <esi:include> dca=proces-
sor attribute.
2044 Error You are using too many includes on
your page. You are only allowed to
use %d includes.
The maximum number of includes allowed is, by default, 65,
when including the current page and any nested pages. This
is configurable in your edge server configuration but too
many includes can also impact performance.
2045 Error You are exceeding the recursion limit
of %d levels.
The maximum number of nested includes is, by default, 15,
starting with the main template. This is configurable in your
edge server configuration but too many levels can also
impact performance.
Table 2: Evaluation Messages
No.Type Text (n = Line Number) Comments
Sample ESI Debug Report
The ESI Development Tool, Enhanced and Original. Akamai Confidential. NDA Required for Release 23
Sample ESI Debug Report
<style>.hide {display:none;}</style>
<SPAN class=“hide”>
/********************Debugging Section*********************/
<Debug>
<Source>
The Debugging Section, not
displayed in the normal
browser window
1 <html>
2 <header>
3 ESI ’contains’ feature test
4 <header>
5 <body>
6 This is an ESI contains feature test, using ’has’ inside a when tag.
7
8 Checking if the user agent contains the combination ’OTH’ in it.
<br>
9 <esi:choose>
10 <esi:when test=“$(HTTP_USER_AGENT{’os’}) has ’OTH’”>
11 <esi:include src=“http://xyz.akamai.com/esi/other.html”/>
12 </esi:when>
13 <esi:otherwise>
14 OS doesn’t include OTH.
15 </esi:otherwise>
16 </esi:choose>
17 <br>
18
19 Checking if the user cookie contains the combination ’name’
somewhere
20 in it. <br>
21 <esi:choose>
22 <esi:when test=“$(HTTP_COOKIE) has ’name’”>
23 HTTP_COOKIE includes ’name’: $(HTTP_COOKIE)<br>
24 </esi:when>
25 <esi:otherwise>
26 HTTP_COOKIE does not include ’name’ <br>
27 </esi:otherwise>
28 </esi:choose>
29 <br>
30
31 Checking if the query string contains the combination ’val’
somewhere
32 in it. <br>
33 <esi:choose>
34 <esi:when test=“$(QUERY_STRING) has ’val’”>
35 QUERY_STRING has val: $(QUERY_STRING)<br>
36 </esi:when>
37 <esi:otherwise>
38 QUERY_STRING does not contain ’val’ <br>
39 </esi:otherwise>
40 </esi:choose>
41 <br>
42
43 Checking if the query string value of ’val’ contains ’abc’
44 in it. <br>
45 <esi:choose>
46 <esi:when test=“$(QUERY_STRING{’val’}) has ’abc’”>
47 QUERY_STRING{’val’} has abc: $(QUERY_STRING{’val’})<br>
48 </esi:when>
The Debug Report
24 The ESI Development Tool, Enhanced and Original. Akamai Confidential. NDA Required for Release
49 <esi:otherwise>
50 QUERY_STRING{’val’} does not contain ’abc’ <br>
51 </esi:otherwise>
52 </esi:choose>
53 <br>
56
57 </body>
58 </Source>
Environment Variables
Subsection (this example
shows no user-defined
variables)
<EnvironmentVariables>
GEO: country_code=US,region_code=CA,georegion=246,city=SANJOSE,
dma=807,pmsa=7400,areacode=408,county=SANTACLARA,fips=06085,
lat=37.3353,long=121.8938,timezone=PST,network=reserved
HTTP_ACCEPT: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, */*
HTTP_ACCEPT_CHARSET:
HTTP_ACCEPT_ENCODING:
HTTP_ACCEPT_LANGUAGE:
HTTP_CONTENT_LENGTH: 50
HTTP_CONTENT_LOCATION:
HTTP_CONTENT_TYPE: text/html
HTTP_COOKIE:
HTTP_HOST: 127.0.0.2:4567
HTTP_REFERER:
HTTP_USER_AGENT: curl/6.2 (i686-pc-linux-gnu) libcurl 6.2
QUERY_STRING: esifrag=4
REMOTE_ADDR: 127.0.0.1
REQUEST_METHOD: GET
REQUEST_PATH: /akcontrol.jsp
HTTP_PRAGMA: no-cache
HTTP_SERVER: WebLogic 6.0 Service Pack 1 03/04/2001 22:05:05 #101616
HTTP_DATE: Mon, 07 May 2001 18:52:18 GMT
HTTP_CONNECTION: keep-alive
</EnvironmentVariables>
There were no syntax errors, so there is no syntax error section
Evaluation
Subsection
<Eval>
Info[2002]: Line 12. WHEN expression evaluated TRUE.
Info[2002]: Line 24. WHEN expression evaluated TRUE.
Info[2003]: Line 36. WHEN expression evaluated FALSE.
Info[2000]: Line 40. All WHEN expressions evaluated FALSE. Processing
OTHERWISE block.
Info[2003]: Line 48. WHEN expression evaluated FALSE.
Info[2000]: Line 52. All WHEN expressions evaluated FALSE. Processing
OTHERWISE block.
Info[2007]: Line 11. Including fragment “http://xyz.akamai.com/esi/
other.html”.
Info[2004]: Your code ran successfully.
</Eval>
End Debug </Debug>
/********************End Debugging Section*****************/
Begin Display Code </SPAN>
<html>
<header>
ESI ’contains’ feature test
<header>
<body>
Sample ESI Debug Report
The ESI Development Tool, Enhanced and Original. Akamai Confidential. NDA Required for Release 25
This is an ESI contains feature test, using ’has’ inside a when tag.
Checking if the user agent contains the combination ’OTH’ in it. <br>
Begin Debug Section for
next section of ESI Code
<style>.hide {display:none;}</style>
<SPAN class=“hide”>
/********************Debugging Section*********************/
<Debug>
<Source>
1 Just a little file that says OTHER.
</Source>
Environment Variables
Subsection
<EnvironmentVariables>
HTTP_ACCEPT_LANGUAGE:
HTTP_COOKIE:
HTTP_HOST: xyz.akamai.com
HTTP_REFERER:
HTTP_USER_AGENT: Mozilla/4.0
QUERY_STRING:
GEO:
country_code=US,region_code=VA,georegion=288,city=HERNDON,dma=511,
pmsa=8840,areacode=703,county=FAIRFAX,fips=51059,lat=38.9696,long=
77.3866,timezone=EST,network=reserved
REMOTE_ADDR: 127.0.0.1
</EnvironmentVariables>
Evaluation Subsection <Eval>
Info[2004]: Your code ran successfully.
</Eval>
</Debug>
End Debug/********************End Debugging Section*****************/
</SPAN>
Begin Display Code
Just a little file that says OTHER.
<br>
Checking if the user cookie contains the combination ’name’ somewhere
in it. <br>

HTTP_COOKIE includes ’name’: first_name=somename
<br>
Checking if the query string contains the combination ’val’ somewhere
in it. <br>
QUERY_STRING does not contain ’val’ <br>
<br>
Checking if the query string value of ’val’ contains ’abc’
in it. <br>
QUERY_STRING{’val’} does not contain ’abc’ <br>
<br>
</body>
</html>
——End ESI Report——
The Debug Report
26 The ESI Development Tool, Enhanced and Original. Akamai Confidential. NDA Required for Release