You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by bu...@apache.org on 2011/02/12 01:54:14 UTC
svn commit: r785329 - in
/websites/staging/trafficserver/trunk/content/docs/trunk: ./
sdk/adding-statistics/ sdk/troubleshooting-tips/
Author: buildbot
Date: Sat Feb 12 00:54:14 2011
New Revision: 785329
Log:
Staging update by buildbot
Modified:
websites/staging/trafficserver/trunk/content/docs/trunk/STATUS
websites/staging/trafficserver/trunk/content/docs/trunk/sdk/adding-statistics/coupled-statistics.en.html
websites/staging/trafficserver/trunk/content/docs/trunk/sdk/adding-statistics/index.en.html
websites/staging/trafficserver/trunk/content/docs/trunk/sdk/adding-statistics/viewing-statistics-using-traffic-line.en.html
websites/staging/trafficserver/trunk/content/docs/trunk/sdk/troubleshooting-tips/debugging-memory-leaks.en.html
websites/staging/trafficserver/trunk/content/docs/trunk/sdk/troubleshooting-tips/index.en.html
websites/staging/trafficserver/trunk/content/docs/trunk/sdk/troubleshooting-tips/unable-to-debug-tags.en.html
websites/staging/trafficserver/trunk/content/docs/trunk/sdk/troubleshooting-tips/unable-to-load-plugins.en.html
websites/staging/trafficserver/trunk/content/docs/trunk/sdk/troubleshooting-tips/using-a-debugger.en.html
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/STATUS
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/STATUS (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/STATUS Sat Feb 12 00:54:14 2011
@@ -17,7 +17,7 @@ To Do List
- invent a wheel that will help translators and users spot out-dated documents
-- migrate the content - this is happening as we speak!
+- migrate the content - SDK is done. Admin guide is pending.
- update the content: https://issues.apache.org/jira/secure/IssueNavigator.jspa?component=12313124
@@ -28,8 +28,6 @@ Migration procedure
- This requires Ruby 1.9.x
-- Please use the list below to mark the chapter you're currently working on.
-
- ex: ./html2markdown http://trafficserver.apache.org/docs/v2/sdk/HTTP_Transactions > http-hooks-and-transactions/http-transactions.en.mdtext
- take a look at the chapters which are done already for inspiration.
@@ -43,33 +41,6 @@ Migration procedure
https://issues.apache.org/jira/browse/TS-538 and it's ink-2-ts.sh
-- Lastly: Update the STATUS file with your findings, or just to tick off the
- items on the TO DO List :)
-
-========================
-
-index.en.mdtext -- igalic
-preface -- igalic
-getting-started -- igalic
-how-to-create-trafficserver-plugins -- igalic
-remap-plugin -- igalic
-header-based-plugin-examples -- igalic
-http-transformation-plugin -- igalic
-new-protocol-plugins -- igalic
-cache-plugin -- igalic
-http-hooks-and-transactions -- igalic
-misc-interface-guide -- igalic
-http-headers -- igalic
-mutex-guide -- igalic
-continuations -- igalic
-plugin-configurations -- igalic
-actions-guide -- igalic
-io-guide -- igalic
-plugin-management -- igalic
-adding-statistics
-sample-source-code --igalic
-troubleshooting-tips
-
Findings
=================
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/adding-statistics/coupled-statistics.en.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/adding-statistics/coupled-statistics.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/adding-statistics/coupled-statistics.en.html Sat Feb 12 00:54:14 2011
@@ -6,8 +6,8 @@
<link rel="stylesheet" href="/styles/pygments_style.css" />
- <title></title>
-
+ <title>Apache Traffic Server⢠Software Developers Kit</title>
+ <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at . http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -->
</head>
<body>
@@ -15,11 +15,106 @@
<span id="ts_logo">
<a href="http://trafficserver.apache.org/"><img alt="Apache Traffic Server" src="/images/ts75.png" /></a>
</span>
- <h1></h1>
+ <h1>Apache Traffic Server⢠Software Developers Kit</h1>
</div>
<div id="content">
-
+ <p><a href="../adding-statistics">Prev</a> - Adding Statistics</p>
+<p>Viewing Statistics Using Traffic Line - <a href="viewing-statistics-using-traffic-line">Next</a></p>
+<h2 id="CoupledStatistics">Coupled Statistics</h2>
+<p>Use coupled statistics for quantities that are related and therefore must be
+updated jointly. </p>
+<p>As a very simple example, suppose you have three statistics: <code>sum</code>, <code>part_1</code>,
+and <code>part_2</code>. They must always preserve the relationship that <code>sum = part_1
++ part_2</code>. If you update <code>part_1</code> without updating <code>sum</code> at the same time,
+then the equation becomes untrue. Therefore, the statistics are said to be
+<em>coupled</em>. </p>
+<p>The mechanism for updating coupled statistics jointly is to create local copies
+of global coupled statistics in the routines that modifiy them. When each local
+copy is updated appropriately, do a global update using <code>TSStatsCoupledUpdate</code>.
+To specify which statistics are related to one another, establish a coupled
+statistic category and make sure that each coupled statistic belongs to the
+appropriate category. When it is time to do the global update, specify the
+category to be updated.</p>
+<p><img alt="[Note]" src="/images/docbook/note.png" /></p>
+<p><strong>Note</strong> </p>
+<p>The local statistic copy must have a duplicate set of statistics as that of
+the master copy. Local statistics must also be added to the local statistic
+category in the same order as their master copy counterparts were originally
+added.</p>
+<p>Below are the steps you need to follow, along with a code example taken from
+the <code>redirect-1.c</code> sample plugin.</p>
+<h3 id="addcoupledstatistics">To add coupled statistics:</h3>
+<ol>
+<li>
+<p>Declare the global category for your coupled statistics as a global <code>TSCoupledStat</code>
+variable in your plugin.</p>
+</li>
+<li>
+<p>Declare your coupled statistics as global <code>TSStat</code> variables in your plugin. </p>
+</li>
+<li>
+<p>In <code>TSPluginInit</code>, create a new global coupled category using <code>TSStatCoupledGlobalCategoryCreate</code>. </p>
+</li>
+<li>
+<p>In <code>TSPluginInit</code>, create new global coupled statistics using <code>TSStatCoupledGlobalAdd</code>.
+When you create a new statistic, you need to give it an "external" name that
+the Traffic Server command line interface (Traffic Line) uses to access the
+statistic.</p>
+</li>
+<li>
+<p>In any routine wherein you want to modify (increment, decrement, or other modification)
+your coupled statistics, declare local copies of the coupled category and coupled
+statistics.</p>
+</li>
+<li>
+<p>Create local copies using <code>TSStatCoupledLocalCopyCreate</code> and <code>TSStatCoupledLocalAdd</code>. </p>
+</li>
+<li>
+<p>Modify the local copies of your statistics. Then call <code>TSStatsCoupledUpdate</code>
+to update the global copies jointly.</p>
+</li>
+<li>
+<p>When you are finished, you must destroy all of the local copies in the category
+via <code>TSStatCoupledLocalCopyDestroy</code>.</p>
+</li>
+</ol>
+<h3 id="ExampleUsingredirect-1.cSamplePlugin">Example Using the redirect-1.c Sample Plugin</h3>
+<div class="codehilite"><pre><span class="k">static</span> <span class="n">TSCoupledStat</span> <span class="n">request_outcomes</span><span class="p">;</span>
+
+<span class="k">static</span> <span class="n">TSStat</span> <span class="n">requests_all</span><span class="p">;</span>
+<span class="k">static</span> <span class="n">TSStat</span> <span class="n">requests_redirects</span><span class="p">;</span>
+<span class="k">static</span> <span class="n">TSStat</span> <span class="n">requests_unchanged</span><span class="p">;</span>
+
+<span class="n">request_outcomes</span> <span class="o">=</span> <span class="n">TSStatCoupledGlobalCategoryCreate</span> <span class="p">(</span><span class="s">"request_outcomes"</span><span class="p">);</span>
+
+<span class="n">requests_all</span> <span class="o">=</span> <span class="n">TSStatCoupledGlobalAdd</span> <span class="p">(</span><span class="n">request_outcomes</span><span class="p">,</span> <span class="s">"requests.all"</span><span class="p">,</span> <span class="n">TSSTAT_TYPE_FLOAT</span><span class="p">);</span>
+<span class="n">requests_redirects</span> <span class="o">=</span> <span class="n">TSStatCoupledGlobalAdd</span> <span class="p">(</span><span class="n">request_outcomes</span><span class="p">,</span> <span class="s">"requests.redirects"</span><span class="p">,</span>
+ <span class="n">TSSTAT_TYPE_INT64</span><span class="p">);</span>
+<span class="n">requests_unchanged</span> <span class="o">=</span> <span class="n">TSStatCoupledGlobalAdd</span> <span class="p">(</span><span class="n">request_outcomes</span><span class="p">,</span> <span class="s">"requests.unchanged"</span><span class="p">,</span>
+ <span class="n">TSSTAT_TYPE_INT64</span><span class="p">);</span>
+
+<span class="n">TSCoupledStat</span> <span class="n">local_request_outcomes</span><span class="p">;</span>
+<span class="n">TSStat</span> <span class="n">local_requests_all</span><span class="p">;</span>
+<span class="n">TSStat</span> <span class="n">local_requests_redirects</span><span class="p">;</span>
+<span class="n">TSStat</span> <span class="n">local_requests_unchanged</span><span class="p">;</span>
+
+<span class="n">local_request_outcomes</span> <span class="o">=</span> <span class="n">TSStatCoupledLocalCopyCreate</span><span class="p">(</span><span class="s">"local_request_outcomes"</span><span class="p">,</span>
+ <span class="n">request_outcomes</span><span class="p">);</span>
+<span class="n">local_requests_all</span> <span class="o">=</span> <span class="n">TSStatCoupledLocalAdd</span><span class="p">(</span><span class="n">local_request_outcomes</span><span class="p">,</span> <span class="s">"requests.all.local"</span><span class="p">,</span>
+ <span class="n">TSSTAT_TYPE_FLOAT</span><span class="p">);</span>
+<span class="n">local_requests_redirects</span> <span class="o">=</span> <span class="n">TSStatCoupledLocalAdd</span><span class="p">(</span><span class="n">local_request_outcomes</span><span class="p">,</span>
+ <span class="s">"requests.redirects.local"</span><span class="p">,</span> <span class="n">TSSTAT_TYPE_INT64</span><span class="p">);</span>
+<span class="n">local_requests_unchanged</span> <span class="o">=</span> <span class="n">TSStatCoupledLocalAdd</span><span class="p">(</span><span class="n">local_request_outcomes</span><span class="p">,</span>
+ <span class="s">"requests.unchanged.local"</span><span class="p">,</span> <span class="n">TSSTAT_TYPE_INT64</span><span class="p">);</span>
+
+<span class="n">TSStatFloatAddTo</span><span class="p">(</span> <span class="n">local_requests_all</span><span class="p">,</span> <span class="mf">1.0</span> <span class="p">)</span> <span class="p">;</span>
+<span class="p">...</span>
+<span class="n">TSStatIncrement</span> <span class="p">(</span><span class="n">local_requests_unchanged</span><span class="p">);</span>
+<span class="n">TSStatsCoupledUpdate</span><span class="p">(</span><span class="n">local_request_outcomes</span><span class="p">);</span>
+
+<span class="n">TSStatCoupledLocalCopyDestroy</span><span class="p">(</span><span class="n">local_request_outcomes</span><span class="p">);</span>
+</pre></div>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/adding-statistics/index.en.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/adding-statistics/index.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/adding-statistics/index.en.html Sat Feb 12 00:54:14 2011
@@ -6,8 +6,8 @@
<link rel="stylesheet" href="/styles/pygments_style.css" />
- <title></title>
-
+ <title>Apache Traffic Server⢠Software Developers Kit</title>
+ <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at . http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -->
</head>
<body>
@@ -15,11 +15,67 @@
<span id="ts_logo">
<a href="http://trafficserver.apache.org/"><img alt="Apache Traffic Server" src="/images/ts75.png" /></a>
</span>
- <h1></h1>
+ <h1>Apache Traffic Server⢠Software Developers Kit</h1>
</div>
<div id="content">
-
+ <p><a href="../plugin-management/guide-to-the-logging-api">Prev</a> - Guide to the Logging API</p>
+<p>Coupled Statistics - <a href="coupled-statistics">Next</a></p>
+<h2 id="AddingStatistics">Adding Statistics</h2>
+<p>This chapter describes how to add statistics to your plugins. Statistics can
+be coupled or uncoupled; <strong>coupled</strong> statistics are quantities that are related
+and must therefore be updated together. The Traffic Server API statistics functions
+add your plugin's statistics to the Traffic Server statistics system. You can
+view your plugin statistics as you would any other Traffic Server statistic,
+using Traffic Line (Traffic Server's command line interface). This chapter
+contains the following topics:</p>
+<ul>
+<li>
+<p><a href="#UncoupledStatistics">Uncoupled Statistics</a></p>
+</li>
+<li>
+<p><a href="coupled-statistics">Coupled Statistics</a></p>
+</li>
+<li>
+<p><a href="ViewStatsUsingTrafLine.html">Viewing Statistics Using Traffic Line</a></p>
+</li>
+</ul>
+<h2 id="UncoupledStatistics">Uncoupled Statistics</h2>
+<p>A statistic is an object of type <code>TSStat</code>. The value of the statistic is of
+type <code>TSStatType</code>. The possible <code>TSStatTypes</code> are:</p>
+<ul>
+<li>
+<p><code>TSSTAT_TYPE_INT64</code></p>
+</li>
+<li>
+<p><code>TSSTAT_TYPE_FLOAT</code></p>
+</li>
+</ul>
+<p>There is <em>no</em> <code>TSSTAT_TYPE_INT32</code>.</p>
+<p>To add uncoupled statistics, follow the steps below:</p>
+<ol>
+<li>
+<p>Declare your statistic as a global variable in your plugin. For example:</p>
+<div class="codehilite"><pre><span class="k">static</span> <span class="n">TSStat</span> <span class="n">my_statistic</span><span class="p">;</span>
+</pre></div>
+
+
+</li>
+<li>
+<p>In <code>TSPluginInit</code>, create new statistics using <code>TSStatCreate</code>.
+When you create a new statistic, you need to give it an "external" name that
+the Traffic Server command line interface (Traffic Line) uses to access the
+statistic. For example:</p>
+<div class="codehilite"><pre><span class="n">my_statistic</span> <span class="o">=</span> <span class="n">TSStatCreate</span> <span class="p">(</span><span class="s">"my.statistic"</span><span class="p">,</span> <span class="n">TSSTAT_TYPE_INT64</span><span class="p">);</span>
+</pre></div>
+
+
+</li>
+<li>
+<p>Modify (increment, decrement, or other modification) your statistic in plugin
+functions.</p>
+</li>
+</ol>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/adding-statistics/viewing-statistics-using-traffic-line.en.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/adding-statistics/viewing-statistics-using-traffic-line.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/adding-statistics/viewing-statistics-using-traffic-line.en.html Sat Feb 12 00:54:14 2011
@@ -6,8 +6,8 @@
<link rel="stylesheet" href="/styles/pygments_style.css" />
- <title></title>
-
+ <title>Apache Traffic Server⢠Software Developers Kit</title>
+ <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at . http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -->
</head>
<body>
@@ -15,11 +15,25 @@
<span id="ts_logo">
<a href="http://trafficserver.apache.org/"><img alt="Apache Traffic Server" src="/images/ts75.png" /></a>
</span>
- <h1></h1>
+ <h1>Apache Traffic Server⢠Software Developers Kit</h1>
</div>
<div id="content">
-
+ <p><a href="CoupledStatistics.html">Prev</a> - Coupled Statistics</p>
+<p>Sample Source Code - <a href="../sample-source-code">Next</a></p>
+<h2 id="ViewingStatisticsUsingTrafficLine">Viewing Statistics Using Traffic Line</h2>
+<p>To view statistics for your plugin, follow the steps below:</p>
+<ol>
+<li>
+<p>Make sure you know the name of your statistic (i.e., the name used in the <code>TSStatCoupledGlobalAdd</code>,
+<code>TSStatCreate</code>, or <code>TSStatCoupledGlobalCategoryCreate</code> call).</p>
+</li>
+<li>
+<p>In your <code><Traffic Server>/bin</code> directory, enter the following:</p>
+<p>::::text
+ ./traffic_line -r the_name</p>
+</li>
+</ol>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/troubleshooting-tips/debugging-memory-leaks.en.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/troubleshooting-tips/debugging-memory-leaks.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/troubleshooting-tips/debugging-memory-leaks.en.html Sat Feb 12 00:54:14 2011
@@ -6,8 +6,8 @@
<link rel="stylesheet" href="/styles/pygments_style.css" />
- <title></title>
-
+ <title>Apache Traffic Server⢠Software Developers Kit</title>
+ <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at . http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -->
</head>
<body>
@@ -15,11 +15,21 @@
<span id="ts_logo">
<a href="http://trafficserver.apache.org/"><img alt="Apache Traffic Server" src="/images/ts75.png" /></a>
</span>
- <h1></h1>
+ <h1>Apache Traffic Server⢠Software Developers Kit</h1>
</div>
<div id="content">
-
+ <p><a href="using-a-debugger">Prev</a> - Using a Debugger</p>
+<h2 id="DebuggingMemoryLeaks">Debugging Memory Leaks</h2>
+<p>Memory leaks in a plugin can be detected using e.g. an MRTG graph related to
+memory - you can use memory dump information.
+Enable <code>mem dump</code> in <code>records.config</code> as follows:</p>
+<div class="codehilite"><pre> CONFIG proxy.config.dump_mem_info_frequency INT <value>
+</pre></div>
+
+
+<p>This causes Traffic Server to dump memory information to <code>traffic.out</code> at <code><value></code>
+(intervals are in seconds). A zero value means that it is disabled.</p>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/troubleshooting-tips/index.en.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/troubleshooting-tips/index.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/troubleshooting-tips/index.en.html Sat Feb 12 00:54:14 2011
@@ -6,8 +6,8 @@
<link rel="stylesheet" href="/styles/pygments_style.css" />
- <title></title>
-
+ <title>Apache Traffic Server⢠Software Developers Kit</title>
+ <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at . http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -->
</head>
<body>
@@ -15,11 +15,46 @@
<span id="ts_logo">
<a href="http://trafficserver.apache.org/"><img alt="Apache Traffic Server" src="/images/ts75.png" /></a>
</span>
- <h1></h1>
+ <h1>Apache Traffic Server⢠Software Developers Kit</h1>
</div>
<div id="content">
-
+ <p><a href="../sample-source-code">Prev</a> - Sample Source Code</p>
+<p>Unable to Load Plugins - <a href="unable-to-load-plugins">Next</a></p>
+<h2 id="TroubleshootingTips">Troubleshooting Tips</h2>
+<p>This appendix lists the following troubleshooting tips.</p>
+<ul>
+<li>
+<p><a href="#Trouble_CompilePlugins">Unable to Compile Plugins</a> </p>
+</li>
+<li>
+<p><a href="unable-to-load-plugins">Unable to Load Plugins</a></p>
+</li>
+<li>
+<p><a href="unable-to-debug-tags">Using Debug Tags</a></p>
+</li>
+<li>
+<p><a href="using-a-debugger">Using a Debugger</a></p>
+</li>
+<li>
+<p><a href="debugging-memory-leaks">Debugging Memory Leaks</a></p>
+</li>
+</ul>
+<h2 id="UnableCompilePlugins">Unable to Compile Plugins</h2>
+<p>The process for compiling a shared library varies with the platform used, so
+the Traffic Server API includes the <code>tsxs</code> script you can use to create
+shared libraries on all supported Traffic Server platforms.</p>
+<h3 id="Example">Example</h3>
+<p>Assuming the sample program is stored in the file <code>hello-world.c</code>, you could
+use the following commands to building a shared library:</p>
+<div class="codehilite"><pre> tsxs -c hello-world.c -o hello-world.so
+</pre></div>
+
+
+<p>To install this plugin in your <code>plugindir</code> use the equivalent of sudo on
+your platform to execute:</p>
+<div class="codehilite"><pre> sudo tsxs -o hello-world.so -i
+</pre></div>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/troubleshooting-tips/unable-to-debug-tags.en.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/troubleshooting-tips/unable-to-debug-tags.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/troubleshooting-tips/unable-to-debug-tags.en.html Sat Feb 12 00:54:14 2011
@@ -6,8 +6,8 @@
<link rel="stylesheet" href="/styles/pygments_style.css" />
- <title></title>
-
+ <title>Apache Traffic Server⢠Software Developers Kit</title>
+ <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at . http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -->
</head>
<body>
@@ -15,11 +15,63 @@
<span id="ts_logo">
<a href="http://trafficserver.apache.org/"><img alt="Apache Traffic Server" src="/images/ts75.png" /></a>
</span>
- <h1></h1>
+ <h1>Apache Traffic Server⢠Software Developers Kit</h1>
</div>
<div id="content">
-
+ <p><a href="unable-to-load-plugins">Prev</a> - Unable to Load Plugins</p>
+<p>Using a Debugger - <a href="using-a-debugger">Next</a></p>
+<h2 id="UsingDebugTags">Using Debug Tags</h2>
+<p>Use the API <code>void TSDebug (const char *tag, const char *format_str, ...)</code>
+to add traces in your plugin. In this API:</p>
+<ul>
+<li>
+<p><code>tag</code> is the Traffic Server parameter that enables Traffic Server to print
+out <em><code>format_str</code></em></p>
+</li>
+<li>
+<p><code>...</code> is a variable for <em><code>format_str</code></em></p>
+</li>
+</ul>
+<p>Run Traffic Server with the <code>-Ttag</code> option. For example, if the tag is
+<code>my-plugin</code>, then the debug output goes to <code>traffic.out.</code>See below:</p>
+<div class="codehilite"><pre> traffic_server -T"my-plugin"
+</pre></div>
+
+
+<p>Set the following variables in <code>records.config</code> (in the Traffic Server <code>config</code>
+directory):</p>
+<div class="codehilite"><pre> proxy.config.diags.debug.enabled INT 1
+ proxy.config.diags.debug.tags STRING debug-tag-name
+</pre></div>
+
+
+<p>In this case, debug output goes to <code>traffic.out</code>.</p>
+<p>Example:</p>
+<div class="codehilite"><pre> <span class="n">TSDebug</span> <span class="p">(</span><span class="s">"my-plugin"</span><span class="p">,</span> <span class="s">"Starting my-plugin at %d</span><span class="se">\n</span><span class="s">"</span><span class="p">,</span> <span class="n">the_time</span><span class="p">);</span><span class="err">`</span>
+</pre></div>
+
+
+<p>The statement <code>"Starting my-plugin at <time>"</code> appears whenever you run Traffic
+Server with the <code>my-plugin</code> tag:</p>
+<div class="codehilite"><pre> traffic_server -T"my-plugin"
+</pre></div>
+
+
+<h3 id="OtherUsefulInternalDebugTags">Other Useful Internal Debug Tags</h3>
+<p>Traffic Server provides many debug tags for internal debugging purposes. Some
+of the useful HTTP debug tags are:</p>
+<ul>
+<li>
+<p><code>http_hdrs</code> - traces all incoming and outgoing HTTP headers.</p>
+</li>
+<li>
+<p><code>http.*</code> - traces all the STTP SM debug statements.</p>
+</li>
+<li>
+<p><code>sdk</code> - gives some warning concerning API usage.</p>
+</li>
+</ul>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/troubleshooting-tips/unable-to-load-plugins.en.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/troubleshooting-tips/unable-to-load-plugins.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/troubleshooting-tips/unable-to-load-plugins.en.html Sat Feb 12 00:54:14 2011
@@ -6,8 +6,8 @@
<link rel="stylesheet" href="/styles/pygments_style.css" />
- <title></title>
-
+ <title>Apache Traffic Server⢠Software Developers Kit</title>
+ <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at . http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -->
</head>
<body>
@@ -15,11 +15,34 @@
<span id="ts_logo">
<a href="http://trafficserver.apache.org/"><img alt="Apache Traffic Server" src="/images/ts75.png" /></a>
</span>
- <h1></h1>
+ <h1>Apache Traffic Server⢠Software Developers Kit</h1>
</div>
<div id="content">
-
+ <p><a href="../troubleshooting-tips">Prev</a> - Troubleshooting Tips</p>
+<p>Using Debug Tags - <a href="unable-to-debug-tags">Next</a></p>
+<h2 id="UnableLoadPlugins">Unable to Load Plugins</h2>
+<p>To load plugins, follow the steps below.</p>
+<ol>
+<li>
+<p>Make sure that your plugin source code contains an <code>TSPluginInit</code>
+initialization function.</p>
+</li>
+<li>
+<p>Compile your plugin source code, creating a shared library.</p>
+</li>
+<li>
+<p>Add an entry to the <code>plugin.config</code> file for your plugin.</p>
+</li>
+<li>
+<p>Add the path to your plugin shared library to the <code>records.config</code> file.</p>
+</li>
+<li>
+<p>Restart Traffic Server.</p>
+</li>
+</ol>
+<p>For detailed information about each step above, refer to
+<a href="../getting-started/a-simple-plugin">A Simple Plugin</a>.</p>
</div>
<div id="footer">
Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/troubleshooting-tips/using-a-debugger.en.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/troubleshooting-tips/using-a-debugger.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/troubleshooting-tips/using-a-debugger.en.html Sat Feb 12 00:54:14 2011
@@ -6,8 +6,8 @@
<link rel="stylesheet" href="/styles/pygments_style.css" />
- <title></title>
-
+ <title>Apache Traffic Server⢠Software Developers Kit</title>
+ <!-- Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at . http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -->
</head>
<body>
@@ -15,11 +15,31 @@
<span id="ts_logo">
<a href="http://trafficserver.apache.org/"><img alt="Apache Traffic Server" src="/images/ts75.png" /></a>
</span>
- <h1></h1>
+ <h1>Apache Traffic Server⢠Software Developers Kit</h1>
</div>
<div id="content">
-
+ <p><a href="unable-to-debug-tags">Prev</a> - Using Debug Tags</p>
+<p>Debugging Memory Leaks - <a href="debugging-memory-leaks">Next</a></p>
+<h2 id="UsingaDebugger">Using a Debugger</h2>
+<p>A debugger can set breakpoints in a plugin. Use a Traffic Server debug build
+and compile the plugin with the <code>-g</code> option. A debugger can also be used to
+analyze a core dump. To generate core, set the size limit of the core files
+in the <code>records.config</code> file to -1 as follows:</p>
+<div class="codehilite"><pre><span class="n">CONFIG</span> <span class="n">proxy</span><span class="p">.</span><span class="n">config</span><span class="p">.</span><span class="n">core_limit</span> <span class="n">INT</span> <span class="o">-</span><span class="mi">1</span>
+</pre></div>
+
+
+<p>This is the equivalent of setting <code>ulimit -c unlimited</code></p>
+<h3 id="DebuggingTips">Debugging Tips:</h3>
+<ul>
+<li>
+<p>Use a Traffic Server debug version.</p>
+</li>
+<li>
+<p>Use assertions in your plugin (<code>TSAssert</code>/<code>TSReleaseAssert</code>).</p>
+</li>
+</ul>
</div>
<div id="footer">